pyxen.world.all()

Requêter les entités par composant.

world.all(*components, without=None)

Renvoie un itérateur sur toutes les entités correspondant à la requête.

C’est le cœur du système ECS de Pyxen.

Utilisation basique

for e in world.all("enemy"):
    e.health.value -= 1

Cela itère sur toutes les entités possédant le composant "enemy".

Les composants sont identifiés par nom (chaîne de caractères).

Composants multiples

Vous pouvez exiger plusieurs composants :

for e in world.all("position", "velocity"):
    e.position.x += e.velocity.x

Cela renvoie uniquement les entités possédant les deux composants.

Pensez-y comme :

Requête AND

Exclure des composants (without)

Vous pouvez exclure les entités possédant certains composants avec le mot-clé without.

for e in world.all("enemy", without=("dead",)):
    attack(e)

Cela signifie :

• Doit avoir "enemy"
• Ne doit PAS avoir "dead"

Syntaxe complète

world.all(
    "required_component_1",
    "required_component_2",
    ...,
    without=("excluded_component_1", "excluded_component_2")
)

• Les composants requis sont des arguments positionnels
• without doit être un tuple

Exemple : Jeu de la Vie

for cell in world.all("cell"):
    if cell.alive and cell.next_alive:
        cell.color = (0.25, 0.15, 0.85, 1.0)

Exemple : Cellules vivantes uniquement

for cell in world.all("cell", without=("dead",)):
    update(cell)

Composants marqueurs dans les requêtes

Les composants marqueurs (composants booléen uniquement) fonctionnent exactement de la même façon.

e.enemy = True

Puis :

for e in world.all("enemy"):
    ...

Les marqueurs sont extrêmement efficaces dans les requêtes.

Composants intégrés dans les requêtes

Vous pouvez requêter les entités par leurs composants intégrés :

for e in world.all("sprite"):
    e.color = (1, 0, 0, 1)

Les noms de composants intégrés suivants sont supportés :

Vous pouvez combiner composants intégrés et personnalisés dans la même requête :

for e in world.all("sprite", "enemy"):
    e.color = (1, 0, 0, 1)

L’exclusion fonctionne aussi :

for e in world.all("sprite", without=("body",)):
    ...

Comportement des requêtes

En interne :

1. La requête collecte les schémas de composants requis
2. Collecte les schémas de composants exclus
3. Itère sur les entités correspondantes
4. Produit des handles Entity

Si un nom de composant n’existe pas :

• Un avertissement est enregistré
• La requête continue néanmoins

Notes importantes

Les noms de composants doivent être des chaînes

world.all("health")

Correct.

world.all(health)

Incorrect.

without doit être un tuple

world.all("enemy", without=("dead",))

Correct.

world.all("enemy", without="dead")

Incorrect.

Ce que ça renvoie

world.all() renvoie un itérateur.

Vous pouvez :

list(world.all("enemy"))

Ou :

for e in world.all("enemy"):
    ...

Notes de sécurité

Si un composant requis n’existe pas :

• Un avertissement est enregistré
• La requête continue

Si trop de composants sont passés, la limite interne du moteur s’applique.