`pyxen.world.spawn()`

Crée une nouvelle Entity dans le monde et lui attache optionnellement des composants (sprite, son, musique, map, corps physique, etc.).

C’est le moyen principal d’ajouter des objets à votre scène.

Syntaxe

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

Tous les arguments sont par mot-clé uniquement.

Paramètres

Paramètre	Type	Description
`name`	`str`	Nom optionnel pour l’entité. Utile pour le débogage ou les recherches.
`sprite`	`Sprite`	Attacher un composant sprite. Doit être une instance de Sprite.
`x`	`float`	Position X initiale dans le monde. Défaut : `0.0`
`y`	`float`	Position Y initiale dans le monde. Défaut : `0.0`
`parent`	`Entity`	Entité parente. Active la hiérarchie de transforms.
`layer`	`int`	Couche de rendu. Par défaut : la couche du parent ou la couche par défaut du monde.
`sound`	`Sound`	Attacher un composant son.
`music`	`Music`	Attacher un composant musique (streamé/décodé).
`map`	`GridMapInfo`	Créer un composant GridMap à partir des informations de map.
`body`	`GridBody`	Attacher un composant physique GridBody.

Retour

Entity

Une instance d’entité nouvellement créée.

Comportement du Transform

Chaque entité créée reçoit automatiquement un Transform :

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

Actuellement, seuls x et y sont configurables au moment du spawn.

Résolution de la couche

La couche est déterminée dans cet ordre :

Argument layer explicite
Couche du parent (si parent est défini)
Couche par défaut du monde

Exemples

Créer une entité basique

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

Créer avec un Sprite

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

Créer en tant qu’enfant

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

Les entités enfants héritent de la hiérarchie de transforms et de la couche (sauf si explicitement remplacée).

Créer avec un Sound

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

Un composant Sound est attaché et prêt pour la lecture.

Créer avec une Music

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

La musique utilise un décodeur interne et est attachée à l’entité.

Créer une Grid Map

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

Crée un composant GridMap initialisé à partir du GridMapInfo fourni.

Créer avec un corps physique

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

Attache un composant GridBody pour la collision sur grille.

Résumé des composants

Selon les arguments fournis, l’entité peut recevoir :

Transform (toujours)
Name (optionnel)
Sprite
Sound
Music
GridMap
GridBody
Relation parente
Assignation de couche

Erreurs de type

La fonction lèvera un TypeError si :

sprite n’est pas un Sprite
parent n’est pas une Entity
Les types de composants ne correspondent pas aux classes attendues

Exemple :

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

Notes

Les entités sont légères.
Les composants sont optionnels.
L’entité est immédiatement enregistrée dans le monde.
La hiérarchie et les couches sont résolues au moment du spawn.

Philosophie de conception

spawn() est volontairement orienté composants.

Vous ne créez pas de sous-classes. Vous composez le comportement en attachant des composants.

Cela rend Pyxen :

Prévisible
Orienté données
Accessible aux débutants
Cohérent avec l’ECS