pyxen.world.get()

Récupérer une entité par son nom.

world.get(*, name=None)

Renvoie la première entité correspondant au nom donné.

Utilisation basique

player = world.get(name="player")

Si une entité nommée "player" existe, elle est renvoyée. Sinon, None est renvoyé.

Paramètres

Le paramètre est par mot-clé uniquement.

Valeur de retour

Exemple

hero = world.spawn(name="player")

found = world.get(name="player")

if found:
    print("Found:", found.name)

Comportement déterministe

Si plusieurs entités partagent le même nom :

world.spawn(name="enemy")
world.spawn(name="enemy")

Alors :

enemy = world.get(name="enemy")

Renvoie l’entité avec l’index d’identifiant d’entité le plus bas.

Cela garantit :

• Un comportement déterministe
• Des résultats stables entre les exécutions
• Une logique de jeu prévisible

Pattern d’utilisation sûre

Vérifiez toujours la valeur None :

player = world.get(name="player")

if player is not None:
    player.x += 10

Cas d’utilisation courants

Accéder à une entité joueur unique

player = world.get(name="player")

Accéder à un élément d’interface

score_label = world.get(name="score_label")

Pattern d’entité singleton

camera = world.get(name="camera")

Nommer les entités

Vous pouvez définir ou changer un nom :

e.name = "boss"

Ou lors du spawn :

world.spawn(name="boss")

Voir : pyxen.Entity

Fonctionnement interne

world.get() :

1. Recherche dans la table de noms interne
2. Récupère l’entité correspondante avec l’ID le plus bas
3. Renvoie un handle Entity léger
4. Renvoie None si non trouvée

Les noms sont stockés côté moteur.

Python ne stocke aucune donnée d’entité.

Notes importantes

• Les noms ne sont pas nécessairement uniques
• La recherche est déterministe
• Plus lente qu’une requête via world.all()
• Idéale pour les entités de type singleton

Quand ne pas l’utiliser

Évitez d’utiliser world.get() dans des boucles fréquentes.

Pour les opérations en masse, préférez :

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

Utilisez get() pour :

• Les entités individuelles
• Les objets connus comme uniques
• La logique d’initialisation

Résumé

world.get() :

• Récupère les entités par nom
• Renvoie la première correspondance (ID le plus bas)
• Renvoie None si non trouvée
• Déterministe et sûre

C’est un utilitaire pratique pour les recherches ciblées dans un monde ECS.