《游戏引擎实现原理》1.3 分包与首包体

// snippet: 懒加载根在游戏代码里的声明方式
// tier: L1

// 静态 import：进入这个模块时就一起加载（首屏必需）。
import { Kernel } from '../core/kernel.ts';

// 动态 import：只有真正调用时才去拉对应 chunk（懒加载）。
async function enterGameplay(): Promise<void> {
  const { runDemo, recordedInput } = await import('../apps/glimmer-isle-demo.ts');
  runDemo(recordedInput(120));
}

// file: tools/split-chunks.mjs
// tier: L1
// verify: node tools/split-chunks.mjs
//
// 分包器：给定「入口模块」和一组「懒加载根」（动态 import 的落点），
// 把模块图切成若干 chunk——
//   - 入口 chunk = 从入口静态可达、且不穿过任何懒加载根的模块（首包必需）
//   - 懒加载 chunk[k] = 从 lazyRoot[k] 可达、且未被更早的 chunk 认领的模块
// 量出「首包」与「整包」的真实字节数，以及 gzip 后的首包体积。

import { gzipSync } from 'node:zlib';
import { buildGraph } from './module-graph.mjs';
import { bundle } from './bundle-analyze.mjs';

/** 从 start 出发的静态可达集；lazyRoots 里的模块当作叶子（不展开其依赖）。 */
function reachFrom(graph, start, lazyRoots) {
  const lazy = new Set(lazyRoots);
  const seen = new Set();
  const stack = [start];
  while (stack.length) {
    const cur = stack.pop();
    if (seen.has(cur)) continue;
    seen.add(cur);
    if (cur !== start && lazy.has(cur)) continue; // 懒加载根：到此为止
    for (const dep of graph.modules.get(cur)?.imports ?? []) if (!seen.has(dep)) stack.push(dep);
  }
  return seen;
}

/** 完全展开的可达集（穿懒加载根），用于算懒加载 chunk 的大小。 */
function reachAll(graph, start) {
  const seen = new Set();
  const stack = [start];
  while (stack.length) {
    const cur = stack.pop();
    if (seen.has(cur)) continue;
    seen.add(cur);
    for (const dep of graph.modules.get(cur)?.imports ?? []) if (!seen.has(dep)) stack.push(dep);
  }
  return seen;
}

/** 按 manifest 切分，返回 { entry, lazy: [{name, root, modules}] }。 */
export function split(graph, manifest) {
  const lazyRoots = manifest.lazy.map((l) => l.root);
  const assigned = new Set();
  const entryModules = [...reachFrom(graph, manifest.entry, lazyRoots)].filter((m) => !lazyRoots.includes(m));
  for (const m of entryModules) assigned.add(m);

  const lazy = [];
  for (const l of manifest.lazy) {
    const mods = [...reachAll(graph, l.root)].filter((m) => !assigned.has(m));
    for (const m of mods) assigned.add(m);
    lazy.push({ name: l.name, root: l.root, modules: mods });
  }
  return { entry: entryModules, lazy };
}

const bytesOf = (graph, mods) => mods.reduce((n, m) => n + (graph.modules.get(m)?.bytes ?? 0), 0);

if (import.meta.url === `file://${process.argv[1]}`) {
  const graph = buildGraph('src');
  const manifest = {
    entry: 'src/apps/kernel-boot.ts',
    lazy: [
      { name: 'gameplay', root: 'src/apps/glimmer-isle-demo.ts' },
      { name: 'frame-sync', root: 'src/apps/frame-sync-demo.ts' },
    ],
  };
  const { entry, lazy } = split(graph, manifest);

  const kb = (n) => (n / 1024).toFixed(1);
  const entryBytes = bytesOf(graph, entry);
  console.log('== 《微光岛》分包：首包 vs 懒加载 ==');
  console.log(`入口 chunk（首包必需）  ${entry.length} 模块  ${entryBytes} 字节 (${kb(entryBytes)} KB)`);
  let lazyTotal = 0;
  for (const l of lazy) {
    const b = bytesOf(graph, l.modules);
    lazyTotal += b;
    console.log(`懒加载 ${l.name.padEnd(10)} ${String(l.modules.length).padStart(2)} 模块  ${b} 字节 (${kb(b)} KB)`);
  }
  const total = entryBytes + lazyTotal;
  console.log(`\n首包 ${entryBytes} 字节，整包 ${total} 字节，首包占比 ${((entryBytes / total) * 100).toFixed(1)}%`);
  const entryGzip = gzipSync(bundle(graph, entry), { level: 9 }).length;
  console.log(`首包 gzip 后 ${entryGzip} 字节（真实压缩入口 chunk 的 bundle）`);

  // 对照：不做「共享依赖上提」，每个懒加载根各带一份完整子树（会重复打包）。
  const lazyRoots = manifest.lazy.map((l) => l.root);
  const naiveEntry = reachFrom(graph, manifest.entry, lazyRoots);
  const naiveLazy = manifest.lazy.map((l) => [...reachAll(graph, l.root)]);
  const naiveBytes =
    bytesOf(graph, [...naiveEntry]) + naiveLazy.reduce((n, m) => n + bytesOf(graph, m), 0);
  console.log(`\n对照：不上提共享依赖时，各 chunk 各带一份，整包膨胀到 ${naiveBytes} 字节`);
  console.log(`      （相对上提后的 ${total} 字节，多出 ${naiveBytes - total} 字节重复）`);
}

// file: tools/emit-chunks.mjs
// tier: L1
// verify: node tools/emit-chunks.mjs
//
// 把分包结果真正落盘：每个 chunk 用 bundle() 拼成一份可独立运行的 .ts，
// 写到 artifacts/chunks/ 下，并报出各自的原始字节与 gzip 字节。
// 首包（entry）与懒加载 chunk 的字节之和，就是「整包」的真实体积。

import { gzipSync } from 'node:zlib';
import { writeFileSync, mkdirSync } from 'node:fs';
import { buildGraph } from './module-graph.mjs';
import { bundle } from './bundle-analyze.mjs';
import { split } from './split-chunks.mjs';

const OUT_DIR = 'artifacts/chunks';

/** 把一个 chunk 的模块拼成 bundle，落盘并返回 { bytes, gzip }。 */
function emit(graph, name, modules) {
  const code = bundle(graph, modules);
  const bytes = Buffer.byteLength(code);
  const gz = gzipSync(code, { level: 9 }).length;
  writeFileSync(`${OUT_DIR}/${name}.ts`, code);
  return { bytes, gzip: gz };
}

if (import.meta.url === `file://${process.argv[1]}`) {
  const graph = buildGraph('src');
  const manifest = {
    entry: 'src/apps/kernel-boot.ts',
    lazy: [
      { name: 'gameplay', root: 'src/apps/glimmer-isle-demo.ts' },
      { name: 'frame-sync', root: 'src/apps/frame-sync-demo.ts' },
    ],
  };
  const { entry, lazy } = split(graph, manifest);
  mkdirSync(OUT_DIR, { recursive: true });

  let rawTotal = 0;
  let gzTotal = 0;
  console.log('== 落盘的 chunk（bundle 后字节 / gzip 后字节）==');
  for (const [name, mods] of [['entry', entry], ...lazy.map((l) => [l.name, l.modules])]) {
    const { bytes, gzip } = emit(graph, name, mods);
    rawTotal += bytes;
    gzTotal += gzip;
    console.log(`${name.padEnd(10)} ${String(mods.length).padStart(2)} 模块  ${String(bytes).padStart(6)} 字节  gzip ${String(gzip).padStart(5)} 字节`);
  }
  console.log(`\n整包（三 chunk 之和）  ${rawTotal} 字节，gzip 后 ${gzTotal} 字节`);
  console.log(`落盘目录：${OUT_DIR}/entry.ts, gameplay.ts, frame-sync.ts`);
}

$ node tools/split-chunks.mjs
== 《微光岛》分包：首包 vs 懒加载 ==
入口 chunk（首包必需）  6 模块  19517 字节 (19.1 KB)
懒加载 gameplay    1 模块  3004 字节 (2.9 KB)
懒加载 frame-sync  2 模块  6691 字节 (6.5 KB)

首包 19517 字节，整包 29212 字节，首包占比 66.8%
首包 gzip 后 6558 字节（真实压缩入口 chunk 的 bundle）

对照：不上提共享依赖时，各 chunk 各带一份，整包膨胀到 47439 字节
      （相对上提后的 29212 字节，多出 18227 字节重复）

$ node tools/emit-chunks.mjs
== 落盘的 chunk（bundle 后字节 / gzip 后字节）==
entry       6 模块   19122 字节  gzip  6558 字节
gameplay    1 模块    2925 字节  gzip  1416 字节
frame-sync  2 模块    6566 字节  gzip  2781 字节

整包（三 chunk 之和）  28613 字节，gzip 后 10755 字节
落盘目录：artifacts/chunks/entry.ts, gameplay.ts, frame-sync.ts