bear_hug.ecs_widgets module

Two Layouts designed specifically for the ECS system.

class bear_hug.ecs_widgets.ECSLayout(chars, colors)

Bases: bear_hug.widgets.Layout

A Layout of entities.

This layout, besides visualization, provides collision detection. It is controlled entirely by events. Although Layout methods add_child and move_child are not overloaded, their use is discouraged. Just like a regular Layout, ECSLayout resides within a single bearlibterminal layer and therefore does not provide character overlap for overlapping entities. Who hides whom is currently determined by the order of widget addition, with newer entities on top of older ones (Z-levels are to be implemented in a future release).

Event conventions are as following:

BearEvent(event_type='ecs_create', event_value=entity_object)

Announces that a new Entity has been created and needs to be registered for ECSLayout. Does not cause it to be placed on screen. The same event tells the EntityTracker about any newly-created Entities. It should not be emitted until the Entity has at least an ID and a WidgetComponent.

BearEvent(event_type='ecs_add', event_value=(entity, x, y)).

Announces that the widget of the entity in question should be added to the ECSLayout at (x;y). This event should not be emitted before both entity and its widget have been created, and ‘ecs_create’ event has been emitted.

BearEvent(event_type='ecs_move', event_value=(entity, x, y))

Announces that the widget of the entity in question should be moved to (x; y). If the widget collides into the widget of another Entity (or multiple widgets), emits BearEvent('ecs_collide', other_entity_id) for each Entity that was collided into. If the widget touches Layout edges, emits BearEvent('ecs_collide', None) instead. In either case, collision does not automatically prevent movement.

BearEvent(event_type='ecs_remove', event_value=entity)

Announces that the widget of a given entity should be removed from the ECSLayout, but does not cause or imply the its destruction. It is to be used when the Entity currently on screen needs to be hidden, but is expected to be shown again later.

BearEvent(event_type='ecs_destroy', event_value=entity)

Announces that the widget of a given entity should be removed from the ECSLayout, as well as from its entities and widgets lists. This event is emitted when the entity is destroyed (eg by DestructorComponent) and used by EntityTracker to know which Entities no longer exist.

BearEvent(event_type='ecs_redraw')

Announces that the layout needs to be redrawn this tick, even if none of the events above have been emitted. This is useful if some widget (eg animation) has changed its chars or colors, but was not moved, added or deleted.

If at least one of these events was sent to the ECSLayout, it will redraw itself on ‘tick_over’.

Parameters:
  • chars – Layout BG chars
  • colors – Layout BG colors
add_entity(entity)

Register the entity to be displayed.

Assumes that the entity has a widget already. The widget is not actually shown until the ‘ecs_add’ event with its entity ID is emitted.

Parameters:entity – Entity instance
remove_entity(entity_id)

Forget about the registered entity and its widget.

Does not imply or cause the destruction of Entity object itself or any of its Component objects. Making sure that the entity is removed cleanly is not the Layout’s job.

Parameters:entity_id – Entity ID
on_event(event)

See class documentation

Parameters:event – BearEvent instance
class bear_hug.ecs_widgets.ScrollableECSLayout(chars, colors, view_pos=(0, 0), view_size=(10, 10))

Bases: bear_hug.widgets.Layout

A ECSLayout that can show only a part of its surface.

Like a ScrollableLayout, accepts chars and colors on creation, which should be the size of the entire layout, not just the visible area. The latter is initialized by view_pos and view_size arguments.

This class supports all ‘ecs_*’ events described in the docs for ECSLayout. In addition, it supports the following two two event types:

BearEvent(event_type='ecs_scroll_by', event_value=(x, y))

Shifts visible area by x chars horizontally and by y chars vertically.

BearEvent(event_type='ecs_scroll_to', event_value=(x, y)

Moves visible area to (x, y).

Both events cause BearLayoutException if event values require visible area to move beyond Layout borders.

Parameters:
  • chars – Layout BG chars.
  • colors – Layout BG colors.
  • view_pos – Top left corner of the initial visible area, 2-tuple (x, y).
  • view_size – The size of the visible area, 2-tuple (x, y).
add_child(child, pos, skip_checks=False)

Add a widget as a child at a given position.

The child has to be a Widget or a Widget subclass that haven’t yet been added to this Layout and whose dimensions are less than or equal to the Layout’s. The position is in the Layout coordinates, ie relative to its top left corner.

Parameters:
  • child – A widget to add.
  • pos – A widget position, (x, y) 2-tuple
resize_view(new_size)

Currently not implemented. :param new_size: :return:

scroll_to(pos)

Move field of view to pos.

Raises BearLayoutException on incorrect position

Parameters:pos – 2-tuple (x, y)
scroll_by(shift)

Move field of view by shift[0] to the right and by shift[1] down.

Raises BearLayoutException on incorrect position.

Parameters:shift – 2-tuple (dx, dy)
add_entity(entity)

Register the entity to be displayed. Assumes that the entity has a widget already.

The entity is not actually shown until the ‘ecs_add’ event is emitted :return:

remove_entity(entity_id)

Forget about the registered entity and its widget. Does not imply or cause the destruction of Entity object or any of its Component objects (except if this was the last reference). Making sure that the entity is removed cleanly is someone else’s job.

Parameters:entity_id – ID of the removed entity.
on_event(event)

See class documentation.

Parameters:event – BearEvent instance.