pyxen.world.get()

通过名称检索实体。

world.get(name)

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

基本用法

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

如果存在名为 "player" 的实体，则返回该实体。 如果不存在，则返回 None：即空实体，is None 和 == None 对它成立，if 把它当作假。给它设置字段会在“问题”中给出警告，游戏继续运行。被销毁的实体会失去名字，所以从那一帧起 get 什么也找不到。

参数

可以按位置或按名称传入：world.get("player") 与 world.get(name="player") 相同。

返回值

示例

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 世界中定向查找的便捷工具。