《游戏引擎实现原理》3.1 子系统注册、启动顺序与逆序关闭

// file: src/core/subsystem.ts
// tier: L1
// verify: npx vitest run src/core/subsystem.test.ts
//
// helio 内核：子系统注册与生命周期编排。
// 每个子系统声明自己的名字与依赖；注册表负责拓扑排序、
// 按序 onInit/onStart、逆序 onStop/onShutdown，并在注册阶段就拒绝循环依赖。

/** 传给 onInit 的上下文：内核在启动时注入的公共设施。 */
export interface SubsystemContext {
  readonly frameCount: number;
  log(msg: string): void;
}

/** 一个内核子系统。四个生命周期钩子都会按确定顺序被调用。 */
export interface ISubsystem {
  readonly name: string;
  /** 本子系统启动前必须先启动的子系统名。 */
  readonly dependencies: readonly string[];
  onInit(ctx: SubsystemContext): void;
  onStart(): void;
  onStop(): void;
  onShutdown(): void;
}

const WHITE = 0;
const GRAY = 1;
const BLACK = 2;

/**
 * 子系统注册表。启动顺序 = 依赖拓扑序（被依赖者先启动），
 * 关闭顺序 = 启动顺序的严格逆序。
 */
export class SubsystemRegistry {
  readonly #subsystems = new Map<string, ISubsystem>();
  #order: ISubsystem[] = [];
  #phase: 'idle' | 'running' | 'stopped' = 'idle';

  /** 注册。一旦启动过就不再允许注册（避免顺序在运行期变化）。 */
  register(sub: ISubsystem): void {
    if (this.#phase === 'running') {
      throw new Error(`cannot register ${sub.name}: registry already running`);
    }
    if (this.#subsystems.has(sub.name)) {
      throw new Error(`duplicate subsystem: ${sub.name}`);
    }
    this.#subsystems.set(sub.name, sub);
  }

  /** 只读地取出拓扑序，不触发任何生命周期钩子——方便测试与工具。 */
  resolveOrder(): ISubsystem[] {
    const color = new Map<string, number>();
    const out: ISubsystem[] = [];
    const path: string[] = [];

    const visit = (name: string): void => {
      const c = color.get(name) ?? WHITE;
      if (c === BLACK) return;
      if (c === GRAY) {
        const start = path.indexOf(name);
        const cycle = path.slice(start).concat(name);
        throw new Error(`cyclic subsystem dependency: ${cycle.join(' -> ')}`);
      }
      const sub = this.#subsystems.get(name);
      if (sub === undefined) {
        throw new Error(`unknown subsystem dependency: ${name}`);
      }
      color.set(name, GRAY);
      path.push(name);
      for (const dep of sub.dependencies) visit(dep);
      path.pop();
      color.set(name, BLACK);
      out.push(sub);
    };

    for (const name of this.#subsystems.keys()) visit(name);
    return out;
  }

  /** 按拓扑序 onInit 全部，再按拓扑序 onStart 全部。 */
  boot(ctx: SubsystemContext): void {
    if (this.#phase === 'running') throw new Error('registry already booted');
    this.#order = this.resolveOrder();
    for (const sub of this.#order) sub.onInit(ctx);
    for (const sub of this.#order) sub.onStart();
    this.#phase = 'running';
  }

  /** 按启动顺序的逆序 onStop 全部，再逆序 onShutdown 全部。 */
  shutdown(): void {
    if (this.#phase !== 'running') throw new Error('registry is not running');
    const reverse = [...this.#order].reverse();
    for (const sub of reverse) sub.onStop();
    for (const sub of reverse) sub.onShutdown();
    this.#order = [];
    this.#phase = 'stopped';
  }

  /** 当前生效的启动顺序（boot 之前为空）。 */
  get startOrder(): readonly ISubsystem[] {
    return this.#order;
  }
}

// file: src/core/subsystem.test.ts
// tier: L1
// verify: npx vitest run src/core/subsystem.test.ts
import { describe, expect, it } from 'vitest';
import { SubsystemRegistry } from './subsystem.ts';
import type { ISubsystem, SubsystemContext } from './subsystem.ts';

const ctx: SubsystemContext = { frameCount: 0, log: () => {} };

/** 造一个把所有生命周期调用写进 log 的假子系统。 */
function fake(name: string, deps: string[], log: string[]): ISubsystem {
  return {
    name,
    dependencies: deps,
    onInit: () => log.push(`init:${name}`),
    onStart: () => log.push(`start:${name}`),
    onStop: () => log.push(`stop:${name}`),
    onShutdown: () => log.push(`shutdown:${name}`),
  };
}

describe('SubsystemRegistry', () => {
  it('按依赖拓扑序启动（被依赖者先启动）', () => {
    const log: string[] = [];
    const r = new SubsystemRegistry();
    // 注册顺序刻意打乱：render 依赖 scene，scene 依赖 asset，asset 无依赖。
    r.register(fake('render', ['scene'], log));
    r.register(fake('scene', ['asset'], log));
    r.register(fake('asset', [], log));
    r.boot(ctx);
    expect(log).toEqual([
      'init:asset', 'init:scene', 'init:render',
      'start:asset', 'start:scene', 'start:render',
    ]);
  });

  it('关闭顺序是启动顺序的严格逆序', () => {
    const log: string[] = [];
    const r = new SubsystemRegistry();
    r.register(fake('render', ['scene'], log));
    r.register(fake('scene', ['asset'], log));
    r.register(fake('asset', [], log));
    r.boot(ctx);
    const startOrder = r.startOrder.map((s) => s.name);
    log.length = 0;
    r.shutdown();
    const stopOrder = log.filter((e) => e.startsWith('stop:')).map((e) => e.slice(5));
    expect(stopOrder).toEqual([...startOrder].reverse());
  });

  it('先全部 onStop 再全部 onShutdown', () => {
    const log: string[] = [];
    const r = new SubsystemRegistry();
    r.register(fake('a', [], log));
    r.register(fake('b', ['a'], log));
    r.boot(ctx);
    log.length = 0;
    r.shutdown();
    expect(log).toEqual(['stop:b', 'stop:a', 'shutdown:b', 'shutdown:a']);
  });

  it('检测循环依赖并给出环路径', () => {
    const log: string[] = [];
    const r = new SubsystemRegistry();
    r.register(fake('a', ['b'], log));
    r.register(fake('b', ['a'], log));
    expect(() => r.resolveOrder()).toThrow(/cyclic subsystem dependency: a -> b -> a/);
  });

  it('依赖不存在的子系统时报错', () => {
    const r = new SubsystemRegistry();
    r.register(fake('a', ['ghost'], []));
    expect(() => r.resolveOrder()).toThrow(/unknown subsystem dependency: ghost/);
  });

  it('重复注册同名子系统报错', () => {
    const r = new SubsystemRegistry();
    r.register(fake('a', [], []));
    expect(() => r.register(fake('a', [], []))).toThrow(/duplicate subsystem: a/);
  });

  it('boot 之后禁止再注册', () => {
    const r = new SubsystemRegistry();
    r.register(fake('a', [], []));
    r.boot(ctx);
    expect(() => r.register(fake('b', [], []))).toThrow(/already running/);
  });
});