Skip to content

feat!: add swimming, diving and climbing out for Player and Person - #76

Merged
anistark merged 1 commit into
mainfrom
feat/swimming
Nov 15, 2026
Merged

anistark merged 1 commit into
mainfrom
feat/swimming

Conversation

@anistark

Copy link
Copy Markdown
Contributor

Open water you can get into: the Player wades, swims, dives and climbs out, and every Person swims. Ocean, Lake and Pool publish where their surface is, so nothing is wired per world.

Water registry (@runek/core)

  • useWater(body), waterAt(waters, x, top, z), planeWater(object, size, { wave, depth }) and useWorld().waters
  • Ocean and Lake report their swell from a JS twin of the shader wave (surfaces/water.ts), so a swimmer rides the surface that is drawn
  • Pool reports its floor, so a room under one stays dry

Player

  • Wades from the knee up, swims where the still water is over half its height, and stands again a little shallower so a slope doesn't flip it
  • Afloat on a buoyancy spring with the swell fed forward; swimSpeed, swimSprintSpeed and swim={false}
  • Leaving the ground over deep water while moving is a dive, then a glide back up
  • Swimming into a bank, a step or a ledge up to 0.6 m over the surface lifts it out
  • The logic is plain numbers in player/swim.ts, run in useBeforePhysicsStep so it lands after ecctrl's pushes

Person

  • Strokes as canonical humanoid poses in person/swim.ts: tread, breaststroke, front crawl and a dive streamline, picked by speed
  • A carried body follows PlayerMotion.swim; a figure on its own treads where it is placed in deep water and swims the wet stretch of its route
  • Names, bubbles and prompts ride over a swimmer's head
  • PoseSource gets an optional swim(ctx, out); a source without it isn't asked in the water

Breaking changes

  • A Player no longer walks the bed under an Ocean, Lake or Pool, and water slows its walk from the knee up
  • A Person placed in water over half its height floats up to the surface
  • swim={false} on either restores the old behavior; migration notes are added for both, keyed to the next minor

Found along the way, not fixed here

  • The stock Player can't climb Pool's 0.4 m corner steps, with or without this change, so swimmers leave over the rim
  • Terrain's island falloff makes a 55 to 65 degree shore, past what ecctrl walks; the water carries a swimmer up it, but the last half meter is slow
  • No underwater view, splashes or climbing pose yet, and the third-person camera rides at the surface while swimming

Testing: just check is green (408 tests, 46 new in water.test.ts, player/swim.test.ts and person/swim.test.ts). Walked in the workshop's play mode on the island template's nodes: wade, swim, sprint, tread, dive off the dock, climb back onto it, first person, a placed and a patrolling Person, and a Pool.

- `Player` wades in open water, swims where it is over half its height, and rides the swell of an `Ocean` or `Lake`
- Leaving the ground over deep water is a dive: head first, a glide under the surface, then up
- Swimming into a bank, a step or a ledge up to 0.6 m over the water climbs out onto it
- `Person` treads water, swims breaststroke or a front crawl by speed, and dives with the avatar
- A `Person` placed in deep water treads at the surface, and a walker swims the wet stretch of its route
- New props: `swim`, `swimSpeed`, `swimSprintSpeed` on `Player` and `swim` on `Person`
- `useWater`, `waterAt`, `planeWater` and `useWorld().waters` in `@runek/core` let any water component join in
- BREAKING: a `Player` no longer walks the bed under an `Ocean`, `Lake` or `Pool`, and a `Person` in deep water floats up (`swim={false}` restores it)

[CONTRIBUTORS]
- Swim state and forces are plain numbers in `player/swim.ts`, run from `useBeforePhysicsStep` so they land after ecctrl's pushes
- Strokes are canonical humanoid poses in `person/swim.ts`, blended over the built-in posture with `applyPose`
- `surfaces/water.ts` is the JS twin of the water shaders' wave, read at the same `uTime`
- `PlayerMotion` gains `swim`, `immersion` and `submerged`, `PoseContext` gains `swim` and `submerged`, `PoseSource` an optional `swim()` method
- Migration notes for `player` and `person` assume the next release is 0.19.0
- Tests for the water registry, the swim step and the strokes
@anistark
anistark merged commit 5d9ca19 into main Nov 15, 2026
1 check passed
@anistark
anistark deleted the feat/swimming branch November 15, 2026 08:40
anistark added a commit that referenced this pull request Nov 15, 2026
**`Terrain` gains `shore`, a beach an avatar can walk up out of the
sea.** A small island's bare coast is close to a cliff: on the
workshop's "Island cove" it runs 30° to 66°, which testing the swimming
in #76 showed an avatar can't climb.
- `shore` is the width, in units, of a band past the land's edge where
the ground falls 2 units at one slope, from 0.4 above the world ground
to wading depth, then drops to the deep as before
- So the beach is as gentle as it is wide: `shore: 6` is about 18°, and
about 4.3 is the 25° mark
- Land near the coast is lowered to meet the beach, so nothing steeper
stands behind it
- With a shore, `flatRadius` flattens the land alone (scaling the sea
bed would steepen it), and a pad wider than the land pushes the beach
out to its edge
- The island grows outward by `shore`, so it needs room inside `size`

**Worlds without `shore` keep every height they had**
- The old path in `terrainHeight()` is untouched, and `shore` is read
only on an island (one with `falloff`)
- A test pins four shore-less shapes with `toBe` against heights
recorded from `main` before the change

**"Island cove" template**
- Its terrain takes `shore: 6`: the steepest stretch between +0.3 m and
-1.5 m on the collider mesh goes from 60.8° to 19.6°
- `Dock` moves from `[0, 0, 19]` to `[0, 0, 9.4]` and the `Sailboat`
from z 24 to z 15.5. The dock used to start 9 m out from the waterline
over 7 m of water, and now starts on the sand
- The campfire, rocks and person stay at height 0, and the palms move by
1 to 4 mm

**Also**
- `shore` slider range in the workshop, regenerated `registry/` and
component docs
- `person.md` picks up two prop descriptions from #77 that were not
regenerated there

Known limit: on a coarse grid (cells much wider than about 1.5 m) the
crease at the bottom of the beach can show one steep triangle, 31° at
`resolution: 32` on an 80 x 60 terrain.

Testing: `just check` passes. In the workshop, a `Player` holding W
walks from 1.6 m deep onto land in 2.5 s with `shore: 6`; on the old
coast it slides to the bottom.

Refs #76
anistark added a commit that referenced this pull request Nov 15, 2026
…es (#79)

**`Pool`'s exit steps can be walked**, the stock `Player` climbs from
the basin floor onto the deck and back down
- The three 0.4 m blocks and the 0.47 m last rise stalled the avatar,
which floats 0.3 m over the ground
- The flight is now 0.25 m risers counted down from the coping, as many
as `depth` needs, under one `ConvexHullCollider` wedge
- The `steps` prop is unchanged

**`Pool`'s basin walls are solid**
- They were drawn without colliders, so an avatar on the basin floor
walked out through them and fell
- One `CuboidCollider` per wall, the size of its mesh

**`Player` keeps its pace on a slope whichever way it walks**
- ecctrl only turns its slope ray to the direction of travel under
`autoBalance`, which `Player` turns off, so the ray stayed in front of
the camera
- `SlopeRay` in `packages/components/src/Player.tsx` turns it to follow
the avatar's velocity; ecctrl is not patched
- Backing down a 32° ramp goes 2.2 m/s (was 0.6), across it 2.5 (was
0.9), stairs backwards 1.7 down and 1.5 up (were 1.1 and 0.9); forward
and flat-ground speeds are unchanged
- Strafing straight up or down a slope now matches walking up or down it
(2.0 and 2.2 m/s) instead of flat-ground speed

**Also in the diff**
- `apps/docs/src/content/docs/components/person.md` is regenerated: two
`Person` prop descriptions changed in #77 without the page being rebuilt

Testing: `just check` passes. Walked in the workshop with the stock
`Player`: pool floor to deck and back, all four walls of the default
pool and a `depth: 2.4` pool, and W/S/A/D on a 32° ramp, a `Staircase`
and flat ground, in first and third person. Gamepad and touch joystick
were not driven.

Refs #76 (also edits `Player.tsx` and `Pool.tsx`)
anistark added a commit that referenced this pull request Nov 15, 2026
)

**Swimming, second pass: going under on purpose, a view from below, a
pose for climbing out, a camera that looks down at a swimmer, and marks
on the water.** Stacked on #76: merge after it.

**Going under**
- New world control `dive` (default `KeyC`): hold to swim down, let go
to float back up
- `PlayerMotion.swim` gains `'under'`, with its own stroke on `Person`
- `player/Underwater.tsx` swaps the world fog's values in place for the
water's color and clarity and draws a backdrop sphere, so no material
recompiles under either renderer; `underwater={false}` on `Player` opts
out
- `Ocean` and `Lake` draw their underside (`UNDERSIDE` in
`surfaces/water.ts`, TSL twin in `nodes/water.ts`); `Pool` water is
double sided
- `WaterBody` gains `color` and `clarity`, and `waterAt` returns the
`body` it sampled

**Climbing out**
- `swim` gains `'climb'` while a swimmer hauls out over a wall, and
`submerged` then counts down the height left
- `Person` reaches, presses up, brings a knee up and stands; banks and
pool steps keep the plain lift
- A wall haul is capped at 1.4 m/s (was 2.5), about a second, so the
pose reads

**Camera**
- The third-person boom tilts to at least about 20 degrees over an
avatar afloat (`raiseBoom` in `player/boom.ts`): a tilt, not a lift, so
the sweep still starts inside the capsule

**Splash, ripples and wake**
- `water/wake.ts` (pure, seeded, two fixed pools) and `water/trail.tsx`
(two instanced draws, textures drawn in code)
- The `Player` draws its own, first person included, and every other
`Person` draws its own
- `Player`'s `seed` now sets how its splashes scatter

**Fixed on the way**
- `Ocean` and `Lake` waves stood still under WebGL and the `Ocean`
horizon ignored the fog range: react-three-fiber copies the uniforms
handed to `<shaderMaterial>`, so per-frame writes never reached the
shader. Both now build their material themselves

**Heads-up**
- `KeyC` is bound by default, so a world already using C for its own
action also dives on it in water (move one, or bind `dive: []`)
- Not here: ledges over 0.6 m and hull ladders, a touch or gamepad
button for `dive`, a blend as the camera crosses the surface

Testing: `just check` passes on the rebased branch, with new tests
beside `player/boom.ts`, `player/swim.ts`, `person/swim.ts`,
`water/wake.ts` and the core water and keyboard changes. Walked in the
workshop's play mode before the rebase: dive, swim down and back up,
look up from below, climb onto a dock and over a pool rim, a treading
`Person` with its own rings, first person, and a run under
`WebGPURenderer`. `just perf` was within budget then.

Refs #76
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant