Character states and transitions

This page describes ordinary free-mode movement in v1.0.1, based on behavior.rs, terrestrial_behavior.rs, the engine, and platform runtimes. See the user guide for controls and behavior parameters for values.

A state describes what a character is doing; a surface describes where it is. Walking on the desktop and walking at a window edge lead to different decisions. State timing, boundaries, nearby targets, and randomness all contribute.

Surface types

Internal name	Meaning
Desktop	Desktop floor
WindowTop	Top edge of a window
WindowWall	Side wall of a window
WindowUpperCorner	Upper window corner
WindowBottom	Surface along the bottom of a window
Airborne	In the air, not bound to a surface
WindowInterior	Internal definition for aquatic physics; outside ordinary free-mode behavior

Main transition flow

Falling -> LandingStandUp -> Observing -> Walking / SurfaceInteract
Walking -> JumpRunup -> Airborne -> WallEntry / LandingStandUp
WallEntry -> ClimbingUp -> CornerTransitionSide -> CornerTransitionFront
CornerTransitionFront -> CornerRest / Walking / ClimbingDown
ClimbingDown -> Walking (WindowBottom)

This shows the main flow. Rest, running, surface loss, and user interaction add other branches. Falling and Airborne depend on physics and arrival detection, rather than reaching a landing solely through the normal state decision method.

Floor and window-top states

Falling

Gravity-driven falling. Landing on a wall enters WallEntry; other landings enter LandingStandUp. Losing a surface also enters this state.

Airborne

A controlled parabolic jump with a target window. The runtime handles target arrival and disappearance separately from ordinary falling.

LandingStandUp

Post-landing stand-up. Enters Observing after floor.standup_duration.

Observing

Post-landing observation. On the desktop, it may first approach a nearby window; otherwise it chooses walking or peeking.

SurfaceInteract

A short surface interaction. Peeking uses animation="peek-down". On completion, enters Walking or TurningAround. This replaces the old PeekDown state.

Walking

Moves along a surface. On the desktop it may run or start a wall-jump run-up. At a window-top edge it may idle, fall in surprise, or round the corner.

Running

A running burst. Returns to Walking when its duration ends or an edge is reached; may enter JumpRunup for a desktop wall-jump target.

TurningAround

Turns around. After floor.turn_duration, floor.turn_walk_prob selects Walking or StandIdle.

StandIdle

Standing rest, including small mouth movements. Decisions on expiry differ at an edge and away from edges.

SitIdle

Sitting rest with side/front head turns. On expiry it may lie down, stand, or walk.

LieIdle

Lying rest. On expiry it may sleep, sit, or walk.

Sleeping

Sleeping. On expiry it resumes rest or movement according to its location.

Jump state

JumpRunup

Run-up before a jump. Enters Airborne after jump.runup_duration. The engine and platform runtime handle velocity, trajectory, and arrival.

Window-wall states

WallEntry

Holds the wall-entry pose, then enters ClimbingUp after wall.entry_hold.

ClimbingUp

Climbs a wall. Enters CornerTransitionSide at the top and may pause along the way.

ClimbingDown

Descends a wall. Reaching the bottom leads to Walking on WindowBottom; may pause along the way.

WallPause

Rests on a wall, then resumes climbing in the previous direction.

Corner states

CornerTransitionSide

Side-view corner transition. Enters CornerTransitionFront after corner.side_corner_secs.

CornerTransitionFront

Front-view corner transition. Upward movement leads to rest or window-top walking; downward movement leads to ClimbingDown.

CornerRest

Sitting or lying at a corner. On expiry it checks for an outing to a nearby window; otherwise descends or walks inward.

Interaction and additional animations

Grabbed

Held by a modifier-key drag. On release, the runtime chooses a surface based on the drop position.

OneShot

Plays an asset-defined animation once, then returns to the saved return_to state.

Idle chain

Standing → sitting → lying → sleeping is a possible progression, not a mandatory sequence. Edge and ordinary rest decisions differ. A character may walk, turn, or descend before reaching sleep. Some decisions use cumulative thresholds rather than independent probabilities.

Event-driven transitions

Event	Result
Surface disappears	Enter Falling
Landing after a fall	WallEntry for a wall; otherwise LandingStandUp
Jump reaches its target	Update surface and state for the target and landing mode
User grabs the character	Enter Grabbed
User releases it	Choose a surface or falling based on the position
OneShot completes	Return to the saved state

Speech events startup, landing, and hour_change belong to the speech system, not the set of movement state names. Additional animation conditions live in behavior.toml; the engine manages surfaces and the full state machine.