游戏客户端架构 / 系统课时
把镜头参数整理成配置数据
把镜头参数整理成配置数据
距离、阻尼和震动幅度散落在脚本里时,调参容易改错单位,也难以回退。本课把参数按职责组织成带版本的数据,在加载时验证数值与跨字段约束,并采用校验成功后整体替换的方式,让调试配置保持可追踪。
学习目标
- 按模式、投影、安全约束和效果组织摄像机配置。
- 校验单位、范围、未知字段与跨字段关系。
- 在运行中替换配置而不重置当前镜头状态。
配置保存设计意图不保存运行记忆
期望距离、肩位、俯仰范围、半衰期和效果上限属于配置。当前实际距离、正在播放的爆炸实例、上一帧阻尼速度和目标身份属于运行状态。两者分开,重新加载参数时才不会把当前镜头突然变成配置中的默认世界位置。
配置字段应写出单位,例如 distanceM、verticalFovDeg、halfLifeS,避免迁移到厘米或弧度接口时误用。阻尼时间也要明确是半衰期、时间常数还是引擎的 smoothTime,这些数字即使都以秒计,也不是等价参数。
| 配置分组 | 保存什么 | 验证重点 |
|---|---|---|
| 模式方案 | 期望距离、肩位、FOV、角度范围 | 每个模式是否完整、字段单位 |
| 公共安全 | 探测半径、安全余量、投影裁剪范围 | 正半径、近小于远、余量非负 |
| 效果规则 | 幅度上限、持续时间、玩家强度比例 | 生命周期合法、叠加后仍有上限 |
配置继承可以减少重复,但会增加“最终值来自哪里”的排查成本。教学例程采用完整模式对象,加载后便能看到全部有效值。需要覆盖层时,先形成有效配置,再校验和显示来源,不要让求解器每帧临时合并多层对象。
本例按十六比九视口、Near 为零点三米、最大垂直 FOV 为六十五度计算,覆盖近面角点的保守半径约零点四九二米,因此探测半径取零点五五米。这个值只匹配当前投影,宽高比或 FOV 改变时仍须重算。
校验不能只依赖类型名称
标准 JSON 不允许 NaN 与 Infinity,但运行中的对象、配置迁移或编辑器输入仍可能产生非有限数值。即使值是数字,也要检查有限性和范围。距离允许范围、Pitch 上下界、Near/Far 等跨字段关系同样需要校验。
未知字段应明确拒绝或按版本迁移。拼错 halfLifeS 若被静默忽略,作者可能以为阻尼已经改变,实际仍用默认值。版本号用于识别结构,而不是每次调数值都升级;参数实验可以另外记录配置修订号和变更说明。
演示规定公共最小期望距离不大于各模式距离,但它只是构图偏好,绝不能把碰撞允许距离抬高到这个最小值。安全空间不足时,运行层应报告应急构图;配置校验也不能预先证明任意关卡都有足够空间。
原子替换完整的有效配置
保存为 camera-config.cjs,执行 node camera-config.cjs。例程校验 JSON 数据副本并深度冻结,模拟加载失败时保留上一份有效配置,所有字段都是本课程自定义配置,不是任何引擎内置参数接口。
'use strict';
const assert = require('node:assert/strict');
function keys(value, expected) {
assert(value && typeof value === 'object' && !Array.isArray(value), 'object required');
assert.deepEqual(Object.keys(value).sort(), [...expected].sort(), 'unknown or missing field');
}
function between(v, low, high) { assert(Number.isFinite(v) && v >= low && v <= high, 'range error'); }
function validate(c) {
keys(c, ['schemaVersion', 'minDesiredDistanceM', 'probeRadiusM', 'marginM', 'nearM', 'farM', 'modes']);
assert.equal(c.schemaVersion, 1, 'unsupported schema');
between(c.minDesiredDistanceM, 0, 100); between(c.probeRadiusM, 0.001, 10);
between(c.marginM, 0, 10); between(c.nearM, 0.001, 10); between(c.farM, 0.002, 100000);
assert(c.nearM < c.farM, 'clip order');
keys(c.modes, ['explore', 'aim']);
for (const mode of Object.values(c.modes)) {
keys(mode, ['distanceM', 'shoulderM', 'verticalFovDeg', 'pitchMinDeg', 'pitchMaxDeg', 'halfLifeS']);
between(mode.distanceM, c.minDesiredDistanceM, 100); between(mode.shoulderM, -5, 5);
between(mode.verticalFovDeg, 1, 179); between(mode.halfLifeS, 0.001, 10);
between(mode.pitchMinDeg, -89, 89); between(mode.pitchMaxDeg, -89, 89);
assert(mode.pitchMinDeg < mode.pitchMaxDeg, 'pitch order');
}
}
function freeze(value) {
for (const child of Object.values(value)) if (child && typeof child === 'object') freeze(child);
return Object.freeze(value);
}
function load(json) {
const candidate = JSON.parse(json); validate(candidate);
return freeze(candidate); // 验证完成之前不发布半成品。
}
const initial = { schemaVersion: 1, minDesiredDistanceM: 1, probeRadiusM: 0.55,
marginM: 0.05, nearM: 0.3, farM: 1000, modes: {
explore: { distanceM: 4, shoulderM: 0.3, verticalFovDeg: 65, pitchMinDeg: -35, pitchMaxDeg: 70, halfLifeS: 0.2 },
aim: { distanceM: 2.2, shoulderM: 0.6, verticalFovDeg: 45, pitchMinDeg: -20, pitchMaxDeg: 45, halfLifeS: 0.15 }
} };
let active = load(JSON.stringify(initial));
const viewportAspect = 16 / 9;
const requiredRadius = Math.max(...Object.values(active.modes).map(mode => {
const h = active.nearM * Math.tan(mode.verticalFovDeg * Math.PI / 360);
return Math.hypot(active.nearM, h, h * viewportAspect);
}));
assert(active.probeRadiusM >= requiredRadius); // 范围合法之外,还检查当前投影覆盖。
const previous = active, bad = structuredClone(initial);
bad.modes.aim.halfLifeS = 0;
try { active = load(JSON.stringify(bad)); } catch (e) { assert.match(e.message, /range error/); }
assert.equal(active, previous);
const unknown = structuredClone(initial); unknown.modes.aim.halfLife = 0.2;
assert.throws(() => load(JSON.stringify(unknown)), /unknown or missing field/);
const clips = structuredClone(initial); clips.nearM = clips.farM;
assert.throws(() => validate(clips), /clip order|range error/);
const nonfinite = structuredClone(initial); nonfinite.probeRadiusM = NaN;
assert.throws(() => validate(nonfinite), /range error/);
assert.throws(() => { active.modes.aim.distanceM = 9; }, TypeError);
const revised = structuredClone(initial); revised.modes.aim.distanceM = 2.4;
active = load(JSON.stringify(revised));
assert.equal(active.modes.aim.distanceM, 2.4);
console.log(`schema=${active.schemaVersion} aim distance=${active.modes.aim.distanceM.toFixed(1)}m`);
console.log('failed reload retained previous=true; deep frozen=true');
console.log('unknown field, range, clip order, nonfinite: passed');预期输出:
schema=1 aim distance=2.4m
failed reload retained previous=true; deep frozen=true
unknown field, range, clip order, nonfinite: passed调参只改变目标不强制重置镜头
新配置通过后,在同一个更新边界整体替换,并记录修订号。当前距离、旋转和效果时间继续保留,由新目标驱动平滑。若缩小了角度合法范围,应安排回到新范围的策略;直接裁剪可能产生跳变,不能把它当作普通热更新副作用忽略。
Near、FOV 与宽高比变化时,重新计算检测代理是否覆盖近裁剪面。探测半径也不能只根据配置范围合法就视为足够大。场景单位变化、角色体型变化或投影变化,都需要重新执行墙角与狭道测试。
练习故意拼错半衰期字段、颠倒裁剪范围,再加载一份合法的瞄准距离修改。非法配置应拒绝且保留原配置,合法修改应连续影响目标而不清空运行状态。配合有效配置导出和同条件回归记录,调参才具有可复现的依据。