Scene Graph

Entities in Pyxen can be organized into a tree — parents and children. This is the scene graph. It controls how entities inherit transforms, how visibility propagates, and how rendering is ordered.

Parent-child relationships

Any entity can be a parent or a child. You set the relationship at spawn time or later:

# at spawn
arm = world.spawn(x=10, y=0, parent=player)

# or later
arm.parent = player

When an entity has a parent:

• Its position (x, y) is relative to the parent. If the parent moves, the child moves with it.
• Rotation and scale are inherited too. A child rotated 10 degrees on a parent rotated 20 degrees appears at 30 degrees.
• You can access children with entity.children.

To detach an entity from its parent:

arm.parent = None

Layers

Every entity has a layer (0–255). Layers control rendering order: lower layers are drawn first, higher layers are drawn on top.

background = world.spawn(layer=0, sprite=Sprite("sky"))
player = world.spawn(layer=1, sprite=Sprite("hero"))
ui = world.spawn(layer=2, sprite=Sprite("health_bar"))

Within a layer, entities are sorted by depth. Depth is determined by the entity’s position in the scene graph — deeper children render after their parents.

Visibility

Entities have two visibility properties:

• visible — whether this entity is set to be shown. You control this.
• is_visible — whether this entity is actually rendered. This accounts for parent visibility.

enemy.visible = False  # hide this entity and all its children

When you hide a parent, all its children become invisible too, even if their own visible property is still True. This makes it easy to toggle entire groups — hide a UI panel and everything inside it disappears.

Typical scene structure

A common pattern is to organize your game into layers and groups:

def start():
    # layer 0: background
    world.spawn(layer=0, sprite=Sprite("tilemap"))

    # layer 1: game entities
    player = world.spawn(name="player", layer=1, sprite=Sprite("hero"))
    weapon = world.spawn(parent=player, x=8, y=0, sprite=Sprite("sword"))

    # layer 2: UI
    ui_root = world.spawn(name="ui", layer=2)
    world.spawn(parent=ui_root, x=10, y=10, sprite=Sprite("heart"))

The weapon follows the player automatically. The UI is always on top. Hiding ui_root hides the entire UI.