pyxen.world.get()

Retrieve an entity by its name.

world.get(*, name=None)

Returns the first entity that matches the given name.

Basic Usage

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

If an entity named "player" exists, it is returned. If not, None is returned.

Parameters

The parameter is keyword-only.

Return Value

Example

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

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

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

Deterministic Behavior

If multiple entities share the same name:

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

Then:

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

Returns the entity with the lowest entity ID index.

This guarantees:

• Deterministic behavior
• Stable results across runs
• Predictable gameplay logic

Safe Usage Pattern

Always check for None:

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

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

Common Use Cases

Access a Unique Player Entity

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

Access a UI Element

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

Singleton Entity Pattern

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

Naming Entities

You can set or change a name:

e.name = "boss"

Or during spawn:

world.spawn(name="boss")

See: pyxen.Entity

Internals

world.get():

1. Searches the internal name map
2. Retrieves the lowest-ID matching entity
3. Returns a lightweight Entity handle
4. Returns None if not found

Names are stored engine-side.

Python stores no entity data.

Important Notes

• Names are not required to be unique
• Lookup is deterministic
• Slower than a query to world.all()
• Ideal for singleton-like entities

When Not to Use It

Avoid using world.get() in tight loops.

For bulk operations, prefer:

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

Use get() for:

• Single entities
• Known unique objects
• Initialization logic

Summary

world.get():

• Retrieves entities by name
• Returns first match (lowest ID)
• Returns None if not found
• Deterministic and safe

It is a convenience utility for targeted lookups in an ECS world.