《游戏引擎实现原理》3.2 PAL 平台抽象层

// snippet: 反面写法，本节不采用
import { readFileSync } from 'node:fs';
const data = readFileSync('assets/isle.mesh', 'utf8');

// file: src/core/platform.ts
// tier: L1
// verify: npx vitest run src/core/platform.test.ts
//
// helio 内核：平台抽象层 PAL。内核其余部分只依赖 IPlatform，
// 不直接 import node:fs / window / performance。
// 换平台 = 换一个 IPlatform 实现，调用方代码一行不动。

export interface PlatformTime {
  /** 单调时钟，单位秒。用于帧计时、超时，不用于日历。 */
  nowSeconds(): number;
  /** 单调时钟，单位毫秒。 */
  nowMillis(): number;
}

export interface PlatformFile {
  readText(path: string): string;
  writeText(path: string, data: string): void;
  exists(path: string): boolean;
}

export interface PlatformThread {
  readonly hardwareConcurrency: number;
  /** 在另一条线程上跑 task，返回其完成 Promise。 */
  spawn(task: () => void): Promise<void>;
}

export interface PlatformLog {
  write(level: string, category: string, message: string): void;
}

/** 内核与宿主环境的唯一契约面。 */
export interface IPlatform {
  readonly name: string;
  readonly time: PlatformTime;
  readonly file: PlatformFile;
  readonly thread: PlatformThread;
  readonly log: PlatformLog;
}

/**
 * 与平台无关的代码：只吃 IPlatform。
 * 这段函数在 Node 与浏览器上是同一份源码。
 */
export function measureMillis(p: IPlatform, fn: () => void): number {
  const t0 = p.time.nowMillis();
  fn();
  const t1 = p.time.nowMillis();
  return t1 - t0;
}

/** 内核启动横幅：展示平台名与可用并发度。 */
export function describePlatform(p: IPlatform): string {
  return `${p.name}: ${p.thread.hardwareConcurrency} hw threads`;
}

// file: src/core/node-platform.ts
// tier: L1
// verify: npx vitest run src/core/platform.test.ts
//
// NodePlatform：IPlatform 的 Node 实现，用于命令行工具、离线烘焙与单测。
// 时间走 node:perf_hooks，文件走 node:fs，并发度走 node:os。

import { readFileSync, writeFileSync, existsSync } from 'node:fs';
import { performance } from 'node:perf_hooks';
import { availableParallelism } from 'node:os';
import type {
  IPlatform,
  PlatformFile,
  PlatformLog,
  PlatformThread,
  PlatformTime,
} from './platform.ts';

const nodeTime: PlatformTime = {
  nowSeconds: () => performance.now() / 1000,
  nowMillis: () => performance.now(),
};

const nodeFile: PlatformFile = {
  readText: (path) => readFileSync(path, 'utf8'),
  writeText: (path, data) => writeFileSync(path, data, 'utf8'),
  exists: (path) => existsSync(path),
};

const nodeThread: PlatformThread = {
  hardwareConcurrency: availableParallelism(),
  // 真正的并行要 worker_threads；这里用微任务队列模拟「交给调度器」。
  spawn: (task) => Promise.resolve().then(task),
};

const nodeLog: PlatformLog = {
  write: (level, category, message) => {
    process.stdout.write(`[${level}][${category}] ${message}\n`);
  },
};

export const NodePlatform: IPlatform = {
  name: 'node',
  time: nodeTime,
  file: nodeFile,
  thread: nodeThread,
  log: nodeLog,
};

// file: src/core/node-shims.d.ts
// tier: L3
//
// 本工程未安装 @types/node，这里只声明 NodePlatform 用到的宿主 API。
// 真实工程 `npm i -D @types/node` 后本文件可删。

declare module 'node:fs' {
  export function readFileSync(path: string, encoding: 'utf8'): string;
  export function writeFileSync(path: string, data: string, encoding?: 'utf8'): void;
  export function existsSync(path: string): boolean;
  export function mkdtempSync(prefix: string): string;
}

declare module 'node:os' {
  export function availableParallelism(): number;
  export function tmpdir(): string;
}

declare module 'node:path' {
  export function join(...parts: string[]): string;
}

declare module 'node:perf_hooks' {
  export const performance: { now(): number };
}

declare const process: {
  readonly stdout: { write(chunk: string): boolean };
};

// file: src/core/platform.test.ts
// tier: L1
// verify: npx vitest run src/core/platform.test.ts
import { describe, expect, it } from 'vitest';
import { mkdtempSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { describePlatform, measureMillis } from './platform.ts';
import { NodePlatform } from './node-platform.ts';

describe('PAL on NodePlatform', () => {
  it('同一段 measureMillis 代码在 PAL 上读时间戳', () => {
    const elapsed = measureMillis(NodePlatform, () => {
      let acc = 0;
      for (let i = 0; i < 1000; i++) acc += i;
      expect(acc).toBe(499500);
    });
    expect(elapsed).toBeGreaterThanOrEqual(0);
  });

  it('nowMillis 单调不减', () => {
    const a = NodePlatform.time.nowMillis();
    const b = NodePlatform.time.nowMillis();
    expect(b).toBeGreaterThanOrEqual(a);
  });

  it('文件接口读回写入的内容', () => {
    const dir = mkdtempSync(join(tmpdir(), 'helio-'));
    const path = join(dir, 'cvar.cfg');
    NodePlatform.file.writeText(path, 'r.vsync=true\n');
    expect(NodePlatform.file.exists(path)).toBe(true);
    expect(NodePlatform.file.readText(path)).toBe('r.vsync=true\n');
  });

  it('describePlatform 汇总平台信息', () => {
    expect(describePlatform(NodePlatform)).toMatch(/^node: \d+ hw threads$/);
  });

  it('spawn 异步跑完 task', async () => {
    let ran = false;
    await NodePlatform.thread.spawn(() => {
      ran = true;
    });
    expect(ran).toBe(true);
  });
});