游戏引擎 / 系统课时

用 asmdef 划分运行时代码

用 asmdef 划分运行时代码

先为第三人称动作关卡建立资源目录,再用 .asmdef 将角色与战斗逻辑、Unity 编辑器工具和自动化测试分开编译。完成后,编辑器和测试能够引用运行时代码,运行时却不依赖它们,错误依赖会在编译或构建阶段暴露。

学习目标

  • 为 Scripts、Art、Prefabs、Scenes 和 Settings 分配明确职责。
  • 在 Unity 6 中创建运行时、编辑器和测试程序集,并配置单向引用。
  • 用一条 Edit Mode 测试和 Player 构建检查程序集边界。

将资源放进有边界的目录

在 Project 窗口的 Assets 下创建以下目录。只有 Scripts 下需要按程序集拆分;美术、预制体和场景资源不必各自建立 .asmdef。

目录 放入的内容
Assets/Scripts/Runtime 玩家控制、战斗结算、相机逻辑及 Game.Runtime.asmdef
Assets/Scripts/Editor 自定义检查工具及 Game.Editor.asmdef
Assets/Scripts/Tests/EditMode NUnit 测试及 Game.Tests.EditMode.asmdef
Assets/Art 模型、材质、纹理、动画
Assets/Prefabs Player.prefab、敌人和关卡交互物预制体
Assets/Scenes Level_01.unity 等场景
Assets/Settings URP Asset、Renderer 等项目资源

.asmdef 会收纳所在文件夹及没有其他程序集定义的子文件夹中的 C# 脚本。因此不要只在 Assets/Scripts 根目录放一个运行时 .asmdef:其下 Editor 脚本也可能被收进运行时程序集,导致 Player 构建失败。三个代码目录分别放定义文件。

确定单向依赖

这里采用三个程序集:Game.Runtime 不引用本项目的编辑器或测试程序集;Game.Editor 只引用 Game.Runtime;Game.Tests.EditMode 也只引用 Game.Runtime(另保留 Test Framework 自动设置的测试依赖)。

运行时、编辑器与测试程序集的单向引用关系

引用箭头表示“谁需要使用谁的类型”,不是运行顺序。不要让 Game.Runtime 引用 Game.Editor,也不要让两个程序集互相引用。如果两边都需要某个接口,应把接口移到双方都能引用的独立底层程序集,而不是增加反向引用。

创建并配置两个正式程序集

以下操作适用于 Unity 6(6000.x)编辑器。

  1. 选中 Assets/Scripts/Runtime,执行 Assets > Create > Scripting > Assembly Definition,命名为 Game.Runtime。
  2. 在 Assets/Scripts/Editor 同样创建 Game.Editor;选中它,在 Inspector 的 Platforms 中取消 Any Platform,只选择 Editor,然后点击 Apply。
  3. 在 Game.Editor 的 Assembly Definition References 中点击 +,选择 Game.Runtime,点击 Apply。运行时程序集保持 Any Platform,不添加对编辑器的引用。

也可以直接编辑生成的文件。Assets/Scripts/Runtime/Game.Runtime.asmdef 内容如下:

json
{
  "name": "Game.Runtime",
  "rootNamespace": "Game",
  "references": [],
  "includePlatforms": [],
  "excludePlatforms": []
}

Assets/Scripts/Editor/Game.Editor.asmdef 内容如下:

json
{
  "name": "Game.Editor",
  "rootNamespace": "Game.EditorTools",
  "references": ["Game.Runtime"],
  "includePlatforms": ["Editor"],
  "excludePlatforms": []
}

这两段是完整配置文件,不是终端命令。保存后 Unity 会导入并重新编译;预期行为是 Game.Runtime 可用于 Player,而 Game.Editor 仅参与编辑器编译。references 中使用的是程序集 name,不是 C# 命名空间。初次迁移先保留 Auto Referenced 默认值,避免尚在 Assembly-CSharp 中的旧脚本失去访问权。

建立测试程序集并运行一次测试

先在 Window > Package Manager 确认安装了 Test Framework。在 Project 中建立并选中 Assets/Scripts/Tests,执行 Assets > Create > Testing > Test Assembly Folder;将新建的测试文件夹重命名为 EditMode,同时将其中 .asmdef 的资源文件名和 Inspector 的 Name 都改为 Game.Tests.EditMode,保持平台仅 Editor。在其 Assembly Definition References 中补上 Game.Runtime,不要删除生成器添加的 NUnit 和 Test Runner 引用。

在 Assets/Scripts/Runtime/DamageRules.cs 写入:

csharp
namespace Game
{
    public static class DamageRules
    {
        // 高防御也保留至少 1 点伤害,便于验证纯逻辑。
        public static int Compute(int attack, int defense)
        {
            return System.Math.Max(1, attack - defense);
        }
    }
}

预期结果:Unity 编译时无错误,DamageRules.Compute(12, 5) 可返回 7。此文件是供 Unity 项目其他脚本和测试调用的类,不是带独立入口的控制台程序。

在 Assets/Scripts/Tests/EditMode/DamageRulesTests.cs 写入:

csharp
using Game;
using NUnit.Framework;

public class DamageRulesTests
{
    [Test]
    public void DamageNeverDropsBelowOne()
    {
        // 同时覆盖普通伤害和最低伤害两种情况。
        Assert.That(DamageRules.Compute(12, 5), Is.EqualTo(7));
        Assert.That(DamageRules.Compute(3, 8), Is.EqualTo(1));
    }
}

打开 Window > General > Test Runner,选择 EditMode 并运行测试。预期结果:DamageNeverDropsBelowOne 显示通过,断言值分别为 7 和 1;如果测试未出现,优先检查 Test Framework 是否安装、测试程序集的平台以及对 Game.Runtime 的引用。

用编译与构建检查隔离是否生效

  1. 在 Project 中选中 DamageRules.cs,查看 Inspector 的 Assembly Information,应属于 Game.Runtime;测试脚本应属于 Game.Tests.EditMode。
  2. 执行 File > Build Profiles,选择已安装构建模块支持的桌面目标并构建 Player。预期结果:编译成功,Editor 和 Edit Mode 测试程序集不进入常规 Player 构建。
  3. 若提示找不到 Game 中的类型,先检查发起调用的程序集是否在 Assembly Definition References 中引用了 Game.Runtime;using Game; 不能替代程序集引用。
  4. 若 Player 构建报告 UnityEditor 相关错误,检查编辑器脚本是否误放在运行时程序集管辖的目录,以及 Game.Editor 是否设置为仅 Editor。
  5. 若出现循环依赖,不要通过更多引用修补;将两边共用的数据定义或接口下沉到独立程序集,再让上层单向引用它。

如果有其他位置的脚本必须加入现有程序集,可以在那个文件夹创建 .asmref 并指向目标 .asmdef。.asmref 改变脚本归属,不等于在两个程序集之间新增依赖。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

用 asmdef 划分运行时代码

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通