实体与组件

All Out 游戏围绕实体（世界中的事物）和组件（附加到实体上的行为/数据）构建。

如果你以前用过 Unity：可以理解为“GameObject + 组件”。如果你用过 Roblox：可以理解为“Instance + 脚本/组件”。核心思想是相同的： 你通过向实体添加组件来组合玩法。

实体

实体通常以两种方式存在：

• 放置在编辑器中：它们在启动时就已经存在于场景中。
• 运行时创建：你从脚本中生成它们。

创建和销毁实体

entity := Scene.create_entity();
entity.set_local_position({10, 20});
entity.set_local_scale({2.5, 2.5});
entity.set_local_rotation(0);

// 完成后：
entity.destroy();

销毁实体也会销毁其组件。销毁实体后，不要再持有对其组件的引用。

遍历实体

for e: entity_iterator() {
    // ...
}

组件

组件是行为的基本单元。组件“附着”在实体上，并且可以读取/修改该实体。

获取和添加组件

sprite := entity.get_component(Sprite_Renderer);

player := entity.get_component(Player);

my_comp := entity.add_component(My_Component);

遍历组件

for enemy: component_iterator(Enemy) {
    enemy.tick_ai();
}

你会经常使用的内置组件

Sprite_Renderer

texture := get_asset(Texture_Asset, "ui/button.png");

sprite := entity.get_component(Sprite_Renderer);
sprite.set_texture(texture);
sprite.color = {1, 1, 1, 1}; // RGBA
sprite.depth_offset = 0.5;
sprite.layer = 10;

// 可选：使用自定义材质。如果渲染器应拥有它，则传入 true。
// sprite.set_material(material, true);

预制体（Prefab_Asset)

预制体必须在编辑器中创建。在脚本中，你要实例化它们。

prefab := get_asset(Prefab_Asset, "MyPrefab.prefab");
spawned := Scene.instantiate(prefab);
spawned.set_local_position({1, 3});

Spine（Spine_Animator)

如果你在使用 2D 动画角色，你通常会使用 Spine_Animator。参见 Spine.

编写自定义组件

在独立文件中创建新组件（例如 orbiter.csl），并通过以下任一方式将它们附加到实体：

• 在编辑器中手动或
• 在运行时 使用 entity.add_component(...)

组件可以实现生命周期回调：

• ao_start()
• ao_update(dt)
• ao_late_update(dt) （在所有更新之后）
• ao_end() （在销毁时）

示例：

Orbiter :: class : Component {
    center: v2;
    radius: float;
    speed: float;
    angle: float;

    ao_start :: method() {
        center = entity.local_position;
        radius = 2;
        speed = 1;
        angle = 0;
    }

    ao_update :: method(dt: float) {
        angle += speed * dt;

        offset_x := cos(angle) * radius;
        offset_y := sin(angle) * radius;

        entity.set_local_position({center.x + offset_x, center.y + offset_y});
    }
}

全局脚本的生命周期方法（ao_start, ao_update，...）在下文中介绍 游戏/帧生命周期.

序列化字段（@ao_serialize)

使用 @ao_serialize 用于在 Inspector 中公开字段，并将其包含在场景和 JSON 序列化中。

Chest :: class : Component {
    capacity: int @ao_serialize;
}

触发器和邻近查询

触发器碰撞体提供 on_trigger_start, on_trigger_stay，以及 on_trigger_end 回调。参见 Navmesh 和碰撞 了解设置和回调签名。

当你需要获取半径内的每个组件，或者只获取最近的那个时，就使用邻近查询。

有用的辅助函数：

Scene.get_all_components_in_range     :: proc(position: v2, range: float, results: ref [..]$T)
Scene.get_closest_component_in_range  :: proc(position: v2, range: float, $T: typeid) -> T, bool

示例：

nearby: [..]Enemy;
Scene.get_all_components_in_range(player.entity.world_position, 5.0, ref nearby);

for e: nearby {
    // ...
}

closest_pickup, found := Scene.get_closest_component_in_range(player.entity.world_position, 2.0, Pickup);
if found {
    // ...
}

最佳实践

• 每个玩家的状态应放在 Player. 避免使用会在多玩家情况下出问题的全局变量。
• 玩法行为优先使用组件。 这样你就会得到可复用的模块，可以挂到不同的实体上。
• 从……绘制玩家 UI Player.ao_late_update. 将其包装在 is_local_or_server().
• 使用 is_local() 中，仅用于玩家特定的视觉覆盖。 不要在其中更改游戏玩法或 UI 状态。