Entities

We will assume you are familiar with the pygame-ce library fundamentals in the following. If not, please refer to the pygame-ce docs.

Attributes

Entities are the things that fill your scene — players, NPCs, interfaces, or even a whole level.

Each entity has the following attributes:

• rect : pygame.FRect — position and size
• uid : int — unique id for every entity created
• tags : list[str] — list of tags
• debug_color: tuple | str — color used to outline the entity in the debugging view
• parent_scene : Scene | None — pointer to the scene the entity belongs to, or None if it is not added

Useful methods:

• set_position(self, x, y) — set top-left (pass None to keep an axis unchanged)
• set_center(self, x, y) — set center (pass None to keep an axis unchanged)
• add_tags(self, *tags) / remove_tags(self, *tags)
• has_tags(self, *tags) / has_any_tags(self, *tags)
• kill() — remove this entity from its parent scene

Drawable

Drawable extends Entity with a surface and draw state:

• visible, render_order, surface, blit_flags
• set_render_order(n) — controls draw order within the scene (lower first)
• set_visible, set_alpha, set_size
• draw(camera) — blits the surface if visible and in view

GUI widgets inherit from Drawable through Widget.

Lifecycle

As soon as an entity is added to a scene via scene.add(...), it is managed by that scene:

1. The scene propagates events to the entity
2. The scene updates the entity every frame
3. The scene draws the entity if it is a Drawable

Adds and removes are deferred by one frame and applied in flush_entity_changes().

When an entity is attached or detached, these hooks run:

• do_when_added(self) — called when the entity joins a scene
• do_when_removed(self) — called when the entity leaves a scene

Override them for setup/teardown specific to that entity.