escapy.commands

Command factory functions that drive game-state mutations.

A command is a callable (GameProtocol) -> list[Event]. Each factory function in this module returns a command that performs a single, composable action — for example picking up an object, unlocking a lock, or moving the player to another room. Higher-order combinators such as combine(), cond(), and chain() allow commands to be composed.

escapy.commands.no_op()[source]

Return a command that does nothing and emits no events.

Return type:: Command

escapy.commands.pick(id)[source]

Return a command that picks up an object from the current room.

The object is removed from the room and added to the player’s inventory.

Parameters:: id (str) – Identifier of the object to pick up.
Returns:: A command that emits a PickedUpEvent.
Return type:: Command

escapy.commands.put_in_hand(id)[source]

Return a command that sets an object as the active hand item.

Parameters:: id (str) – Identifier of the object to hold.
Returns:: A command that emits a PutInHandEvent.
Return type:: Command

escapy.commands.simple_lock(id)[source]

Return a command that unlocks a locked object unconditionally.

If the object implements Unlockable and its state is "locked", it will be unlocked and its on_unlock command will be executed.

Parameters:: id (str) – Identifier of the lockable object.
Returns:: A command that emits an UnlockedEvent followed by the events from the object’s on_unlock command, or an empty list if the object is already unlocked.
Return type:: Command

escapy.commands.key_lock(id, key_id)[source]

Return a command that unlocks a locked object only if the player holds the right key.

The object is unlocked when:

it implements Unlockable,
its state is "locked", and
game.in_hand_object_id matches key_id.

Parameters:

id (str) – Identifier of the lockable object.
key_id (str) – Identifier of the required key object.

Returns:

A command that emits an UnlockedEvent (plus the on_unlock follow-up events), or an empty list on failure.

Return type:

Command

escapy.commands.ask_for_code(id)[source]

Return a command that requests the UI to prompt the player for a code.

Parameters:: id (str) – Identifier of the object awaiting the code.
Returns:: A command that emits an AskedForCodeEvent.
Return type:: Command

escapy.commands.locked(id)[source]

Return a command that signals the player interacted with a locked object.

Parameters:: id (str) – Identifier of the locked object.
Returns:: A command that emits an InteractedWithLockedEvent.
Return type:: Command

escapy.commands.inspect(id)[source]

Return a command that inspects an object (e.g. zoom-in view).

Parameters:: id (str) – Identifier of the object to inspect.
Returns:: A command that emits an InspectedEvent.
Return type:: Command

escapy.commands.reveal(object_id, room_id, position)[source]

Return a command that reveals a hidden object by placing it in a room.

Parameters:

object_id (str) – Identifier of the object to reveal.
room_id (str) – Room in which the object should appear.
position (Position) – Position within the room.

Returns:

A command that emits a RevealedEvent.

Return type:

Command

escapy.commands.move_to_room(room_id)[source]

Return a command that changes the current room.

Parameters:: room_id (str) – Identifier of the destination room.
Returns:: A command that emits a MovedToRoomEvent.
Return type:: Command

escapy.commands.add_to_inventory(object_id)[source]

Return a command that adds an object directly to the player’s inventory.

Unlike pick(), this does not remove the object from a room.

Parameters:: object_id (str) – Identifier of the object to add.
Returns:: A command that emits an AddedToInventoryEvent.
Return type:: Command

escapy.commands.combine(*fns)[source]

Return a command that executes multiple commands in sequence.

All events are collected in order and returned as a single flat list.

Parameters:: *fns (Command) – Commands to execute sequentially.
Return type:: Command

escapy.commands.cond(*clauses)[source]

Return a command that executes the first clause whose condition is true.

Clauses are evaluated in order. Only the command of the first matching clause is executed; the rest are skipped.

Parameters:: *clauses (tuple[Callable[[], bool], Command]) – (condition, command) pairs. condition is a zero-argument callable returning a bool.
Return type:: Command

escapy.commands.chain(*clauses)[source]

Like combine, but allows conditional execution based on previously emitted events.

Parameters:: *clauses (tuple[Callable[[list[Event]], bool], Command]) – Tuple of (condition, Command) where condition receives the list of events emitted so far.
Return type:: Command

Example:

chain(
    (lambda _: True, key_lock(id, key_id)),
    (lambda events: not any(isinstance(e, UnlockedEvent) for e in events), locked(id)),
)