《游戏引擎实现原理》7.2 关卡与内容管线

// snippet: 编辑器导出的关卡文档（SAMPLE_LEVEL）
{
  "version": 1,
  "island": { "seed": 20261010, "size": 20, "glimmerCount": 9, "treeCount": 12 },
  "spawn": { "x": 0, "z": 0 },
  "props": [
    { "kind": "chest", "x": -7, "z": 6 },
    { "kind": "sign", "x": 5, "z": -6 }
  ]
}

// file: src/game/level-pipeline.ts
// tier: L1
// verify: node src/game/level-pipeline.ts
//
// 《微光岛》关卡与内容管线。编辑器导出的关卡是一份带版本号的 JSON：小岛生成参数
// （种子 / 尺寸 / 密度）+ 出生点 + 手工摆件。运行时的加载器只做三件事：解析并校验、
// 用种子程序化生成小岛、把结果翻译成渲染器能消费的实例列表。全部确定性、无随机。

import { assembleFrame, type SceneInstance } from '../render/app/renderer-assembly.ts';
import { hashUnit } from '../render/ui2d/sprite-batch.ts';

export interface PropDef { readonly kind: string; readonly x: number; readonly z: number }

export interface LevelDoc {
  readonly version: number;
  readonly island: { readonly seed: number; readonly size: number; readonly glimmerCount: number; readonly treeCount: number };
  readonly spawn: { readonly x: number; readonly z: number };
  readonly props: readonly PropDef[];
}

export interface Vec2 { readonly x: number; readonly z: number }

export interface Level {
  readonly spawn: Vec2;
  readonly glimmers: readonly Vec2[];
  readonly trees: readonly Vec2[];
  readonly props: readonly PropDef[];
}

export const LEVEL_VERSION = 1;

/** 解析并校验编辑器导出的关卡。越界或未知版本一律抛错，绝不静默降级。 */
export function parseLevel(text: string): LevelDoc {
  let raw: unknown;
  try { raw = JSON.parse(text); } catch { throw new Error('关卡不是合法 JSON'); }
  const doc = raw as Partial<LevelDoc>;
  if (doc.version !== LEVEL_VERSION) {
    throw new Error(`不支持的关卡版本：${String(doc.version)}（期望 ${LEVEL_VERSION}）`);
  }
  const isl = doc.island;
  if (isl === undefined || !(isl.size > 0)) throw new Error('island.size 必须为正');
  if (!Number.isInteger(isl.seed)) throw new Error('island.seed 必须是整数');
  if (isl.glimmerCount < 0 || isl.treeCount < 0) throw new Error('生成数量不能为负');
  const half = isl.size / 2;
  if (doc.spawn === undefined || Math.abs(doc.spawn.x) > half || Math.abs(doc.spawn.z) > half) {
    throw new Error('spawn 必须落在小岛范围内');
  }
  for (const p of doc.props ?? []) {
    if (typeof p.kind !== 'string' || p.kind.length === 0) throw new Error('prop.kind 不能为空');
    if (Math.abs(p.x) > half || Math.abs(p.z) > half) throw new Error(`prop ${p.kind} 越界`);
  }
  return doc as LevelDoc;
}

/** 程序化生成：用种子把点铺在抖动网格上，同种子必然得到同一组坐标。 */
export function scatter(seed: number, size: number, count: number, salt: number): Vec2[] {
  if (count === 0) return [];
  const half = size / 2;
  const cols = Math.ceil(Math.sqrt(count));
  const cell = size / cols;
  const out: Vec2[] = [];
  for (let i = 0; i < count; i++) {
    const cx = i % cols;
    const cz = Math.floor(i / cols);
    // 抖动限制在格子的 60% 内，保证不跨格、不重叠
    const jx = (hashUnit(i, seed ^ salt) - 0.5) * cell * 0.6;
    const jz = (hashUnit(i, seed ^ (salt + 101)) - 0.5) * cell * 0.6;
    const x = Math.max(-half, Math.min(half, -half + cell * (cx + 0.5) + jx));
    const z = Math.max(-half, Math.min(half, -half + cell * (cz + 0.5) + jz));
    out.push({ x, z });
  }
  return out;
}

/** 由关卡文档构建运行时关卡：手工摆件 + 程序化生成的微光与树木。 */
export function buildLevel(doc: LevelDoc): Level {
  const { seed, size, glimmerCount, treeCount } = doc.island;
  return {
    spawn: { x: doc.spawn.x, z: doc.spawn.z },
    glimmers: scatter(seed, size, glimmerCount, 0x9e37),
    trees: scatter(seed, size, treeCount, 0x51ed),
    props: doc.props,
  };
}

/** 把关卡翻译成渲染器实例：微光 / 树 / 摆件各有自己的 meshId。 */
export function toSceneInstances(level: Level): SceneInstance[] {
  const out: SceneInstance[] = [];
  let id = 0;
  const push = (p: Vec2, meshId: number): void => {
    out.push({ id: id++, meshId, materialId: 0, position: [p.x, 0, p.z], scale: 0.8, alpha: false, visible: true });
  };
  for (const g of level.glimmers) push(g, 1);
  for (const t of level.trees) push(t, 2);
  for (const p of level.props) push({ x: p.x, z: p.z }, p.kind === 'chest' ? 3 : 4);
  return out;
}

/** 俯视正交投影：把 [-extent,extent] 映射到裁剪空间，列主序 4x4。 */
export function orthoViewProj(extent: number): number[] {
  return [1 / extent, 0, 0, 0, 0, 0, -1 / 20, 0, 0, 1 / extent, 0, 0, 0, 0, 1, 1];
}

export interface LevelStats { readonly glimmers: number; readonly trees: number; readonly props: number; readonly drawn: number; readonly culled: number }

/** 装配一帧：把关卡实例送进剔除 + 排序，返回统计。 */
export function assembleLevel(level: Level, extent: number): LevelStats {
  const frame = assembleFrame(toSceneInstances(level), orthoViewProj(extent), [0, 20, 0], 100);
  return {
    glimmers: level.glimmers.length, trees: level.trees.length, props: level.props.length,
    drawn: frame.stats.drawn, culled: frame.stats.culled,
  };
}

/** 示例关卡：编辑器导出的样子。 */
export const SAMPLE_LEVEL: LevelDoc = {
  version: LEVEL_VERSION,
  island: { seed: 20261010, size: 20, glimmerCount: 9, treeCount: 12 },
  spawn: { x: 0, z: 0 },
  props: [{ kind: 'chest', x: -7, z: 6 }, { kind: 'sign', x: 5, z: -6 }],
};

if ((import.meta as { main?: boolean }).main) {
  const doc = parseLevel(JSON.stringify(SAMPLE_LEVEL));
  const stats = assembleLevel(buildLevel(doc), 10);
  console.log(`[level] seed=${doc.island.seed} size=${doc.island.size}`);
  console.log(`[level] glimmers=${stats.glimmers} trees=${stats.trees} props=${stats.props}`);
  console.log(`[level] drawn=${stats.drawn} culled=${stats.culled}`);
  const a = buildLevel(doc).glimmers.map((g) => `${g.x.toFixed(3)},${g.z.toFixed(3)}`).join(' ');
  const b = buildLevel(doc).glimmers.map((g) => `${g.x.toFixed(3)},${g.z.toFixed(3)}`).join(' ');
  console.log(`[level] deterministic=${a === b}`);
}

[level] seed=20261010 size=20
[level] glimmers=9 trees=12 props=2
[level] drawn=23 culled=0
[level] deterministic=true

extent 12 -> drawn=23 culled=0
extent 10 -> drawn=23 culled=0
extent  8 -> drawn=22 culled=1
extent  6 -> drawn=12 culled=11