escapy.protocols

Protocol (structural typing) interfaces for escapy.

This subpackage defines the abstract contracts that the game engine, game objects, and UI implementations must satisfy. Using typing.Protocol allows duck-typed interoperability without forcing concrete inheritance.

Submodules

escapy.protocols.game

Game-engine protocol and the Command type alias.

class escapy.protocols.game.GameProtocol(*args, **kwargs)

Bases: Protocol

Structural interface that every game-engine implementation must satisfy.

objects

Mapping of object IDs to their game-object instances.

Type:

dict[str, object]

rooms

Mapping of room IDs to Room dicts.

Type:

dict[str, escapy.types.Room]

current_room_id

ID of the room currently displayed.

Type:

str

is_finished

True after the game has ended.

Type:

bool

inventory

Ordered list of object IDs the player is carrying.

Type:

list[str]

in_hand_object_id

ID of the object currently held, or None.

Type:

str | None

objects: dict[str, object]

rooms: dict[str, Room]

current_room_id: str

is_finished: bool

inventory: list[str]

in_hand_object_id: str | None

quit()

End the game.

Return type:

list[Event]

interact(object_id)

Interact with an object in the current room.

Parameters:

object_id (str)

Return type:

list[Event]

interact_inventory(object_id)

Interact with an inventory object or clear the hand.

Parameters:

object_id (str | None)

Return type:

list[Event]

insert_code(object_id, code)

Submit a code to a decodable object.

Parameters:

• object_id (str)

• code (str)

Return type:

list[Event]

type escapy.protocols.game.Command = Callable[[GameProtocol], list[Event]]

A callable that mutates game state and returns the resulting events.

escapy.protocols.objects

Protocol definitions for game-object capabilities.

Each protocol represents a single capability (interacting, being placed, being unlocked, etc.) and may be composed via multiple inheritance.

class escapy.protocols.objects.Interactable(*args, **kwargs)

Bases: Protocol

An object that can be interacted with when clicked in a room.

interact

Command executed on interaction.

Type:

escapy.protocols.game.Command

interact: Command

class escapy.protocols.objects.InventoryInteractable(*args, **kwargs)

Bases: Protocol

An object that can be interacted with from the inventory panel.

interact_inventory

Command executed on inventory interaction.

Type:

escapy.protocols.game.Command

interact_inventory: Command

class escapy.protocols.objects.Placeable(*args, **kwargs)

Bases: Protocol

An object that occupies visual space in the game area.

Dimensions are expressed as normalised fractions of the game area (same coordinate system as Position).

width

Normalised width.

Type:

float

height

Normalised height.

Type:

float

width: float

height: float

class escapy.protocols.objects.Unlockable(*args, **kwargs)

Bases: Protocol

An object that has a locked/unlocked state.

state

Current lock state.

Type:

Literal[‘locked’, ‘unlocked’]

on_unlock

Command to execute when unlocked.

Type:

escapy.protocols.game.Command

state: Literal['locked', 'unlocked'] = 'locked'

on_unlock: Command

unlock()

Transition the object to the unlocked state and return on_unlock.

Return type:

Command

class escapy.protocols.objects.Decodable(*args, **kwargs)

Bases: Protocol

An object that can be decoded with a text/numeric code.

code

The correct code string.

Type:

str

on_decode

Command to execute on a correct code.

Type:

escapy.protocols.game.Command

code: str

on_decode: Command

insert_code(code)

Validate code and return the appropriate command.

Parameters:

code (str)

Return type:

Command

escapy.protocols.ui

Protocol definition for the game UI layer.

class escapy.protocols.ui.GameUiProtocol(*args, **kwargs)

Bases: Protocol

Structural interface that every UI backend must implement.

The game loop calls these methods in order:

ui.init(game)
while ui.is_running:
    ui.tick()
    events = ui.input()
    ui.handle(events)
    ui.render()
ui.quit()

is_running

True while the UI is active.

Type:

bool

init(game)

Initialise the UI with the given game instance.

Parameters:

game (GameProtocol)

Return type:

None

tick()

Regulate the frame rate / perform per-frame bookkeeping.

Return type:

None

input()

Poll user input and return resulting events.

Return type:

list[Event]

handle(events)

React to game events (e.g. display messages, switch states).

Parameters:

events (list[Event])

Return type:

None

render()

Draw the current frame.

Return type:

None

quit()

Tear down the UI and release resources.

Return type:

None

is_running: bool