Scene Graph

Las entidades en Pyxen pueden organizarse en un árbol — padres e hijos. Este es el scene graph. Controla cómo las entidades heredan transformaciones, cómo se propaga la visibilidad y cómo se ordena el renderizado.

Relaciones padre-hijo

Cualquier entidad puede ser padre o hijo. Estableces la relación al momento de generar o después:

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

# o después
arm.parent = player

Cuando una entidad tiene un padre:

• Su posición (x, y) es relativa al padre. Si el padre se mueve, el hijo se mueve con él.
• La rotación y la escala también se heredan. Un hijo rotado 10 grados en un padre rotado 20 grados aparece a 30 grados.
• Puedes acceder a los hijos con entity.children.

Para separar una entidad de su padre:

arm.parent = None

Capas

Cada entidad tiene una capa (0-255). Las capas controlan el orden de renderizado: las capas inferiores se dibujan primero, las capas superiores se dibujan encima.

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"))

Dentro de una capa, las entidades se ordenan por profundidad. La profundidad se determina por la posición de la entidad en el scene graph — los hijos más profundos se renderizan después de sus padres.

Visibilidad

Las entidades tienen dos propiedades de visibilidad:

• visible — si esta entidad está configurada para mostrarse. Tú controlas esto.
• is_visible — si esta entidad se renderiza realmente. Esto tiene en cuenta la visibilidad del padre.

enemy.visible = False  # oculta esta entidad y todos sus hijos

Cuando ocultas un padre, todos sus hijos se vuelven invisibles también, incluso si su propia propiedad visible sigue siendo True. Esto facilita alternar grupos enteros — oculta un panel de UI y todo dentro desaparece.

Estructura de escena típica

Un patrón común es organizar tu juego en capas y grupos:

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

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

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

El arma sigue al jugador automáticamente. La UI siempre está encima. Ocultar ui_root oculta toda la UI.