`pyxen.world.spawn()`

在世界中创建一个新的 Entity 并可选地为其附加组件（sprite、sound、music、map、物理体等）。

这是向场景中添加对象的主要方式。

语法

entity = pyxen.world.spawn(
    *,
    name=None,
    sprite=None,
    x=None,
    y=None,
    parent=None,
    layer=None,
    sound=None,
    music=None,
    map=None,
    body=None
)

所有参数均为仅关键字参数。

参数

参数	类型	描述
`name`	`str`	实体的可选名称。用于调试或查找。
`sprite`	`Sprite`	附加精灵组件。必须是 Sprite 实例。
`x`	`float`	初始世界 X 位置。默认值：`0.0`
`y`	`float`	初始世界 Y 位置。默认值：`0.0`
`parent`	`Entity`	父实体。启用层级变换。
`layer`	`int`	渲染层。默认为父级的层或世界默认层。
`sound`	`Sound`	附加音效组件。
`music`	`Music`	附加音乐组件（流式/解码）。
`map`	`GridMapInfo`	从地图信息创建 GridMap 组件。
`body`	`GridBody`	附加 GridBody 物理组件。

返回值

Entity

新创建的 entity 实例。

变换行为

每个生成的实体都会自动获得一个 Transform：

x = 0.0
y = 0.0
scale_x = 1.0
scale_y = 1.0
rotation = 0.0

目前只有 x 和 y 可以在生成时配置。

层级解析

层级按以下顺序确定：

显式 layer 参数
父级的层（如果设置了 parent）
世界默认层

示例

生成基本实体

player = pyxen.world.spawn(x=32, y=16)

带 Sprite 生成

player = pyxen.world.spawn(
    name="Player",
    sprite=assets.player_sprite,
    x=32,
    y=16
)

作为子实体生成

weapon = pyxen.world.spawn(
    sprite=assets.sword,
    parent=player,
    x=8,
    y=0
)

子实体继承变换层级和层（除非被覆盖）。

带 Sound 生成

explosion = pyxen.world.spawn(
    sprite=assets.explosion,
    sound=assets.explosion_sfx,
    x=64,
    y=32
)

附加了一个 Sound 组件，可以立即播放。

带 Music 生成

music_entity = pyxen.world.spawn(
    music=assets.background_theme
)

Music 使用内部解码器并附加到实体上。

生成网格地图

level = pyxen.world.spawn(
    map=assets.level1_map
)

从提供的 GridMapInfo 创建 GridMap 组件。

带物理体生成

player = pyxen.world.spawn(
    sprite=assets.player,
    body=GridBody.dynamic(),
    x=10,
    y=5
)

附加一个 GridBody 组件用于基于网格的碰撞。

组件总结

根据提供的参数，实体可能获得：

Transform（始终）
Name（可选）
Sprite
Sound
Music
GridMap
GridBody
父级关系
层分配

类型错误

如果以下情况，函数将抛出 TypeError：

sprite 不是 Sprite
parent 不是 Entity
组件类型与预期类不匹配

示例：

pyxen.world.spawn(sprite="not a sprite")
# TypeError: spawn: sprite must be a Sprite

注意事项

实体是轻量级的。
组件是可选的。
实体会立即注册到世界中。
层级和分层在生成时解析。

设计理念

spawn() 是有意为组件驱动的。

你不需要创建子类。你通过附加组件来组合行为。

这使 Pyxen 保持：

可预测
数据导向
对初学者友好
ECS 一致性