《游戏引擎实现原理》1.1 引擎的分层与模块边界

┌──────────────────────────────────────────────────────────┐
│  游戏层 Game        《微光岛》玩法、关卡、UI、存档逻辑      │
├──────────────────────────────────────────────────────────┤
│  子系统层 Subsystem  动画 / 物理 / 音频 / AI / 寻路         │
├──────────────────────────────────────────────────────────┤
│  渲染层 Render      渲染器、材质、pass、GPU 资源、渲染图    │
├──────────────────────────────────────────────────────────┤
│  内核层 Kernel      时间 / 内存 / 句柄 / 数学 / ECS / 任务  │
├──────────────────────────────────────────────────────────┤
│  平台层 Platform    窗口 / 输入 / 文件 / 时钟 / 线程        │
└──────────────────────────────────────────────────────────┘
        依赖方向：上层 → 下层，只准向下，绝不准向上

// file: src/core/layers.ts
// tier: L1
// verify: npx vitest run src/core/layers.test.ts
//
// helio 内核：分层与模块边界。
// 五层从下到上：Platform < Kernel < Render < Subsystem < Game。
// 铁律：依赖只能向下（上层 → 下层），内核层永远不许 import 渲染层。
// 这条铁律一半靠类型系统在编译期挡住，一半靠运行期扫描配置兜底。

export const LAYER_ORDER = ['Platform', 'Kernel', 'Render', 'Subsystem', 'Game'] as const;
export type LayerName = (typeof LAYER_ORDER)[number];
export type LayerIndex = 0 | 1 | 2 | 3 | 4;

/** 每一层允许 import 的层集合（只允许向下）。内核层因此拿不到 Render。 */
export type AllowedImports = {
  Platform: never;
  Kernel: 'Platform';
  Render: 'Platform' | 'Kernel';
  Subsystem: 'Platform' | 'Kernel';
  Game: 'Platform' | 'Kernel' | 'Render' | 'Subsystem';
};

/** 带类型约束的模块声明：Kernel 模块写 imports: ['Render'] 会直接编译报错。 */
export interface ModuleSpec<L extends LayerName> {
  readonly name: string;
  readonly layer: L;
  readonly imports: readonly AllowedImports[L][];
}

/** 无类型约束的声明，用于从配置/清单读入后再做运行期校验。 */
export interface LooseModule {
  readonly name: string;
  readonly layer: LayerName;
  readonly imports: readonly LayerName[];
}

export interface Violation {
  readonly from: string;
  readonly fromLayer: LayerName;
  readonly toLayer: LayerName;
}

export function layerIndexOf(layer: LayerName): LayerIndex {
  return LAYER_ORDER.indexOf(layer) as LayerIndex;
}

/** 扫描一组模块，找出所有「向上依赖」（目标层比自身层更高）的非法边。 */
export function findUpwardDeps(modules: readonly LooseModule[]): Violation[] {
  const out: Violation[] = [];
  for (const m of modules) {
    const from = layerIndexOf(m.layer);
    for (const dep of m.imports) {
      if (layerIndexOf(dep) > from) {
        out.push({ from: m.name, fromLayer: m.layer, toLayer: dep });
      }
    }
  }
  return out;
}

/** 统计每一层各有多少个模块，用来核对分层是否真的被使用。 */
export function countByLayer(modules: readonly LooseModule[]): Record<LayerName, number> {
  const acc: Record<LayerName, number> = {
    Platform: 0,
    Kernel: 0,
    Render: 0,
    Subsystem: 0,
    Game: 0,
  };
  for (const m of modules) acc[m.layer] += 1;
  return acc;
}

// file: src/core/layers.test.ts
// tier: L1
// verify: npx vitest run src/core/layers.test.ts
import { describe, expect, it } from 'vitest';
import {
  countByLayer,
  findUpwardDeps,
  layerIndexOf,
  type LooseModule,
  type ModuleSpec,
} from './layers.ts';

describe('layers', () => {
  it('内核模块只依赖平台层，类型层面即通过', () => {
    const clock: ModuleSpec<'Kernel'> = {
      name: 'core/clock',
      layer: 'Kernel',
      imports: ['Platform'],
    };
    expect(clock.imports).toEqual(['Platform']);
    expect(layerIndexOf(clock.layer)).toBe(1);
  });

  it('内核依赖渲染层被类型系统直接拒绝', () => {
    const illegal: ModuleSpec<'Kernel'> = {
      name: 'core/clock',
      layer: 'Kernel',
      // @ts-expect-error Kernel 的 imports 只允许 'Platform'，写 'Render' 编译不过
      imports: ['Render'],
    };
    expect(illegal.name).toBe('core/clock');
  });

  it('运行期能扫出向上的非法依赖', () => {
    const bad: readonly LooseModule[] = [
      { name: 'core/clock', layer: 'Kernel', imports: ['Render'] },
    ];
    const v = findUpwardDeps(bad);
    expect(v).toHaveLength(1);
    expect(v[0].fromLayer).toBe('Kernel');
    expect(v[0].toLayer).toBe('Render');
  });

  it('合法的分层图没有任何非法边', () => {
    const graph: readonly LooseModule[] = [
      { name: 'core/clock', layer: 'Kernel', imports: ['Platform'] },
      { name: 'render/device', layer: 'Render', imports: ['Platform', 'Kernel'] },
      { name: 'subsys/animation', layer: 'Subsystem', imports: ['Kernel'] },
      { name: 'game/island', layer: 'Game', imports: ['Kernel', 'Render', 'Subsystem'] },
    ];
    expect(findUpwardDeps(graph)).toEqual([]);
    expect(countByLayer(graph)).toEqual({
      Platform: 0,
      Kernel: 1,
      Render: 1,
      Subsystem: 1,
      Game: 1,
    });
  });

  it('同层之间依赖不算向上', () => {
    const graph: readonly LooseModule[] = [
      { name: 'kernel/a', layer: 'Kernel', imports: ['Kernel'] },
    ];
    expect(findUpwardDeps(graph)).toEqual([]);
  });
});

✓ src/core/layers.test.ts > layers > 内核模块只依赖平台层，类型层面即通过
✓ src/core/layers.test.ts > layers > 内核依赖渲染层被类型系统直接拒绝
✓ src/core/layers.test.ts > layers > 运行期能扫出向上的非法依赖
✓ src/core/layers.test.ts > layers > 合法的分层图没有任何非法边
✓ src/core/layers.test.ts > layers > 同层之间依赖不算向上
 Test Files  1 passed (1)
      Tests  5 passed (5)