这篇写给做游戏单位/载具逻辑、想摆脱「每加一款车复制一套代码」的开发者;下面这张表按角色列出你能带走什么、从哪节开始读。
| 读者 | 带走什么 | 拿它做什么 | 从哪节开始读 |
|---|---|---|---|
| 做载具逻辑的人 | 层级/动作/动画三块字段划分 | 新增车型时只填配置、不改判断 | 2 → 4 |
| 想上数据驱动的人 | 按结构推导层级的判定式 | 替换按模型名特判的分支 | 3 |
| 要加新车型的人 | 字段规格对照表 | 先按字段设计做一版 | 4 → 5 |
只做纯渲染、不碰单位逻辑的读者不必读。
这篇讲三款军车(坦克、导弹车、火焰车)怎么收进同一套单位模组:先说清模组由哪三块组成,再逐块讲模型层级、动作/技能、动画怎么进配置,最后说这套做法带来的好处。先看概览:
| 小节 | 讲什么 | 读它能得到什么 |
|---|---|---|
| 1 | 为什么每款车不该写一套 | 判断自己该不该模组化 |
| 2 | 单位模组的三块字段 | 一张字段总表 |
| 3 | 模型层级:按结构推导 | 一个不写死名字的判定式 |
| 4 | 动作 / 技能:功能与取值 | 字段设计方式 |
| 5 | 动画:对准与攻击表现 | 层级字段的直接用法 |
| 6 | 结论与下一步 | 今天就能动手的一步 |
单位模组 = mods/unit-* 下「数据 + 行为」的单位定义;数据驱动 = 差异写在配置里,代码只解释配置。
三款车共同点是「载具 + 炮塔/发射架 + 炮管」,差异在弹药与发射。最直接做法是每款车一套函数,差异写进各自函数,代价是每加一款复制三块逻辑(开火/朝向/层级)。下面是直接做法:
// 每款车一套函数:重复的是数量
function fireTank(state, cfg) { ... }
function aimTank(state, cfg) { ... }
function fireMissileCar(state, cfg) { ... }
function aimMissileCar(state, cfg) { ... }
function fireFlameCar(state, cfg) { ... }
function aimFlameCar(state, cfg) { ... }
// 加第四款车:再抄两组函数
模组化做法相反:分类、动作、模型层级都变成配置字段,代码只解释数据的纯函数(getModelLevel(nodes)、canFire(state, target)、pickAnimation(action);第 2 节字段、第 3 节层级、第 4 节动画)。差在哪(下表):
| 维度 | 每款车一套函数 | 模组化数据驱动 |
|---|---|---|
| 新增一款车要改什么 | 新写 2~3 个函数 | 只加一条配置 |
| 逻辑重复 | 三份,改一处同步三处 | 一份共用 |
| 出错点 | 复制时漏改(射程/轴) | 配置错一眼可见 |
| 模型层级判定 | 每款写死层数 | 按结构推导,换模型不改码 |
| 代价 | 上手快,1~2 款够用 | 先设计字段,首款投入大 |
所以把三块挪进配置,先从字段说起。
本地复现需要 Node 18 与项目依赖(仓库根目录执行 npm install);层级判定与字段读取都是纯函数,可以直接在 Node 里跑。
进入字段划分:三块各管一件事,下面这张表是职责划分:
| 块 | 管什么 | 谁读它 |
|---|---|---|
| 模型 | 几级、子部件叫什么 | 层级判定、刚体挂载 |
| 动作 / 技能 | 什么动作、射程与弹药参数 | 开火与粒子表现 |
| 动画 | 对准方式、攻击表现、死亡 | 表现层(不碰逻辑) |
三块字段分开看都简单,但单看任何一块都拼不出「一台车从读配置到开火」的完整过程。下面是整条链路的骨架,共 16 行:前 5 行在加载时跑一次,后面每帧重复跑。
1 │ readConfig(path) # 读模组配置:分类 / 模型 / 动作 / 动画
2 │ validate(cfg) # 校验:kind 合法、aim 与模型层级匹配、取值在范围内
3 │ parts = loadModel(cfg.model) # 读 glb,取出 body / turret / barrels 这些部件
4 │ level = getModelLevel(parts) # 从结构推导层级(有无 Turret / WeaponPart)
5 │ assert level === cfg.model.level # 配置写的层级与模型实际结构对不上就报错
6 │
7 │ onEachFrame(cfg, parts, state):
8 │ target = pickTarget(state) # 选目标(最接近/最危险,按你的策略)
9 │ aimStrategy = resolveAim(cfg) # animation.aim → 对准策略函数
10 │ aimStrategy(parts, target) # 渐进对准或直接对准;层级不够时这一步只能原地朝前
11 │ if not inRange(cfg, state, target): # 射程判定(距离 × 目标系数)
12 │ moveToward(target); return
13 │ if not canStop(state, target): # 停靠判定(与目标的高度差 ≤ 1 才停得下)
14 │ moveToward(target); return
15 │ runAction(cfg, state, target) # action.kind → 具体实现,其余字段作为参数透传
16 │ playAttack(parts, cfg.animation.attack) # 炮管抽动 / 车身震动
这份骨架分三段看:第 15 行是加载期,整局只跑一次 —— 读配置、校验、取部件、推导层级、交叉核对;第 716 行是每帧,反复跑 —— 选目标、对准、判射程、判停靠、触发动作、播表现。配置只在加载期读,每帧只读解析好的结果,这是数据驱动能便宜的根本原因。
最容易写错的是第 13 行和第 5 行。第 13 行是停靠判定:很多实现只写射程不写停靠,于是单位在射程内却一直往前走、永远不开火。第 5 行是层级校验:少了它,配置把三级模型写成二级也能跑,要到玩家看见炮塔不转才发现。
读法:先看第 15 行知道输入是什么,再看第 716 行知道每帧按什么顺序判,最后回到 §3~§5 看每一步的具体实现。
层级的定义必须前后一致,否则「一级」在不同章节里会指不同东西。下面这张表是最终定义:
| 层级 | 构成 | 车辆例子 |
|---|---|---|
| 三级 | 车体 + 炮塔 + 炮管 | 坦克 |
| 二级 | 车体 + 发射架 | 导弹车 |
| 一级 | 只有车体(发射点是车体上的挂点,不是独立部件) | 火焰车 |
以火焰车为例:它的喷口是挂在车体内部的一个坐标(发射点),不参与层级计数——一级就是一级,只有一个可驱动部件。层级不能靠模型名判断,否则每加一个模型就要改一次判定。下面这段是层级判定(代码第 3 行是层级):
const hasTurret = nodes.some((n) => n.name === 'Turret')
const hasWeapon = nodes.some((n) => n.name === 'WeaponPart')
const level = 1 + (hasTurret ? 1 : 0) + (hasWeapon ? 1 : 0)
模型层级要在两处各实现一遍。
children[0](第一个子节点)钻。两处实现同一件判断:从结构推导「几级、哪些是炮塔、哪些是炮管」。编辑器把结果写进模组数据(分类 + 层级);运行时加载后再推导一次,校验手填的配置。
配置是人手填的,可能填错;重推等于交叉验证。算法不一致时测试会红,而不是「看起来能跑」。炮管数同理:编辑器数「Turret 下带几何体的子节点」,运行时 _hasSeparateBarrel = 部件队列数 ≥ 3;不一致就当 bug。
原来怎么写:每款车的开火逻辑写在自己的函数里,弹药数、发射节奏、弹道都硬编在函数体里。下面这段是改造前的形态:
function fireTank(state, target) {
const ammo = 2
for (let i = 0; i < ammo; i++) {
spawnShell(state, target, { pattern: 'continuous', spread: 'center', trajectory: 'straight' })
}
}
function fireMissileCar(state, target) { /* 弹道硬编成高抛,一次一发 */ }
function fireFlameCar(state, target) { /* 一次多发、蛇形飞 */ }
// 新增第四款车:再写一个函数,把这些参数再抄一遍
新增一款车 = 再写一个函数并复制这些参数;改一次弹药数,要把所有用到它的函数翻一遍。
现在怎么写:动作类型与参数都进配置。下面这段是配置示例:
const tankUnit = {
model: { level: 3 },
action: {
kind: 'TankFire',
ranged: true,
ammoPerShot: 2,
pattern: 'continuous',
spread: 'center',
target: 'point',
trajectory: 'straight'
}
}
配置写完了,先要让它「进到代码里」。加载期把这份对象登记进单位表,整局只做一次:
// 加载期:把这份配置登记到单位表里,整局只做一次
const UNITS = {}
const registerUnit = (name, cfg) => { UNITS[name] = cfg }
registerUnit('tank', tankUnit)
之后每帧需要它时,按名字取回同一份配置,再作为参数交给动作分派:
// 每帧:按单位名取回同一份配置,交给动作分派
const cfg = UNITS['tank'] // ← 就是上面那个 tankUnit
runAction(cfg, state, target) // ← 下面函数里的 cfg.action.* 读的就是它的 action 字段
runAction 只做两件事:按 kind 查表选实现(TankFire / MissileFire / FlameFire),其余字段原样透传。每一处读配置的地方都在行末标了来源:
const ACTIONS = { TankFire: fireShell, MissileFire: fireMissile, FlameFire: fireFlame }
function runAction(cfg, state, target) {
const impl = ACTIONS[cfg.action.kind] // ← tankUnit.action.kind
if (!impl) throw new Error(`unknown action: ${cfg.action.kind}`)
const ammo = cfg.action.ammoPerShot // ← tankUnit.action.ammoPerShot
* (cfg.model.level === 3 ? barrelCount(cfg) : 1) // ← tankUnit.model.level
return impl(state, target, {
pattern: cfg.action.pattern, // ← tankUnit.action.pattern
spread: cfg.action.spread, // ← tankUnit.action.spread
trajectory: cfg.action.trajectory // ← tankUnit.action.trajectory
})
}
数据流是一条直线:配置在加载期登记一次 → 每帧按名字取回 → 作为参数交给 runAction → 函数体按 kind 查表、其余字段原样透传。所以新增一款车 = 多一条 registerUnit,不改 runAction。
三个动作实现只关心「拿到几发、怎么散、怎么飞」,不再关心「这是哪款车」——所以新增车型不碰这三个函数。
改造前后差在哪(下表):
| 改动点 | 改造前 | 改造后 |
|---|---|---|
| 新增一款车 | 新写一个开火函数,复制参数 | 只加一条配置 |
| 改一次弹药数 | 找到该车的函数体改 | 改配置里的一个字段 |
| 参数有没有漏改 | 靠人看 | 字段缺失能被校验 |
字段清单(下表):
| 字段 | 取值 | 含义 |
|---|---|---|
| ammoPerShot | 1~10;三级模型要 × 炮管数 | 单次发射的弹药总数 |
| pattern | 连续 / 齐射 | 发射节奏,选「连续」这类才需要填对应参数 |
| spread | 集中(一点发射)/ 分散(圆形分散点) | 子弹生成点的分布 |
| target | 精确(射向一点)/ 范围(射向圆形范围) | 瞄准点与判定范围 |
| trajectory | 直线 / 高抛 / 蛇形 | 飞行路径 |
原来怎么写:哪款车怎么对准、怎么抖、怎么死,写死在各自的动画代码里;想换表现要改代码。下面这段是改造前的形态:
function aimTank(state, target) {
turnTurret(state, target) // 硬编:走炮塔这根轴
pitchBarrel(state, target) // 硬编:再走炮管这根轴
}
function aimMissileCar(state, target) { /* 硬编:只转车体 */ }
function aimFlameCar(state, target) { /* 硬编:直接朝向目标 */ }
换一款车就要改动画分支,加一种表现组合还要再开一个分支。
现在怎么写:动画也进配置,代码按 aim 的类型选择对准策略,按 attack 数组依次播放。下面这段是配置示例:
// 还是 §4 那份 tankUnit,这里只看它的 animation 块
const tankUnit = {
action: { /* §4 的字段,略 */ },
animation: { aim: 'turretAndBarrel', attack: ['barrelPump', 'bodyShake'], death: 'explode' }
}
接线方式和 §4 一样:加载期登记同一份配置,每帧按名字取回,再交给对准分派:
// 加载期:登记的仍是那份 tankUnit
registerUnit('tank', tankUnit)
// 每帧:取回同一份配置,解析出对准策略并执行
const cfg = UNITS['tank'] // ← 就是上面那个 tankUnit
const strategy = resolveAim(cfg) // ← 读的就是它的 animation.aim
strategy(parts, target)
resolveAim 是一张策略表加一次查表,函数体读的字段同样标了来源:
const AIM = { direct: aimDirect, bodyYaw: aimBodyYaw, turretYaw: aimTurretYaw, barrelPitch: aimBarrelPitch, turretAndBarrel: aimBoth }
function resolveAim(cfg) {
const impl = AIM[cfg.animation.aim] // ← tankUnit.animation.aim
if (!impl) throw new Error(`unknown aim: ${cfg.animation.aim}`)
return impl
}
数据流与 §4 同构:配置登记一次 → 每帧取回 → 解析出策略 → 拿部件和目标执行。每个策略函数只负责转自己那根轴,不判断车型;attack 数组则按顺序交给表现层播放。所以换对准方式 = 改一个字符串,加一种表现组合 = 数组里加一项。
为什么这么设计:aim 声明的是「我想要哪种对准方式」,而每种方式对模型层级有硬要求——渐进对准炮塔必须有炮塔(至少二级),要动炮管就必须三级。所以层级不是另外填的,是从动画需求反推出来的:填了 turretAndBarrel 却给一级模型,配置就不成立。对准方式与层级的对应关系(下表):
| 对准方式 | 需要几级 | 为什么 |
|---|---|---|
| 直接对准 | 一级及以上 | 不依赖可独立旋转的部件 |
| 车身水平渐进 | 一级 | 只转车体 |
| 炮塔水平渐进 | 二级 | 需要炮塔绕自身原点转 |
| 炮管垂直渐进 | 三级 | 需要炮管独立俯仰 |
| 炮塔 + 炮管都渐进 | 三级 | 两个部件各转各的 |
改造前后差在哪(下表):
| 改动点 | 改造前 | 改造后 |
|---|---|---|
| 换对准方式 | 改动画代码分支 | 改一个字段 |
| 新增攻击表现组合 | 改代码新增分支 | 数组里加一项 |
| 配置与模型不匹配 | 运行时才发现转不动 | 填配置时就能判断层级不够 |
下面按「是什么 → 为什么是坑 → 怎么解决 → 为什么能解决」排:
| 坑是什么 | 为什么是坑 | 如何解决 | 为什么能解决 |
|---|---|---|---|
| 按模型名特判层级 | 新增模型要改判断,两边实现容易不一致 | 用结构推导(有无 Turret/WeaponPart) | 结构就在数据里,不依赖命名习惯 |
| 把喷口算成一级部件 | 「一级」在代码与文档里指两套东西 | 发射点定义为车体挂点,不参与层级 | 层级只数可独立驱动的部件 |
| 发射方式填了多个值 | 连续与齐射互相冲突,行为不可预期 | 用单选字段约束只允许一个值 | 字段约束唯一,解释器不用猜 |
| 动画/发射表现挂在模型名上 | 换模型丢表现,新增车型要改代码 | 由动作类型决定 | 动作是行为约定,模型只是外壳 |
你下一步能做什么:挑一款你要新增的单位,先把「分类 / 动作 / 层级」写成配置字段,跑一遍层级判定式;再把动作表里的「功能 / 取值 / 说明」三栏照抄一遍,检查每个选项都有明确的取值约束。
这套设计把「差异」压成了字段,但字段本身没有约束层,配置与资产也各自演化,表现组合仍是固定枚举。下面三条是它现在做不到、下一步可以补的:
pattern: 'continuous' 配 spread 某些组合根本没有意义。下一步可以为每个 kind 声明「必填参数 + 取值范围」,编辑器侧填完就校验,跑起来之前就拦住。level 可能还写着 2,结果对准策略按二级去转,转不动。下一步可以由资产管线在导出时写出版本号,加载时对不上就报警,而不是等玩家看见炮管不动。attack 只能从固定几种里选,想调「炮管抽动幅度大一点、车身震动曲线缓一点」还得改代码。下一步可以把这些幅度与曲线抽成可调参数,让表现也能调参,而不是二选一。这些内容来自一个真实项目里对三款同类对象的连续改造:先把各自的特判收成一套配置,再按模型层级、动作与动画三块逐项补齐,中间经过多轮评审与返工。文中的配置项划分与层级个数都是从实际资产里归纳出来的。