《游戏引擎实现原理》11.3 资产浏览器与关卡编辑

// file: src/editor/assets/asset-tree.ts
// tier: L1
// verify: npx vitest run src/editor/assets/asset-tree.test.ts
//
// helio 编辑器 11.3：资产浏览器背后的数据模型。
// 引擎只知道扁平的「路径 → 资产」；浏览器要把它解释成一棵可展开的树。
// 这里把路径列表建成树、按扩展名判类型、用 FNV-1a 给每个资产算稳定 GUID，
// 再提供拖放载荷的编解码。纯数据，Node 26 直跑。

export type AssetKind = 'folder' | 'texture' | 'model' | 'scene' | 'script' | 'audio';

export interface AssetNode {
  readonly id: string;
  readonly name: string;
  readonly path: string;
  readonly kind: AssetKind;
  readonly children: AssetNode[];
}

/** 扩展名 → 资产类型。未登记的一律当作 script（文本）。 */
const EXT_KIND: Readonly<Record<string, AssetKind>> = {
  png: 'texture', jpg: 'texture', ktx2: 'texture',
  gltf: 'model', glb: 'model',
  level: 'scene',
  ts: 'script',
  wav: 'audio', ogg: 'audio',
};

/** 资产类型判定：取最后一个扩展名，未知扩展名回落为 script。 */
export function kindOf(name: string): AssetKind {
  const dot = name.lastIndexOf('.');
  if (dot < 0) return 'folder';
  return EXT_KIND[name.slice(dot + 1).toLowerCase()] ?? 'script';
}

/** FNV-1a 32 位哈希，输出 8 位十六进制——资产的稳定 GUID（同一路径永远同值）。 */
export function guidOf(path: string): string {
  let h = 0x811c9dc5;
  for (let i = 0; i < path.length; i++) {
    h ^= path.charCodeAt(i);
    h = Math.imul(h, 0x01000193) >>> 0;
  }
  return h.toString(16).padStart(8, '0');
}

/**
 * 把扁平路径列表建成资产树。中间目录自动补成 folder 节点，
 * 同名目录只建一次；插入时按名字排序，保证树是确定的。
 */
export function buildAssetTree(paths: readonly string[], rootName = 'assets'): AssetNode {
  const root: AssetNode = { id: guidOf(rootName), name: rootName, path: rootName, kind: 'folder', children: [] };
  for (const p of paths) {
    const segs = p.split('/').filter((s) => s.length > 0);
    let cur = root;
    let acc = rootName;
    for (let i = 0; i < segs.length; i++) {
      const seg = segs[i]!;
      const isLeaf = i === segs.length - 1;
      acc = `${acc}/${seg}`;
      let child = cur.children.find((c) => c.name === seg);
      if (!child) {
        child = {
          id: guidOf(acc), name: seg, path: acc,
          kind: isLeaf ? kindOf(seg) : 'folder', children: [],
        };
        cur.children.push(child);
      }
      cur = child;
    }
  }
  sortTree(root);
  return root;
}

function sortTree(n: AssetNode): void {
  n.children.sort((a, b) => (a.kind === b.kind ? a.name.localeCompare(b.name) : a.kind === 'folder' ? -1 : 1));
  for (const c of n.children) sortTree(c);
}

/** 深度优先展平成列表（目录在前），供列表控件直接消费。 */
export function flattenTree(root: AssetNode): AssetNode[] {
  const out: AssetNode[] = [];
  const walk = (n: AssetNode): void => { out.push(n); for (const c of n.children) walk(c); };
  walk(root);
  return out;
}

/** 按路径查节点；找不到返回 null。 */
export function findNode(root: AssetNode, path: string): AssetNode | null {
  for (const n of flattenTree(root)) if (n.path === path) return n;
  return null;
}

/** 拖放载荷：带一个私有 MIME 前缀的 JSON，浏览器靠它区分「资产拖拽」与外部拖入。 */
export const ASSET_MIME = 'application/x-helio-asset';

export function encodeDragPayload(ids: readonly string[]): string {
  return `${ASSET_MIME}:${JSON.stringify(ids)}`;
}

/** 解析拖放载荷：前缀不符或 JSON 坏掉都返回空数组（当作外部拖入）。 */
export function decodeDragPayload(text: string): string[] {
  if (!text.startsWith(`${ASSET_MIME}:`)) return [];
  try {
    const v: unknown = JSON.parse(text.slice(ASSET_MIME.length + 1));
    if (!Array.isArray(v)) return [];
    return v.filter((x): x is string => typeof x === 'string');
  } catch {
    return [];
  }
}

// snippet: src/editor/assets/asset-tree.test.ts 节选
expect(kindOf('island.gltf')).toBe('model');
expect(kindOf('notes.txt')).toBe('script'); // 未知扩展名回落 script

// 同一路径永远同值，不同路径不同值
expect(guidOf('assets/art/island.gltf')).toBe(guidOf('assets/art/island.gltf'));
expect(guidOf('a')).not.toBe(guidOf('b'));

// 中间目录自动补成 folder，且只建一次
expect(findNode(root, 'assets/art/rocks')?.children.map((c) => c.name))
  .toEqual(['large.gltf', 'small.gltf']);

// 拖放载荷往返；外部拖入（无私有前缀）返回空数组
expect(decodeDragPayload(encodeDragPayload(['abc12345']))).toEqual(['abc12345']);
expect(decodeDragPayload('随便一段文字')).toEqual([]);

// 关卡加载：引用缺失的网格被收进 missing，其余照常加载
expect(missing).toEqual(['assets/art/missing.gltf']);

// file: src/editor/assets/level-loader.ts
// tier: L1
// verify: npx vitest run src/editor/assets/asset-tree.test.ts
//
// helio 编辑器 11.3：把《微光岛》的关卡数据装进编辑器。
// 关卡文件是一段 JSON：一批实体，每个实体用资产路径引用网格。加载时校验
// 每个引用在资产树里确实存在，缺的收集起来交给界面提示。纯数据，Node 26 直跑。

import type { Vec3 } from '../../core/vec3.ts';
import { findNode, type AssetNode } from './asset-tree.ts';

export interface LevelEntity {
  readonly id: string;
  readonly name: string;
  readonly mesh: string;
  readonly position: Vec3;
}

export interface LevelDocument {
  readonly name: string;
  readonly entities: LevelEntity[];
}

export interface LoadResult {
  readonly document: LevelDocument;
  readonly missing: string[];
}

function asVec3(v: unknown): Vec3 {
  if (!Array.isArray(v) || v.length !== 3 || v.some((n) => typeof n !== 'number')) {
    throw new Error('position 必须是三个数字');
  }
  return [v[0] as number, v[1] as number, v[2] as number];
}

/**
 * 解析关卡 JSON 并对着资产树校验引用。形状不对直接抛（编辑器会弹错误条）；
 * 引用缺失不算致命，收进 missing 让界面标红。
 */
export function parseLevel(raw: unknown, root: AssetNode): LoadResult {
  if (typeof raw !== 'object' || raw === null) throw new Error('关卡根必须是对象');
  const obj = raw as { name?: unknown; entities?: unknown };
  if (typeof obj.name !== 'string') throw new Error('关卡缺少 name');
  if (!Array.isArray(obj.entities)) throw new Error('关卡缺少 entities 数组');
  const entities: LevelEntity[] = [];
  const missing: string[] = [];
  for (const e of obj.entities) {
    if (typeof e !== 'object' || e === null) throw new Error('实体必须是对象');
    const ent = e as { id?: unknown; name?: unknown; mesh?: unknown; position?: unknown };
    if (typeof ent.id !== 'string' || typeof ent.name !== 'string' || typeof ent.mesh !== 'string') {
      throw new Error('实体缺少 id/name/mesh');
    }
    const position = asVec3(ent.position);
    entities.push({ id: ent.id, name: ent.name, mesh: ent.mesh, position });
    if (!findNode(root, ent.mesh)) missing.push(ent.mesh);
  }
  return { document: { name: obj.name, entities }, missing };
}

/** 《微光岛》关卡的最小样例，用作真跑输入与文档示例。 */
export const GLIMMER_ISLE_SAMPLE = {
  name: 'glimmer-isle',
  entities: [
    { id: 'e1', name: 'island', mesh: 'assets/art/island.gltf', position: [0, 0, 0] },
    { id: 'e2', name: 'rockR', mesh: 'assets/art/rocks/small.gltf', position: [3, 0, -2] },
  ],
} as const;

// snippet: src/editor/assets/drag-drop.ts 的落点求解
const onDropEv = (e: DragEvent): void => {
  const ids = decodeDragPayload(e.dataTransfer?.getData(ASSET_MIME) ?? '');
  if (ids.length === 0) return;           // 外部拖入：直接忽略
  e.preventDefault();
  const rect = canvas.getBoundingClientRect();
  const ray = pickRay(getCamera(), e.clientX - rect.left, e.clientY - rect.top, rect.width, rect.height);
  const t = rayPlane(ray, [0, 0, 0], [0, 1, 0]); // 投到 y=0 地面
  const at: Vec3 = t === null ? [0, 0, 0] : [ray.origin[0] + ray.dir[0] * t, 0, ray.origin[2] + ray.dir[2] * t];
  onDrop(ids, at);
};