pyxen.world.get()

通过名称检索实体。

world.get(*, name=None)

返回第一个匹配给定名称的实体。

基本用法

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

如果存在名为 "player" 的实体，则返回该实体。 如果不存在，则返回 None。

参数

该参数为仅关键字参数。

返回值

示例

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

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

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

确定性行为

如果多个实体同名：

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

则：

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

返回实体 ID 索引最小的实体。

这保证了：

• 确定性行为
• 跨运行的稳定结果
• 可预测的游戏逻辑

安全使用模式

始终检查 None：

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

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

常见用例

访问唯一的玩家实体

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

访问 UI 元素

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

单例实体模式

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

命名实体

你可以设置或更改名称：

e.name = "boss"

或在生成时：

world.spawn(name="boss")

参见：pyxen.Entity

内部实现

world.get()：

1. 搜索内部名称映射
2. 检索 ID 最小的匹配实体
3. 返回轻量级 Entity 句柄
4. 如果未找到则返回 None

名称存储在引擎端。

Python 不存储实体数据。

重要注意事项

• 名称不要求唯一
• 查找是确定性的
• 比 world.all() 查询慢
• 适用于单例式实体

何时不应使用

避免在紧密循环中使用 world.get()。

对于批量操作，优先使用：

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

使用 get() 的场景：

• 单个实体
• 已知的唯一对象
• 初始化逻辑

总结

world.get()：

• 通过名称检索实体
• 返回第一个匹配（最小 ID）
• 如果未找到则返回 None
• 确定性且安全

它是 ECS 世界中定向查找的便捷工具。