Events

Events are immutable dataclass instances emitted by commands and consumed by the UI layer. They describe what happened without prescribing how the UI should react.

All event types live in escapy.events.

Event union type

type Event = (
    PickedUpEvent
    | PutInHandEvent
    | PutOffHandEvent
    | InteractedWithLockedEvent
    | UnlockedEvent
    | RevealedEvent
    | MovedToRoomEvent
    | AskedForCodeEvent
    | WrongCodeEvent
    | InspectedEvent
    | GameEndedEvent
    | AddedToInventoryEvent
)

Event reference

`PickedUpEvent`

An object was removed from the room and added to the inventory.

Field	Type	Description
`object_id`	`str`	Identifier of the picked-up object

`PutInHandEvent`

The player selected an inventory object as the active hand item.

Field	Type	Description
`object_id`	`str`	Identifier of the object now held in-hand

`PutOffHandEvent`

The player deselected the active hand item (hand is now empty). No fields.

`InteractedWithLockedEvent`

The player tried to interact with a locked object without the right key.

Field	Type	Description
`object_id`	`str`	Identifier of the locked object

`UnlockedEvent`

A locked object was successfully unlocked.

Field	Type	Description
`object_id`	`str`	Identifier of the unlocked object

`RevealedEvent`

A hidden object was revealed and placed into a room.

Field	Type	Description
`object_id`	`str`	Identifier of the revealed object
`room_id`	`str`	Room where the object was placed
`position`	`Position`	Position of the newly placed object

`MovedToRoomEvent`

The active room changed.

Field	Type	Description
`room_id`	`str`	Identifier of the new current room

`AskedForCodeEvent`

The UI should prompt the player to enter a code.

Field	Type	Description
`object_id`	`str`	Identifier of the object awaiting the code

`WrongCodeEvent`

The player entered an incorrect code. No fields.

`InspectedEvent`

The player inspected an object (e.g. zoomed in on it).

Field	Type	Description
`object_id`	`str`	Identifier of the inspected object

`GameEndedEvent`

The game has ended (player quit or won). No fields.

`AddedToInventoryEvent`

An object was added to the player’s inventory directly (not picked up from a room).

Field	Type	Description
`object_id`	`str`	Identifier of the added object

Using events with messages

To display human-readable text for events, use dict_message_provider:

from escapy import dict_message_provider
from escapy.events import PickedUpEvent

messages = {
    repr(PickedUpEvent("key")): "You found a rusty key!",
}
provider = dict_message_provider(messages)

The provider returns None for events without a matching entry, so unhandled events are silently ignored.

Events

Event union type

Event reference

PickedUpEvent

PutInHandEvent

PutOffHandEvent

InteractedWithLockedEvent

UnlockedEvent

RevealedEvent

MovedToRoomEvent

AskedForCodeEvent

WrongCodeEvent

InspectedEvent

GameEndedEvent

AddedToInventoryEvent