Unreal

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

---

本指南面向从 Unreal Engine 开发者（Blueprints / C++）过渡到 All Out 和 CSL （All Out 的自定义脚本语言）。

重大转变（思维模型）

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

• 世界中的 Actor （生成、复制、归属）

• 组件 附加到 Actor 上的

• Blueprint 图 / C++ 驱动游戏玩法

• RPC + 复制 你显式编写

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

• 场景中的实体 （带有组件）

• 组件 （引擎提供的 + 你自己的 CSL 组件）

• 技能 用于玩家操作（移动优先 UI + 冷却 + 瞄准）

• 服务器权威的游戏玩法 其中 状态同步是自动的 （大多数游戏玩法不需要自定义 RPC 管线）

快速映射：Unreal → All Out / CSL

Unreal	All Out / CSL	说明
UWorld / 关卡	场景	实体存在于场景中；你也可以在运行时创建/销毁它们。
AActor	实体	实体具有变换和组件。
UActorComponent	Component	你通过编写 CSL 组件并将其附加到实体上来编写游戏玩法。
BeginPlay	ao_start	组件生命周期入口点。
Tick(float DeltaTime)	ao_update(dt) / ao_late_update(dt)	使用晚更新来处理引擎使用的 UI/输入模式（例如技能按钮）。
Blueprint 图	CSL 代码	基于文本，并作为项目的一部分进行编译。
Pawn/Character	Player_Base 子类	你的玩家逻辑通常位于一个 Player 组件/类上。
输入映射	技能 + 键位绑定	移动优先：优先使用技能按钮，而不是原始输入。
复制（Replicated 变量）	自动状态同步	除非你确实需要，否则避免自己构建复制/RPC 模式。
RPC（服务器, 客户端, NetMulticast)	通常不需要	使用引擎提供的机制（例如通知）来替代自定义 RPC 的泛滥。
Actor 生成	Scene.create_entity() / 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);
    }
}

遍历实体/组件

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

foreach 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 用于标准游戏流程。

• 但你仍然必须以 多个玩家 为前提进行设计：避免全局状态；将每个玩家的状态存储在玩家实例上。

仅客户端逻辑 vs 服务器/共享逻辑

使用以下模式：

• is_local_or_server() 用于 输入 + 游戏 UI （在服务器 + 本地客户端上运行）

• is_local() 用于 纯视觉 UI/效果 （仅在本地客户端上运行）

Player :: class : Player_Base {
    ao_late_update :: method(dt: float) {
        if is_local_or_server() {
            // 输入 + 游戏 UI
        }
        if is_local() {
            // 仅视觉 UI/效果
        }
    }
}

资源、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结尾的文件夹），并且可以被实例化：

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

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

如果你习惯于 Unreal 的重叠/命中回调（OnComponentBeginOverlap, OnHit），请注意 CSL 游戏玩法通常使用 查询 而不是事件回调。

常见模式：查询附近组件并检查距离：

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 文档并遵循标准模式（除非文档说明，否则不要发明类似 UMG 的 widget 树）。

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

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

• 可交互对象: 可交互对象

• Inventory: Inventory

• 匹配 / Hub 游戏: 匹配 / Hub 游戏

• 移动代理 / NPC: 移动代理 / NPC

• Spine 动画 （如果你使用过 Paper2D / flipbooks）： Spine

Unreal 到 CSL 的“坑点”

• 不要构建自定义 RPC/复制层：从服务器权威逻辑开始，让引擎同步状态。

• 避免将游戏状态放在全局单例中：会有多个玩家连接；将状态存储在玩家或相关组件实例上。

• 导入是集中管理的：从 main.csl一次性导入文件夹，而不是按文件导入。

• 优先将操作交给 Abilities：它能一致地解决移动端 UX + 冷却 + 瞄准。

• 外观与游戏玩法：仅视觉效果保持本地；游戏状态保持服务器权威。

下一步

• 先阅读 技能

• 先阅读 导航网格与碰撞

• 浏览 可交互对象 和 Inventory