Moves¶
Movement functions for entity navigation within the grid universe.
Each movement function defines how an entity moves in response to an action.
They take the current State, the entity ID, and the intended Action,
and return a sequence of Position instances representing the path taken.
Different movement functions can simulate various terrain types or movement
mechanics (e.g., slippery surfaces, wind effects, gravity).
Users can select from built-in movement classes via the MOVEMENT_REGISTRY
or define custom movements by subclassing BaseMovement.
MOVEMENT_REGISTRY = {'cardinal': CardinalMovement(), 'wrap-around': WrapAroundMovement(), 'mirror': MirrorMovement(), 'slippery': SlipperyMovement(), 'windy': WindyMovement(), 'gravity': GravityMovement()}
module-attribute
¶
Registry of built-in movement objects by name.
Use these movement objects when creating State instances. Each object
wraps a movement function along with metadata.
BaseMovement(name, description, function)
dataclass
¶
Base class for movement functions.
__call__(state, eid, action)
¶
Evaluate the movement function.
CardinalMovement(name='cardinal', description='Single-step cardinal movement.', function=cardinal_move_fn)
dataclass
¶
GravityMovement(name='gravity', description='Cardinal movement followed by falling downward until blocked.', function=gravity_move_fn)
dataclass
¶
MirrorMovement(name='mirror', description='Horizontally mirrored movement (LEFT<->RIGHT).', function=mirror_move_fn)
dataclass
¶
SlipperyMovement(name='slippery', description='Cardinal movement with sliding until blocked.', function=slippery_move_fn)
dataclass
¶
WindyMovement(name='windy', description='Cardinal movement with random wind drift.', function=windy_move_fn)
dataclass
¶
WrapAroundMovement(name='wrap-around', description='Cardinal movement with wrap-around at grid edges.', function=wrap_around_move_fn)
dataclass
¶
cardinal_move_fn(state, eid, action)
¶
Single-step cardinal movement in the intended direction. Returns the adjacent tile in the specified direction.
gravity_move_fn(state, eid, action)
¶
Cardinal step then fall straight downward until blocked.
If the initial adjacent tile is blocked or out-of-bounds, no movement is produced. Otherwise the path includes the first step plus each subsequent unobstructed downward tile.
mirror_move_fn(state, eid, action)
¶
Horizontally mirrored movement (LEFT<->RIGHT).
slippery_move_fn(state, eid, action)
¶
Cardinal step with sliding until blocked. The entity continues moving in the chosen direction until blocked, simulating a slippery surface. If the first adjacent tile is blocked, no movement occurs.
windy_move_fn(state, eid, action)
¶
Primary cardinal step plus optional wind drift. The first step is always in the intended direction. Then with 30% chance a random wind drift step is applied in a random cardinal direction (which may be the same as the original). If the wind step would go out-of-bounds, it is skipped.
wrap_around_move_fn(state, eid, action)
¶
Cardinal step with wrap-around at grid edges.
Returns the adjacent tile in the direction of action, wrapping around
the grid if the edge is crossed.