游戏引擎 / 系统课时
用 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)编辑器。
- 选中
Assets/Scripts/Runtime,执行Assets > Create > Scripting > Assembly Definition,命名为Game.Runtime。 - 在
Assets/Scripts/Editor同样创建Game.Editor;选中它,在 Inspector 的Platforms中取消Any Platform,只选择Editor,然后点击Apply。 - 在
Game.Editor的Assembly Definition References中点击+,选择Game.Runtime,点击Apply。运行时程序集保持Any Platform,不添加对编辑器的引用。
也可以直接编辑生成的文件。Assets/Scripts/Runtime/Game.Runtime.asmdef 内容如下:
{
"name": "Game.Runtime",
"rootNamespace": "Game",
"references": [],
"includePlatforms": [],
"excludePlatforms": []
}Assets/Scripts/Editor/Game.Editor.asmdef 内容如下:
{
"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 写入:
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 写入:
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 的引用。
用编译与构建检查隔离是否生效
- 在 Project 中选中
DamageRules.cs,查看 Inspector 的Assembly Information,应属于Game.Runtime;测试脚本应属于Game.Tests.EditMode。 - 执行
File > Build Profiles,选择已安装构建模块支持的桌面目标并构建 Player。预期结果:编译成功,Editor 和 Edit Mode 测试程序集不进入常规 Player 构建。 - 若提示找不到
Game中的类型,先检查发起调用的程序集是否在Assembly Definition References中引用了Game.Runtime;using Game;不能替代程序集引用。 - 若 Player 构建报告
UnityEditor相关错误,检查编辑器脚本是否误放在运行时程序集管辖的目录,以及Game.Editor是否设置为仅Editor。 - 若出现循环依赖,不要通过更多引用修补;将两边共用的数据定义或接口下沉到独立程序集,再让上层单向引用它。
如果有其他位置的脚本必须加入现有程序集,可以在那个文件夹创建 .asmref 并指向目标 .asmdef。.asmref 改变脚本归属,不等于在两个程序集之间新增依赖。