earwax.story.world module¶

Provides various classes relating to worlds.

class earwax.story.world.DumpablePoint(x: T, y: T, z: T)¶

Bases: earwax.point.Point, earwax.mixins.DumpLoadMixin

A point that can be dumped and loaded.

class earwax.story.world.DumpableReverb(gain: float = 1.0, late_reflections_delay: float = 0.01, late_reflections_diffusion: float = 1.0, late_reflections_hf_reference: float = 500.0, late_reflections_hf_rolloff: float = 0.5, late_reflections_lf_reference: float = 200.0, late_reflections_lf_rolloff: float = 1.0, late_reflections_modulation_depth: float = 0.01, late_reflections_modulation_frequency: float = 0.5, mean_free_path: float = 0.02, t60: float = 1.0)¶

Bases: earwax.reverb.Reverb, earwax.mixins.DumpLoadMixin

A reverb that can be dumped.

class earwax.story.world.RoomExit(destination_id: str, action: earwax.story.world.WorldAction = NOTHING, position: Optional[earwax.story.world.DumpablePoint] = None)¶

Bases: earwax.mixins.DumpLoadMixin

An exit between two rooms.

Instances of this class rely on their action property to show messages and play sounds, as well as for the name of the exit.

The actual destination can be retrieved with the destination property.

Variables:	destination_id – The ID of the room on the other side of this exit. location – The location of this exit. This value is provided by the containing `StoryWorld` class. action – An action to perform when using this exit. position – The position of this exit. If this value is `None`, then any `ambiances` will not be panned.

destination¶

Return the room this exit leads from.

This value is inferred from destination_id.

class earwax.story.world.RoomObject(id: str = NOTHING, name: str = 'Unnamed Object', actions_action: Optional[earwax.story.world.WorldAction] = None, ambiances: List[earwax.story.world.WorldAmbiance] = NOTHING, actions: List[earwax.story.world.WorldAction] = NOTHING, position: Optional[earwax.story.world.DumpablePoint] = None, drop_action: Optional[earwax.story.world.WorldAction] = None, take_action: Optional[earwax.story.world.WorldAction] = None, use_action: Optional[earwax.story.world.WorldAction] = None, type: earwax.story.world.RoomObjectTypes = NOTHING, class_names: List[str] = NOTHING)¶

Bases: earwax.story.world.StringMixin, earwax.mixins.DumpLoadMixin

An object in the story.

Instances of this class will either sit in a room, or be in the player’s inventory.

Variables:

id –
The unique ID of this object. If this ID is not provided, then picking it up will not be reliable, as the ID will be randomly generated.

Other than the above restriction, you can set the ID to be whatever you like.
name –
The name of this object.

This value will be used in any list of objects.
actions_action –
An action object which will be used when viewing the actions menu for this object.

If this value is None, no music will play when viewing the actions menu for this object, and the actions_menu message will be shown.
ambiances – A list of ambiances to play at the position of this object.
actions – A list of actions that can be performed on this object.
position –
The position of this object.

If this value is None, then any ambiances will not be panned.
drop_action –
The action that will be used when this object is dropped by the player.

If this value is None, the containing world’s drop_action attribute will be used.
take_action –
The action that will be used when this object is taken by the player.

If this value is None, the containing world’s take_action attribute will be used.
use_action –
The action that will be used when this object is used by the player.

If this value is None, then this object is considered unusable.
type – Specifies what sort of object this is.
class_names –
The names of all the classes this object belongs to.

If you want a list of RoomObjectClass instances, use the classes property.
location –
The room where this object is located.

This value is set by the StoryWorld() which holds this instance.

If this object is picked up, the location will not change, but this object will be removed from the location’s objects dictionary.

classes¶

Return a list of classes.

This value is inferred from the class_names list.

is_droppable¶: Return True if this object can be dropped.

is_stuck¶: Return True if this object is stuck.

is_takeable¶: Return True if this object can be taken.

is_usable¶: Return True if this object can be used.

class earwax.story.world.RoomObjectClass(name: str)¶

Bases: earwax.mixins.DumpLoadMixin

Add a class for objects.

Instances of this class let you organise objects into classes.

This is used for making exits discriminate.

Variables:	name – The name of the class.

class earwax.story.world.RoomObjectTypes¶

Bases: enum.Enum

The type of a room object.

Variables:	stuck – This object cannot be moved. takeable – This object can be picked up. droppable – This object can be dropped. This value automatically implies `takeable`.

droppable = 2¶

stuck = 0¶

takeable = 1¶

usable = 4¶

class earwax.story.world.StoryWorld(game: Game, name: str = 'Untitled World', author: str = 'Unknown', main_menu_musics: List[str] = NOTHING, cursor_sound: Optional[str] = None, empty_category_sound: Optional[str] = None, end_of_category_sound: Optional[str] = None, rooms: Dict[str, earwax.story.world.WorldRoom] = NOTHING, initial_room_id: Optional[str] = None, messages: earwax.story.world.WorldMessages = NOTHING, take_action: earwax.story.world.WorldAction = NOTHING, drop_action: earwax.story.world.WorldAction = NOTHING, panner_strategy: str = NOTHING, object_classes: List[earwax.story.world.RoomObjectClass] = NOTHING)¶

Bases: earwax.mixins.DumpLoadMixin

The top level world object.

Worlds can contain rooms and messages, as well as various pieces of information about themselves.

Variables:

game – The game this world is part of.
name – The name of this world.
author –
The author of this world.

The format of this value is arbitrary, although Author Name <author@domain.com> is recommended.
main_menu_musics – A list of filenames to play as music while the main menu is being shown.
cursor_sound –
The sound that will play when moving over objects.

If this value is None, no sound will be heard.
empty_category_sound – The sound which will be heard when cycling to an empty category.
end_of_category_sound – The sound which will be heard when cycling to the end of a category.
rooms – A mapping of room IDs to rooms.
initial_room_id – The ID of the room to be used when first starting the game.
messages – The messages object used by this world.
take_action –
The default take action.

This value will be used when an object is taken with its take_action attribute set to None.
drop_action –
The default drop action.

This value will be used when an object is dropped and has its drop_action attribute is None.
panner_strategy – The name of the default panner strategy to use.
object_classes –
A list of object classes.

Objects are mapped to these classes by way of their class_names and classes lists.

add_room(room: earwax.story.world.WorldRoom, initial: Optional[bool] = None) → None¶

Add a room to this world.

Parameters:	room – The room to add. initial – An optional boolean to specify whether the given room should become the `initial_room` or not. If this value is `None`, then this room will be set as default if `initial_room_id` is itself `None`.

all_objects() → Iterator[earwax.story.world.RoomObject]¶: Return a generator of every object contained by this world.

dump() → Dict[str, Any]¶: Dump this world.

initial_room¶: Return the initial room for this world.

classmethod load(data: Dict[str, Any], *args) → Any¶: Load credits before anything else.

class earwax.story.world.StringMixin¶

Bases: object

Provides an __str__ method.

class earwax.story.world.WorldAction(name: str = 'Unnamed Action', message: Optional[str] = None, sound: Optional[str] = None, rumble_value: float = 0.0, rumble_duration: int = 0)¶

Bases: earwax.mixins.DumpLoadMixin

An action that can be performed.

Actions are used by the RoomObject and RoomExit classes.

If attached to a RoomObject instance, its name will appear in the action menu. If attached to a RoomExit instance, then its name will appear in the exits list.

Variables:

name – The name of this action.
message –
The message that is shown to the player when this action is used.

If this value is omitted, no message will be shown.
sound –
The sound that should play when this action is used.

If this value is omitted, no sound will be heard.
rumble_value –
The power of a rumble triggered by this action.

This value should be between 0.0 (nothing) and 1.0 (full power).

If this value is 0, no rumble will occur.
rumble_duration –
The time (in seconds) the rumble should continue for.

If this value is 0, no rumble will occur.

class earwax.story.world.WorldAmbiance(path: str, volume_multiplier: float = 1.0)¶

Bases: earwax.mixins.DumpLoadMixin

An ambiance.

This class represents a looping sound, which is either attached to a WorldRoom instance, or a RoomObject instance.

Variables:	path – The path to a sound file. volume_multiplier – A value to multiply the ambiance volume by to get the volume for this sound..

class earwax.story.world.WorldMessages(no_objects: str = 'This room is empty.', no_actions: str = 'There is nothing you can do with this object.', no_exits: str = 'There is no way out of this room.', no_use: str = 'You cannot use {}.', nothing_to_use: str = 'You have nothing that can be used.', nothing_to_drop: str = 'You have nothing that can be dropped.', empty_inventory: str = "You aren't carrying anything.", room_activate: str = 'You cannot do that.', room_category: str = 'Location', objects_category: str = 'Objects', exits_category: str = 'Exits', actions_menu: str = 'You step up to {}.', inventory_menu: str = 'Inventory', main_menu: str = 'Main Menu', play_game: str = 'Start new game', load_game: str = 'Load game', show_credits: str = 'Show Credits', credits_menu: str = 'Credits', welcome: str = 'Welcome to this game.', no_saved_game: str = 'You have no game saved.', exit: str = 'Exit')¶

Bases: earwax.mixins.DumpLoadMixin

All the messages that can be shown to the player.

When adding a message to this class, make sure to add the same message and an appropriate description to the message_descriptions in earwax/story/edit_level.py.

Variables:

no_objects – The message which is shown when the player cycles to an empty list of objects.
no_actions – The message which is shown when there are no actions for an object.
no_exits – The message which is shown when the player cycles to an empty list of exits.
no_use – The message which is shown when the player tries to use an object which cannot be used.
nothing_to_use – The message which is shown when accessing the use menu with no usable objects.
nothing_to_drop – The message which is shown when accessing the drop menu with no droppable items.
empty_inventory – The message which is shown when trying to access an empty inventory menu.
room_activate –
The message which is shown when enter is pressed with the room category selected.

Maybe an action attribute should be added to rooms, so that enter can be used everywhere?
room_category – The name of the “room” category.
objects_category – The name of the “objects” category.
exits_category – The name of the “exits” category.
actions_menu – The message which is shown when the actions menu is activated.
inventory_menu –
The title of the inventory menu.

You can include the name of the object in question, by including a set of braces:
```
<message id="actions_menu">You examine {}.</message>
```
main_menu – The title of the main menu.
play_game – The title of the “play game” entry in the main menu.
load_game – The title of the “load game” entry in the main menu.
show_credits – The title of the “show credits” entry in the main menu.
credits_menu – The title of the credits menu.
welcome – The message which is shown when play starts.
no_saved_game – The message which is spoken when there is no game to load.
exit – The title of the “exit” entry of the main menu.

class earwax.story.world.WorldRoom(id: str = NOTHING, name: str = 'Unnamed Room', description: str = 'Not described.', ambiances: List[earwax.story.world.WorldAmbiance] = NOTHING, objects: Dict[str, earwax.story.world.RoomObject] = NOTHING, exits: List[earwax.story.world.RoomExit] = NOTHING, reverb: Optional[earwax.story.world.DumpableReverb] = None)¶

Bases: earwax.mixins.DumpLoadMixin, earwax.story.world.StringMixin

A room in a world.

Rooms can contain exits and object.

It is worth noting that both the room name and description can either be straight text, or they can consist of a hash character (#) followed by the ID of another room, from which the relevant attribute will be presented at runtime.

If this is the case, changing the name or description of the referenced room will change the corresponding attribute on the first instance.

This convertion can only happen once, as otherwise there is a risk of circular dependencies, causing a RecursionError to be raised.

Variables:

world –
The world this room is part of.

This value is set by the containing StoryRoom instance.
id –
The unique ID of this room.

If this value is not provided, then an ID will be generated, based on the number of rooms that have already been loaded.

If you want to link this room with exits, it is highly recommended that you provide your own ID.
name – The name of this room, or the #id of a room to inherit the name from.
description – The description of this room, or the #id of another room to inherit the description from.
ambiances – A list of ambiances to play when this room is in focus.
objects –
A mapping of object ids to objects.

To get a list of objects, the canonical way is to use the earwax.story.play_level.PlayLevel.get_objects() method, as this will properly hide objects which are in the player’s inventory.
exits – A list of exits from this room.

create_exit(destination: earwax.story.world.WorldRoom, **kwargs) → earwax.story.world.RoomExit¶

Create and return an exit that links this room to another.

This method will add the new exits to this room’s exits list, and set the appropriate location on the new exit.

Parameters:	destination – The destination whose ID will become the new exit’s `destination_id`. kwargs – Extra keyword arguments to pass to the `RoomExit` constructor..

create_object(**kwargs) → earwax.story.world.RoomObject¶

Create and return an exit from the provided kwargs.

This method will add the created object to this room’s objects dictionary, and set the appropriate location attribute.

Parameters:	kwargs – Keyword arguments to pass to the constructor of `RoomObject`.

get_description() → str¶: Return the actual description of this room.

get_name() → str¶: Return the actual name of this room.

class earwax.story.world.WorldState(world: earwax.story.world.StoryWorld, room_id: str = NOTHING, inventory_ids: List[str] = NOTHING, category_index: int = NOTHING, object_index: Optional[int] = None)¶

Bases: earwax.mixins.DumpLoadMixin

The state of a story.

With the exception of the world attribute, this class should only have primitive types as its attributes, so that instances can be easily dumped to yaml.

Variables:	world – The world this state represents. room_id – The ID of the current room. inventory_ids – A list of object IDs which make up the player’s inventory. category_index – The player’s position in the list of categories. object_index – The player’s position in the current category.

category¶: Return the current category.

get_default_room_id() → str¶

Get the first room ID from the attached world.

Parameters:	instance – The instance to work on.

room¶: Get the current room.

class earwax.story.world.WorldStateCategories¶

Bases: enum.Enum

The various categories the player can select.

Variables:	room – The category where the name and description of a room are shown. objects – The category where the objects of a room are shown. exits – The category where the exits of a room are shown.

exits = 2¶

objects = 1¶

room = 0¶