earwax.mapping.box_level module

Provides the BoxLevel class.

class earwax.mapping.box_level.BoxLevel(game: Game, boxes: List[earwax.mapping.box.Box[typing.Any][Any]] = NOTHING, coordinates: earwax.point.Point = NOTHING, bearing: int = 0, current_box: Optional[earwax.mapping.box_level.CurrentBox] = None)

Bases: earwax.level.Level

A level that deals with sound generation for boxes.

This level can be used in your games. Simply bind the various action methods (listed below) to whatever triggers suit your purposes.

Some of the attributes of this class refer to a “perspective”. This could theoretically be anything you want, but most likely refers to the player. Possible exceptions include if you made an instance to represent some kind of long range vision for the player.

Action-ready Methods

  • move().
  • show_coordinates()
  • show_facing()
  • turn()
  • show_nearest_door()
  • describe_current_box()
Variables:
  • box – The box that this level will work with.
  • coordinates – The coordinates of the perspective.
  • bearing – The direction the perspective is facing.
  • current_box –

    The most recently walked over box.

    If you don’t set this attribute when creating the instance, then the first time the player moves using the move() method, the name of the box they are standing on will be spoken.

  • reverb –

    An optional reverb to play sounds through.

    You shouldn’t write to this property, instead use the connect_reverb() method to set a new reverb, and disconnect_reverb() to clear.
activate(door_distance: float = 2.0) → Callable[[], None]

Return a function that can be call when the enter key is pressed.

First we check if the current box is a portal. If it is, then we call handle_portal().

If it is not, we check to see if there is a door close enough to be opened or closed. If there is, then we call handle_door() on it.

If none of this works, and there is a current box, dispatch the on_activate() event to let the box do its own thing.

Parameters:door_distance – How close doors have to be for this method to open or close them.
add_box(box: earwax.mapping.box.Box[typing.Any][Any]) → None

Add a box to self.boxes.

Parameters:box – The box to add.
add_boxes(boxes: Iterable[earwax.mapping.box.Box]) → None

Add multiple boxes with one call.

Parameters:boxes – An iterable for boxes to add.
add_default_actions() → None

Add some default actions.

This method adds the following actions:

  • Move forward: W
  • Turn 180 degrees: S
  • Turn 45 degrees left: A
  • Turn 45 degrees right: D
  • Show coordinates: C
  • Show the facing direction: F
  • Describe current box: X
  • Speak nearest door: Z
  • Activate nearby objects: Return
calculate_coordinates(distance: float, bearing: int) → Tuple[float, float]

Calculate coordinates at the given distance in the given direction.

Used by move() to calculate new coordinates.

Override this method if you want to change the algorithm used to calculate the target coordinates.

Please bear in mind however, that the coordinates this method returns should always be 2d.

Parameters:
  • distance – The distance which should be used.
  • bearing –

    The bearing the new coordinates are in.

    This value may not be the same as self.bearing.
collide(box: earwax.mapping.box.Box[typing.Any][Any], coordinates: earwax.point.Point) → None

Handle collitions.

Called to run collision code on a box.

Parameters:
  • box – The box the player collided with.
  • coordinates – The coordinates the player was trying to reach.
describe_current_box() → None

Describe the current box.

get_angle_between(other: earwax.point.Point) → float

Return the angle between the perspective and the other coordinates.

This function takes into account self.bearing.

Parameters:other – The target coordinates.
get_boxes(t: Any) → List[earwax.mapping.box.Box]

Return a list of boxes of the current type.

If no boxes are found, an empty list is returned.

Parameters:t – The type of the boxes.
get_containing_box(coordinates: earwax.point.Point) → Optional[earwax.mapping.box.Box]

Return the box that spans the given coordinates.

If no box is found, None will be returned.

This method scans self.boxes using the sort_boxes() method.

Parameters:coordinates – The coordinates the box should span.
get_current_box() → Optional[earwax.mapping.box.Box]

Get the box that lies at the current coordinates.

handle_box(box: earwax.mapping.box.Box[typing.Any][Any]) → None

Handle a bulk standard box.

The coordinates have already been set, and the on_footstep event dispatched, so all that is left is to speak the name of the new box, if it is different to the last one, update self.reverb if necessary, and store the new box.

move(distance: float = 1.0, vertical: Optional[float] = None, bearing: Optional[int] = None) → Callable[[], None]

Return a callable that allows the player to move on the map.

If the move is successful (I.E.: There is a box at the destination coordinates), the on_move() event is dispatched.

If not, then on_move_fail() is dispatched.

Parameters:
  • distance – The distance to move.
  • vertical – An optional adjustment to be added to the vertical position.
  • bearing –

    An optional direction to move in.

    If this value is None, then self.bearing will be used.
nearest_by_type(start: earwax.point.Point, data_type: Any, same_z: bool = True) → Optional[earwax.mapping.box_level.NearestBox]

Get the nearest box to the given point by type.

If no boxes of the given type are found, None will be returned.

Parameters:
  • start – The point to start looking from.
  • data_type – The type of box data to search for.
  • same_z – If this value is True, only boxes on the same z axis will be considered.
nearest_door(start: earwax.point.Point, same_z: bool = True) → Optional[earwax.mapping.box_level.NearestBox]

Get the nearest door.

Iterates over all doors, and returned the nearest one.

Parameters:
  • start – The coordinates to start from.
  • same_z – If True, then doors on different levels will not be considered.
nearest_portal(start: earwax.point.Point, same_z: bool = True) → Optional[earwax.mapping.box_level.NearestBox]

Return the nearest portal.

Parameters:
  • start – The coordinates to start from.
  • same_z – If True, then portals on different levels will not be considered.
on_move_fail(distance: float, vertical: Optional[float], bearing: int, coordinates: earwax.point.Point) → None

Handle a move failure.

An event that will be dispatched when the move() action has been used, but no move was performed.

Parameters:
  • distance – The distance value that was passed to move().
  • vertical – The vertical value that was passed to move.
  • bearing – The bearing argument that was passed to move, or self.bearing.
on_move_success() → None

Handle a successful move.

An event that will be dispatched when the move() action is used.

By default, this method plays the correct footstep sound.

on_push() → None

Set listener orientation, and start ambiances and tracks.

on_turn() → None

Handle turning.

An event that will dispatched when the turn() action is used.

register_box(box: earwax.mapping.box.Box) → None

Register a box that is already in the boxes list.

Parameters:box – The box to register.
remove_box(box: earwax.mapping.box.Box[typing.Any][Any]) → None

Remove a box from self.boxes.

Parameters:box – The box to remove.
set_bearing(angle: int) → None

Set the direction of travel and the listener’s orientation.

Parameters:angle – The bearing (in degrees).
set_coordinates(p: earwax.point.Point) → None

Set the current coordinates.

Also set listener position.

Parameters:p – The new point to assign to self.coordinates.
show_coordinates(include_z: bool = False) → Callable[[], None]

Speak the current coordinates.

show_facing(include_angle: bool = True) → Callable[[], None]

Return a function that will let you see the current bearing as text.

For example:

l = BoxLevel(...)
l.action('Show facing', symbol=key.F)(l.show_facing())
Parameters:include_angle – If True, then the actual angle will be shown along with the direction name.
show_nearest_door(max_distance: Optional[float] = None) → Callable[[], None]

Return a callable that will speak the position of the nearest door.

Parameters:max_distance –

The maximum distance between the current coordinates and the nearest door where the door will still be reported.

If this value is None, then any door will be reported.
sort_boxes() → List[earwax.mapping.box.Box]

Return children sorted by area.

turn(amount: int) → Callable[[], None]

Return a turn function.

Return a function that will turn the perspective by the given amount and dispatch the on_turn event.

For example:

l = BoxLevel(...)
l.action('Turn right', symbol=key.D)(l.turn(45))
l.action('Turn left', symbol=key.A)(l.turn(-45))

The resulting angle will always be in the range 0-359.

Parameters:amount –

The amount to turn by.

Positive numbers turn clockwise, while negative numbers turn anticlockwise.
walls_between(end: earwax.point.Point, start: Optional[earwax.point.Point] = None) → int

Return the number of walls between two points.

Parameters:
  • end – The target coordinates.
  • start –

    The coordinates to start at.

    If this value is None, then the current coordinates will be used.
class earwax.mapping.box_level.CurrentBox(coordinates: earwax.point.Point, box: earwax.mapping.box.Box[typing.Any][Any])

Bases: object

Store a reference to the current box.

This class stores the position too, so that caching can be performed.

Variables:
  • coordinates – The coordinates that were last checked.
  • box – The last current box.
class earwax.mapping.box_level.NearestBox(box: earwax.mapping.box.Box, coordinates: earwax.point.Point, distance: float)

Bases: object

A reference to the nearest box.

Variables:
  • box – The box that was found.
  • coordinates – The nearest coordinates to the ones specified.
  • distance – The distance between the supplied coordinates, and coordinates.