《游戏引擎实现原理》5.3 插件系统与引擎版本 / API 稳定性

// snippet: 插件清单里的两个兼容性字段
{
  "id": "shadow-quality",
  "engineRange": "^1.4.0",
  "apiVersion": 3
}

// file: src/core/plugin-host.ts
// tier: L1
// verify: npx vitest run src/core/plugin-host.test.ts
//
// helio 工程化：插件宿主。插件在加载时声明两条兼容性约束：
//   - engineRange：宿主引擎版本必须落在的语义化版本范围；
//   - apiVersion：插件接口的整数版本，必须与宿主完全相等。
// 两条都过才允许 setup；否则给出可读的拒绝原因，绝不半加载。

export interface Semver {
  readonly major: number;
  readonly minor: number;
  readonly patch: number;
}

const SEMVER_RE = /^(\d+)\.(\d+)\.(\d+)$/;

export function parseSemver(text: string): Semver | null {
  const m = SEMVER_RE.exec(text);
  if (m === null) return null;
  return { major: Number(m[1]), minor: Number(m[2]), patch: Number(m[3]) };
}

/** 逐段比较：a<b 返回 -1，a>b 返回 1，相等返回 0。 */
export function compareSemver(a: Semver, b: Semver): number {
  for (const k of ['major', 'minor', 'patch'] as const) {
    if (a[k] !== b[k]) return a[k] < b[k] ? -1 : 1;
  }
  return 0;
}

/** 支持 `^1.4.0`、`~1.4.0`、`>=1.4.0`、`==1.4.0` 与裸 `1.4.0` 五种写法。 */
export function satisfiesRange(range: string, version: string): boolean {
  const v = parseSemver(version);
  if (v === null) return false;
  const op = range.startsWith('^') || range.startsWith('~') ? range[0]
    : range.startsWith('>=') ? '>='
    : range.startsWith('==') ? '=='
    : '==';
  const base = parseSemver(range.replace(/^(\^|~|>=|==)/, ''));
  if (base === null) return false;
  if (op === '>=') return compareSemver(v, base) >= 0;
  if (op === '==') return compareSemver(v, base) === 0;
  if (op === '~') {
    return compareSemver(v, base) >= 0 && v.major === base.major && v.minor === base.minor;
  }
  // '^'：>= base 且同主版本
  return compareSemver(v, base) >= 0 && v.major === base.major;
}

export interface PluginContext {
  readonly engineVersion: string;
  readonly apiVersion: number;
  register(extension: string): void;
}

export interface Plugin {
  readonly id: string;
  readonly engineRange: string;
  readonly apiVersion: number;
  readonly setup: (ctx: PluginContext) => void;
}

export type PluginStatus = 'loaded' | 'engine-mismatch' | 'api-mismatch' | 'duplicate';

export interface LoadResult {
  readonly id: string;
  readonly status: PluginStatus;
  readonly reason: string;
}

export interface HostOptions {
  readonly engineVersion: string;
  readonly apiVersion: number;
}

export interface Host {
  load(plugin: Plugin): LoadResult;
  readonly loaded: readonly string[];
  readonly extensions: readonly string[];
}

export function createPluginHost(opts: HostOptions): Host {
  const loaded: string[] = [];
  const extensions: string[] = [];

  return {
    load(plugin: Plugin): LoadResult {
      if (loaded.includes(plugin.id)) {
        return { id: plugin.id, status: 'duplicate', reason: `插件 ${plugin.id} 已加载` };
      }
      if (!satisfiesRange(plugin.engineRange, opts.engineVersion)) {
        return {
          id: plugin.id,
          status: 'engine-mismatch',
          reason: `引擎 ${opts.engineVersion} 不满足 ${plugin.engineRange}`,
        };
      }
      if (plugin.apiVersion !== opts.apiVersion) {
        return {
          id: plugin.id,
          status: 'api-mismatch',
          reason: `插件接口版本 ${plugin.apiVersion} != 宿主 ${opts.apiVersion}`,
        };
      }
      plugin.setup({
        engineVersion: opts.engineVersion,
        apiVersion: opts.apiVersion,
        register: (extension) => { extensions.push(extension); },
      });
      loaded.push(plugin.id);
      return { id: plugin.id, status: 'loaded', reason: 'ok' };
    },
    get loaded() { return loaded; },
    get extensions() { return extensions; },
  };
}

loaded           shadow-quality  ok
engine-mismatch  future-water    引擎 1.4.2 不满足 ^2.0.0
api-mismatch     legacy-tools    插件接口版本 2 != 宿主 3
duplicate        shadow-quality  插件 shadow-quality 已加载
loaded: shadow-quality
extensions: shadow-quality:hook

// snippet: src/core/plugin-host.test.ts 的加载判定用例
it('兼容插件被加载并注册扩展', () => {
  const host = createPluginHost({ engineVersion: ENGINE, apiVersion: API });
  const r = host.load(makePlugin('shadow-quality', '^1.4.0', API));
  expect(r.status).toBe('loaded');
  expect(host.extensions).toEqual(['shadow-quality:hook']);
});

it('引擎版本不满足范围时拒绝', () => {
  const host = createPluginHost({ engineVersion: ENGINE, apiVersion: API });
  expect(host.load(makePlugin('future', '^2.0.0', API)).status).toBe('engine-mismatch');
  expect(host.loaded).toEqual([]);
});