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 anyambiances
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 theactions_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 anyambiances
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’sdrop_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’stake_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 theclasses
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.
- id –
-
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: -
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 toNone
. - drop_action –
The default drop action.
This value will be used when an object is dropped and has its
drop_action
attribute isNone
. - 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
andclasses
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 ifinitial_room_id
is itselfNone
.
-
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
andRoomExit
classes.If attached to a
RoomObject
instance, itsname
will appear in theaction menu
. If attached to aRoomExit
instance, then itsname
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 aRoomObject
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
inearwax/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
anddescription
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 appropriatelocation
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..
- destination – The destination whose ID will become the new exit’s
-
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 appropriatelocation
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.
- world –
-
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.