Unreal

如果你用 Unreal 制作过游戏，要开始使用 All Out，你需要了解一些关键差异！

---

本指南适用于从 Unreal Engine（Blueprints / C++）转向 All Out 和 CSL （All Out 的自定义脚本语言）。

最大的转变（思维模型）

在 Unreal 中，你通常会从以下角度思考：

• 世界中的 Actor （生成、复制、拥有）
• 组件 附加到 Actor 上
• Blueprint 图 / C++ 驱动游戏玩法
• RPC + 复制 由你显式编写

在 All Out 中，你通常会从以下角度思考：

• 场景中的实体 （带有组件）
• 组件 （引擎提供的 + 你自己的 CSL 组件）
• 技能 用于玩家操作（以移动端优先的 UI + 冷却 + 瞄准）
• 共享预测式游戏玩法 状态同步是自动的（大多数玩法无需自定义 RPC 管线）
• 2D 变换 using v2 位置和缩放，再加一个旋转角度

快速映射：Unreal → All Out / CSL

Unreal	All Out / CSL	备注
UWorld / Level	场景	实体存在于场景中；你也可以在运行时创建/销毁它们。
AActor	实体	实体具有 2D 变换和组件。
Actor 位置	Entity.local_position / world_position	决定 Unreal 的 X/Y/Z 如何映射到游戏的 2D X/Y 平面。
Actor 旋转	Entity.local_rotation	All Out 使用一个以度为单位的旋转角度。
Actor 缩放	Entity.local_scale	All Out 使用 v2；没有玩法层面的 Z 缩放。
UActorComponent	组件	你通过编写 CSL 组件并将其附加到实体上来实现玩法。
BeginPlay	ao_start	组件生命周期入口点。
Tick(float DeltaTime)	ao_update(dt) / ao_late_update(dt)	对于引擎使用的 UI/输入模式（例如技能按钮），请使用延迟更新。
Blueprint 图	CSL 代码	基于文本，作为项目的一部分进行编译。
Pawn/Character	Player_Base 子类	你的玩家逻辑通常位于一个 Player 组件/类上。
输入映射	技能 + 按键绑定	以移动端优先：优先使用技能按钮，而不是原始输入。
复制（Replicated 变量）	自动状态同步	编写一条预测式玩法路径，而不是分别编写客户端/服务器版本。
RPC（服务器, 客户端, NetMulticast)	通常不需要	使用引擎功能（例如通知），而不是让自定义 RPC 变得四处散落。
Actor 生成	Scene.create_entity() / Scene.instantiate(Prefab_Asset)	Prefab 是资源，可以被实例化。
UAsset 引用	get_asset(...)	资源位于 /res ，并通过路径引用。

你的第一个 CSL 文件（导入）

CSL 使用单一的“根”导入模式：在 main.csl中导入，不要把导入散落到每个文件里。

// main.csl
import "core:ao"
import "ui"   // 如果你创建了 /ui 文件夹并希望它在作用域中

实体与组件（相对于 Actor 与组件）

在运行时创建实体

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

添加并访问组件

my := entity.add_component(My_Component);
sprite := entity.get_component(Sprite_Renderer);

// 销毁实体（以及它的组件）
entity.destroy();

编写自定义组件（生命周期）

Spinner :: class : Component {
    speed: float;

    ao_start :: method() {
        speed = 1.0;
    }

    ao_update :: method(dt: float) {
        entity.set_local_rotation(entity.local_rotation + speed * dt);
    }
}

全局生命周期过程会在每个参与的场景模拟中运行；它们并不只在服务器上执行。后加入的客户端可能会收到一个其 start 生命周期已经运行过的组件，因此必要时请在 ao_on_state_sync 中根据同步状态重建表现层。参见 游戏/帧生命周期.

遍历实体/组件

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

for p: component_iterator(Player) {
    // ...
}

玩家操作：使用技能（而不是原始输入）

Unreal 项目通常从输入绑定（Enhanced Input）开始，然后在其上构建 UI/UX。在 All Out 中， 技能 是实现玩家操作的默认方式，具有：

• 一致的 适合移动端的 按钮 UI
• 冷却
• 可选瞄准（移动端拖拽瞄准，PC 端鼠标瞄准）

从以下内容绘制技能按钮： Player.ao_late_update 内部 is_local_or_server():

Player :: class : Player_Base {
    ao_late_update :: method(dt: float) {
        if this.is_local_or_server() {
            draw_ability_button(this, Shoot_Ability, 0);
            draw_ability_button(this, Dodge_Roll, 1);
        }
    }
}

请参见： 技能 以获取完整 API 和模式。

网络：‘复制’通常不是你的工作（大多数时候）

与 Unreal 复制不同之处

• 普通玩法运行在预测客户端和权威服务器上。
• 通常你 不需要编写 RPC 来实现标准玩法流程。
• 你仍然必须从 多玩家 的角度来设计：避免全局状态；将每个玩家的状态存储在玩家实例上。
• 不要用 Game.is_server() ，否则你会禁用预测。

玩家 UI 与本地视觉覆盖

使用以下模式：

• is_local_or_server() 用于玩家的 输入 + 游戏 UI
• is_local() 仅用于 玩家专属的视觉覆盖

Player :: class : Player_Base {
    ao_late_update :: method(dt: float) {
        if this.is_local_or_server() {
            // 输入 + 游戏 UI
        }
        if this.is_local() {
            // 仅此玩家应看到的视觉覆盖
        }
    }
}

参见 网络基础.

资源、Prefab 和路径

其中 /res 文件夹

资源位于 /res。在引用资源时， 省略 /res 路径中的

button := get_asset(Texture_Asset, "ui/button.png");
click := get_asset(SFX_Asset, "sfx/click.wav");
font := get_asset(Font_Asset, "$AO/fonts/Barlow-Black.ttf"); // 引擎资源

预制体

Prefab 是资源，可以通过以下方式实例化： 场景:

prefab := get_asset(Prefab_Asset, "Enemies/Slime.prefab");
enemy_entity := Scene.instantiate(prefab);

碰撞与重叠事件（Unreal 中的常见陷阱）

一个启用的碰撞体，带有 is_trigger 设置后可调用 on_trigger_start, on_trigger_stay，以及 on_trigger_end。每个回调都会接收触发器碰撞体和另一个碰撞体。 移动代理 并非必需。

CSL 没有提供通用的实碰撞回调，等同于 OnHit。请使用触发器来实现玩法重叠行为。对于广域感知，查询附近的组件：

nearby: [..]Pickup;
Scene.get_all_components_in_range(player_pos, 2.0, ref nearby);
for p: nearby {
    // ...
}

请参见： 导航网格与碰撞.

UI 差异（UMG vs CSL UI）

All Out 游戏是 以移动端优先，因此避免构建仅键盘的 UX。使用引擎的 UI 工具和技能按钮。

对于自定义 UI，从以下开始： UI 基础 或 UIDoc 快速入门.

对局流程、背包、可交互对象

如果你在寻找常见 Unreal 玩法系统的对应项：

• 可交互对象: 可交互对象
• Inventory: Inventory
• 匹配 / 中心区游戏: 匹配 / 中心区游戏
• 移动代理 / NPC: 移动代理 / NPC
• Spine 动画 （如果你使用了 Paper2D / flipbook）： Spine

Unreal 到 CSL 的“坑”

• 不要构建自定义 RPC/复制层：从共享的预测式玩法路径开始，并让引擎同步状态。
• 不要用 Game.is_server()来保护玩法：普通玩法也必须在预测客户端上运行。
• 避免为玩法状态使用全局单例：会有多个玩家连接；将状态存储在玩家或相关组件实例上。
• 导入是集中式的：只需从 main.csl导入一次，而不是每个文件都导入。
• 动作优先使用技能：它能一致地解决移动端 UX + 冷却 + 瞄准问题。
• 将 3D 设计映射到 2D：使用渲染器层，而不是 Z 变换。

下一步

• 阅读 技能
• 阅读 导航网格与碰撞
• 快速浏览 可交互对象 和 Inventory