`pyxen.world.spawn()`

Crea un nuevo Entity en el mundo y opcionalmente le adjunta componentes (sprite, sonido, música, mapa, cuerpo físico, etc.).

Esta es la forma principal de añadir objetos a tu escena.

Sintaxis

entity = pyxen.world.spawn(
    *,
    name=None,
    sprite=None,
    x=None,
    y=None,
    parent=None,
    layer=None,
    sound=None,
    music=None,
    map=None,
    body=None
)

Todos los argumentos son solo por nombre.

Parámetros

Parámetro	Tipo	Descripción
`name`	`str`	Nombre opcional para la entidad. Útil para depuración o búsquedas.
`sprite`	`Sprite`	Adjunta un componente sprite. Debe ser una instancia de Sprite.
`x`	`float`	Posición X inicial en el mundo. Por defecto: `0.0`
`y`	`float`	Posición Y inicial en el mundo. Por defecto: `0.0`
`parent`	`Entity`	Entidad padre. Habilita transformaciones jerárquicas.
`layer`	`int`	Capa de renderizado. Por defecto la capa del padre o la capa por defecto del mundo.
`sound`	`Sound`	Adjunta un componente de sonido.
`music`	`Music`	Adjunta un componente de música (streaming/decodificado).
`map`	`GridMapInfo`	Crea un componente GridMap a partir de la información del mapa.
`body`	`GridBody`	Adjunta un componente físico GridBody.

Devuelve

Entity

Una instancia de entidad recién creada.

Comportamiento del Transform

Cada entidad creada recibe automáticamente un Transform:

x = 0.0
y = 0.0
scale_x = 1.0
scale_y = 1.0
rotation = 0.0

Actualmente, solo x e y son configurables al momento de la creación.

Resolución de capa

La capa se determina en este orden:

Argumento layer explícito
Capa del padre (si se establece parent)
Capa por defecto del mundo

Ejemplos

Crear una entidad básica

player = pyxen.world.spawn(x=32, y=16)

Crear con un Sprite

player = pyxen.world.spawn(
    name="Player",
    sprite=assets.player_sprite,
    x=32,
    y=16
)

Crear como hijo

weapon = pyxen.world.spawn(
    sprite=assets.sword,
    parent=player,
    x=8,
    y=0
)

Las entidades hijas heredan la jerarquía de transformación y la capa (a menos que se sobrescriba).

Crear con Sound

explosion = pyxen.world.spawn(
    sprite=assets.explosion,
    sound=assets.explosion_sfx,
    x=64,
    y=32
)

Un componente Sound se adjunta y está listo para reproducción.

Crear con Music

music_entity = pyxen.world.spawn(
    music=assets.background_theme
)

Music usa un decodificador interno y se adjunta a la entidad.

Crear un Grid Map

level = pyxen.world.spawn(
    map=assets.level1_map
)

Crea un componente GridMap inicializado a partir del GridMapInfo proporcionado.

Crear con un cuerpo físico

player = pyxen.world.spawn(
    sprite=assets.player,
    body=GridBody.dynamic(),
    x=10,
    y=5
)

Adjunta un componente GridBody para colisión basada en cuadrícula.

Resumen de componentes

Dependiendo de los argumentos proporcionados, la entidad puede recibir:

Transform (siempre)
Name (opcional)
Sprite
Sound
Music
GridMap
GridBody
Relación de padre
Asignación de capa

Errores de tipo

La función producirá un TypeError si:

sprite no es un Sprite
parent no es un Entity
Los tipos de componentes no coinciden con las clases esperadas

Ejemplo:

pyxen.world.spawn(sprite="not a sprite")
# TypeError: spawn: sprite must be a Sprite

Notas

Las entidades son ligeras.
Los componentes son opcionales.
La entidad se registra inmediatamente en el mundo.
La jerarquía y las capas se resuelven en el momento de la creación.

Filosofía de diseño

spawn() es intencionalmente orientado a componentes.

No creas subclases. Compones comportamiento adjuntando componentes.

Esto mantiene Pyxen:

Predecible
Orientado a datos
Amigable para principiantes
Consistente con ECS