《游戏引擎实现原理》5.2 特性开关与死代码消除

// snippet: rolldown 的 transform.define，把环境变量固化成字面量
const shipPostfx = process.env.SHIP_POSTFX === '1';
const bundle = await build({
  input: 'src/apps/feature-frame.ts',
  output: { format: 'esm' },
  transform: { define: { __FEATURE_POSTFX__: String(shipPostfx) } },
});

// file: src/core/feature-flags.ts
// tier: L1
// verify: npx vitest run src/core/feature-flags.test.ts
//
// helio 工程化：构建期特性开关。
// 每个开关是模块级 const 字面量。打包器把它内联进 `if (FEATURE_X)`，
// 于是 false 分支连同「只被该分支用到的 import」一起被摇掉。
// 改一行字面量 + 重新打包 = 出包体积变化，这就是死代码消除。

export const FEATURE_SHADOWS = true;
export const FEATURE_POSTFX = true;
export const FEATURE_UI2D = false;

/** 运行期遥测用：列出这次构建真正编进去的特性。 */
export function activeFeatures(): string[] {
  const out: string[] = [];
  if (FEATURE_SHADOWS) out.push('shadows');
  if (FEATURE_POSTFX) out.push('postfx');
  if (FEATURE_UI2D) out.push('ui2d');
  return out;
}

// file: src/core/feature-flags.test.ts
// tier: L1
// verify: npx vitest run src/core/feature-flags.test.ts
import { describe, expect, it } from 'vitest';
import {
  FEATURE_POSTFX,
  FEATURE_SHADOWS,
  FEATURE_UI2D,
  activeFeatures,
} from './feature-flags.ts';

describe('feature-flags', () => {
  it('开关是布尔字面量，可被打包器常量折叠', () => {
    expect(typeof FEATURE_SHADOWS).toBe('boolean');
    expect(typeof FEATURE_POSTFX).toBe('boolean');
    expect(typeof FEATURE_UI2D).toBe('boolean');
  });

  it('activeFeatures 只列出编进来的特性', () => {
    expect(activeFeatures()).toEqual(['shadows', 'postfx']);
    expect(activeFeatures()).not.toContain('ui2d');
  });
});

// file: src/apps/feature-frame.ts
// tier: L1
// verify: node tools/feature-bundle.mjs
//
// 帧组装入口：按编译期开关决定这一帧要跑哪些 pass。
// 每个 if 里的重模块都只被该分支引用，关掉开关它就会从产物里消失。
import { FEATURE_SHADOWS, FEATURE_POSTFX, FEATURE_UI2D } from '../core/feature-flags.ts';
import { buildShadowCascades } from '../render/shadow/shadow-cascade-build.ts';
import { bloomPass } from '../render/postfx/bloom-pass.ts';
import { buildOverlay } from '../render/ui2d/ui2d-overlay.ts';

const LUMA = new Float32Array(256);

export function buildFrame(): string[] {
  const passes: string[] = ['base'];
  if (FEATURE_SHADOWS) {
    passes.push(`shadow:${buildShadowCascades(4, 200).length}`);
  }
  if (FEATURE_POSTFX) {
    passes.push(`bloom:${bloomPass(LUMA, 0.8).length}`);
  }
  if (FEATURE_UI2D) {
    passes.push(`ui2d:${buildOverlay(['hud', 'menu']).length}`);
  }
  return passes;
}

// file: src/render/postfx/bloom-pass.ts
// tier: L1
// verify: node tools/feature-bundle.mjs
//
// 重模块示例：泛光。只有开后处理的构建才该带上它。
export function bloomPass(luma: Float32Array, threshold: number): Float32Array {
  const out = new Float32Array(luma.length);
  for (let i = 0; i < luma.length; i++) {
    out[i] = Math.max(0, luma[i] - threshold);
  }
  return out;
}

// file: tools/feature-bundle.mjs
// tier: L1
// verify: node tools/feature-bundle.mjs
//
// helio 工程化：用不同特性开关组合打包同一个入口，打印产物体积。
// 做法是给打包器挂一个插件，把 src/core/feature-flags.ts 的内容按组合
// 替换成字面量常量；打包器的 tree-shaking 负责把死分支和它的独占模块摇掉。

import { build } from 'rolldown';
import { fileURLToPath } from 'node:url';
import { dirname, resolve } from 'node:path';

const HERE = dirname(fileURLToPath(import.meta.url));
const ROOT = resolve(HERE, '..');
const ENTRY = resolve(ROOT, 'src/apps/feature-frame.ts');
const FLAGS = resolve(ROOT, 'src/core/feature-flags.ts');

/** 用字面量常量覆盖 flags 模块，模拟「改一行开关 + 重新打包」。 */
function flagPlugin(flags) {
  return {
    name: 'flag-override',
    load(id) {
      if (id !== FLAGS) return null;
      return [
        `export const FEATURE_SHADOWS = ${flags.shadows};`,
        `export const FEATURE_POSTFX = ${flags.postfx};`,
        `export const FEATURE_UI2D = ${flags.ui2d};`,
        'export function activeFeatures() { return []; }',
      ].join('\n');
    },
  };
}

const combos = [
  { label: 'all-on', shadows: true, postfx: true, ui2d: true },
  { label: 'no-ui2d', shadows: true, postfx: true, ui2d: false },
  { label: 'shadows-only', shadows: true, postfx: false, ui2d: false },
  { label: 'mobile-min', shadows: false, postfx: false, ui2d: false },
];

const rows = [];
for (const combo of combos) {
  const bundle = await build({
    input: ENTRY,
    output: { format: 'esm' },
    platform: 'node',
    treeshake: true,
    plugins: [flagPlugin(combo)],
  });
  const code = bundle.output[0].code;
  rows.push({ label: combo.label, bytes: Buffer.byteLength(code), lines: code.split('\n').length - 1 });
}

const base = rows[0].bytes;
console.log('combo          bytes   vs all-on');
for (const r of rows) {
  const pct = (((r.bytes - base) / base) * 100).toFixed(1);
  console.log(`${r.label.padEnd(14)} ${String(r.bytes).padStart(5)}   ${pct.padStart(6)}%`);
}

combo          bytes   vs all-on
all-on          1140      0.0%
no-ui2d          903    -20.8%
shadows-only     515    -54.8%
mobile-min        80    -93.0%

function buildFrame() {
	return ["base"];
}
export { buildFrame };

$ node -e "import('./src/apps/feature-frame.ts').then(m=>console.log(m.buildFrame().join(' | ')))"
base | shadow:4 | bloom:256