Unreal

如果你曾使用 Unreal 构建游戏，有一些关键差异你需要了解才能在 All Out 上入门！

---

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

重大转变（思维模型）

在 Unreal 中你通常这样思考：

• 世界中的 Actor （生成、复制、拥有）

• 组件 附加到 Actor 上

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

• RPC + 复制 由你显式编写

在 All Out 中你通常会这样思考：

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

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

• 能力（Abilities） 用于玩家操作（以移动为先的 UI + 冷却 + 瞄准）

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

快速映射：Unreal → All Out / CSL

Unreal	All Out / CSL	备注
UWorld / 关卡	Scene	实体存在于场景中；你也可以在运行时创建/销毁它们。
AActor	实体	实体具有变换和组件。
UActorComponent	Component	你通过编写 CSL 组件并将它们附加到实体上来创作游戏玩法。
BeginPlay	尤其是	组件生命周期的入口点。
Tick(float DeltaTime)	ao_update(dt) / ao_late_update(dt)	对于引擎使用的 UI/输入模式（例如技能按钮），使用延迟更新（late update）。
Blueprint 图表	CSL 代码	基于文本，作为项目的一部分进行编译。
Pawn/Character	Player_Base 子类	你的玩家逻辑通常位于一个 Player 组件/类 上。
输入映射	技能 + 按键绑定	以移动优先：优先使用技能按钮而不是原生输入。
复制（Replicated 变量）	自动状态同步	除非确实需要，否则避免构建你自己的复制/RPC 模式。
RPC（服务器, 客户端, NetMulticast)	通常不需要	使用引擎提供的功能（例如通知）而不是自定义 RPC 式蔓延。
Actor 生成	Scene.create_entity() / instantiate(Prefab_Asset)	预制件是资产，可以被实例化。
UAsset 引用	get_asset(...)	资产位于 ：游戏资源位于你项目的 下并通过路径被引用。

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

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

避免在其他文件中添加导入
import "core:ao"
import "ui"   // 如果你创建了一个 /ui 文件夹并希望其在作用域内

实体与组件（相对于 Actors & Components）

在运行时创建实体

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 中， 能力（Abilities） 是实现玩家操作的默认方式，具有：

• 一致的 移动友好 按钮 UI

• 冷却

• 可选瞄准（移动设备上拖拽瞄准，PC 上鼠标瞄准）

从下绘制技能按钮 Player.ao_late_update 内部的 用于仅本地的 UI/粒子，和:

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);
        }
    }
}

参见： 能力（Abilities） 有关完整的 API 和模式，请参阅文档。

网络："复制" 大多数时候不是你的工作

与 Unreal 复制不同的地方

• 游戏玩法状态会自动同步 从服务器 → 客户端。

• 你通常 不为标准游戏流程编写 RPC 。

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

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

使用这些模式：

• 用于仅本地的 UI/粒子，和 用于 输入 + 游戏 UI （在服务器 + 本地客户端上运行）

• 将装饰性逻辑与玩法逻辑分离。 用于 纯粹的装饰性 UI/效果 （仅在本地客户端上运行）

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

资产、预制件和路径

该 ：游戏资源位于你项目的 文件夹

资产位于 ：游戏资源位于你项目的。在引用资产时， 从路径中省略 ：游戏资源位于你项目的 。

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"); // 引擎资产

预制件（Prefabs）

预制件是资产（以 .prefab结尾的文件夹）并且可以被实例化：

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

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

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

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

，请注意 CSL 不依赖碰撞回调来进行游戏脚本。常见模式是查询附近的组件并检查距离。
Scene.get_all_components_in_range(player_pos, 2.0, ref nearby);
Scene.get_all_components_in_range(entity.local_position, 2.0, ref nearby);
    // ...
}

参见： 导航网格与碰撞.

UI 差异（UMG vs CSL UI）

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

如果你需要自定义 UI，请参考 UI 文档并遵循标准模式（不要发明类似 UMG 的小部件树，除非文档说明）。

匹配流程、背包、可交互对象

如果你在寻找与常见 Unreal 游戏系统的等效项：

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

• Inventory: Inventory

• 匹配/大厅类游戏: 匹配/大厅类游戏

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

• Spine 动画 （如果你使用过 Paper2D / 翻转书）： Spine

从 Unreal 到 CSL 的“坑”

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

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

• 导入是集中化的：从 main.csl中一次性导入文件夹，而不是每个文件都导入。

• 优先使用技能来实现动作：它一致地解决了移动端 UX + 冷却 + 瞄准 问题。

• 装饰性与游戏性：将仅装饰性的效果保持在本地；将游戏性状态保持为服务器权威。

下一步

• 阅读 能力（Abilities）

• 阅读 导航网格与碰撞

• 浏览 可交互对象 和 Inventory