《游戏引擎实现原理》12.1 从继承到组合到数据

// snippet: 「让所有会动的东西每帧前进」——三种组织方式
// A 继承：行为挂在类树上，位置和速度是对象的字段
class Actor {
  x = 0; y = 0;
  update(_dt: number): void {}
}
class MovingActor extends Actor {
  vx = 0; vy = 0;
  override update(dt: number): void { this.x += this.vx * dt; this.y += this.vy * dt; }
}

// B 组合：对象由可插拔的组件拼成，行为在系统里按需挑选组件
interface Transform { x: number; y: number; }
interface Mover { vx: number; vy: number; }
class GameObject {
  transform: Transform = { x: 0, y: 0 };
  mover?: Mover; // 没有 mover 的物体不会动
}

// C 数据：不要对象，只有一组平行的连续数组，更新就是扫一遍数组
const posX: number[] = [];
const posY: number[] = [];
const velX: number[] = [];
const velY: number[] = [];
function updateAll(dt: number): void {
  for (let i = 0; i < posX.length; i++) {
    posX[i] += velX[i] * dt;
    posY[i] += velY[i] * dt;
  }
}

// file: src/ecs/mini-ecs.ts
// tier: L1
// verify: npx vitest run src/ecs/mini-ecs.test.ts
//
// helio 内核：在世代句柄（SlotMap）之上搭的最小 ECS。
// 实体 = 世代句柄；组件存储 = 每种组件一个 SparseSet，用句柄的槽位号当稀疏 ID。
// 不做查询缓存、不做并行——只把「实体 / 组件 / 系统」三件套接起来。

import { SlotMap, handleIndex, type Handle } from '../core/slotmap.ts';
import { SparseSet } from '../core/sparse-set.ts';

export type ComponentId = number;

/** 每个实体记录它挂了哪些组件，用于销毁时逐个清理。 */
interface EntityInfo {
  comps: Set<ComponentId>;
}

export class MiniEcs {
  #entities = new SlotMap<EntityInfo>();
  #stores = new Map<ComponentId, SparseSet<unknown>>();

  get entityCount(): number {
    return this.#entities.size;
  }

  #store(id: ComponentId): SparseSet<unknown> {
    let s = this.#stores.get(id);
    if (s === undefined) {
      s = new SparseSet<unknown>();
      this.#stores.set(id, s);
    }
    return s;
  }

  spawn(): Handle {
    return this.#entities.insert({ comps: new Set() });
  }

  alive(h: Handle): boolean {
    return this.#entities.has(h);
  }

  add<T>(h: Handle, id: ComponentId, value: T): void {
    const info = this.#entities.expect(h);
    this.#store(id).add(handleIndex(h), value);
    info.comps.add(id);
  }

  has(h: Handle, id: ComponentId): boolean {
    if (!this.#entities.has(h)) return false;
    return this.#store(id).has(handleIndex(h));
  }

  get<T>(h: Handle, id: ComponentId): T | undefined {
    if (!this.#entities.has(h)) return undefined;
    return this.#store(id).get(handleIndex(h)) as T | undefined;
  }

  remove(h: Handle, id: ComponentId): boolean {
    const info = this.#entities.get(h);
    if (info === undefined) return false;
    info.comps.delete(id);
    return this.#store(id).remove(handleIndex(h));
  }

  /** 销毁实体：先清掉它的全部组件，再回收句柄（世代自增）。 */
  destroy(h: Handle): boolean {
    const info = this.#entities.get(h);
    if (info === undefined) return false;
    for (const id of info.comps) this.#store(id).remove(handleIndex(h));
    return this.#entities.remove(h);
  }

  /** 查询：返回同时拥有全部给定组件的实体句柄。 */
  query(...ids: ComponentId[]): Handle[] {
    const out: Handle[] = [];
    for (const [h, info] of this.#entities.entries()) {
      let ok = true;
      for (const id of ids) {
        if (!info.comps.has(id)) {
          ok = false;
          break;
        }
      }
      if (ok) out.push(h);
    }
    return out;
  }
}

// file: src/ecs/mini-ecs.test.ts
// tier: L1
// verify: npx vitest run src/ecs/mini-ecs.test.ts

import { describe, expect, it } from 'vitest';
import { MiniEcs } from './mini-ecs.ts';

const POSITION = 1;
const VELOCITY = 2;
const SPRITE = 3;

interface Vec2 {
  x: number;
  y: number;
}

describe('MiniEcs 基本操作', () => {
  it('spawn 返回有效句柄，组件可增可查', () => {
    const ecs = new MiniEcs();
    const e = ecs.spawn();
    expect(ecs.alive(e)).toBe(true);
    ecs.add<Vec2>(e, POSITION, { x: 1, y: 2 });
    expect(ecs.has(e, POSITION)).toBe(true);
    expect(ecs.get<Vec2>(e, POSITION)).toEqual({ x: 1, y: 2 });
    expect(ecs.has(e, VELOCITY)).toBe(false);
    expect(ecs.entityCount).toBe(1);
  });

  it('query 返回同时拥有全部组件的实体', () => {
    const ecs = new MiniEcs();
    const a = ecs.spawn();
    ecs.add(a, POSITION, { x: 0, y: 0 });
    ecs.add(a, VELOCITY, { x: 1, y: 0 });
    const b = ecs.spawn();
    ecs.add(b, POSITION, { x: 0, y: 0 });
    ecs.add(b, SPRITE, 7);
    const movers = ecs.query(POSITION, VELOCITY);
    expect(movers).toEqual([a]);
  });

  it('destroy 清组件并让旧句柄立即失效', () => {
    const ecs = new MiniEcs();
    const e = ecs.spawn();
    ecs.add(e, POSITION, { x: 0, y: 0 });
    expect(ecs.destroy(e)).toBe(true);
    expect(ecs.alive(e)).toBe(false);
    expect(ecs.get(e, POSITION)).toBeUndefined();
    expect(ecs.entityCount).toBe(0);
  });

  it('槽位复用但旧句柄读不到新实体的组件', () => {
    const ecs = new MiniEcs();
    const old = ecs.spawn();
    ecs.add(old, POSITION, { x: 9, y: 9 });
    ecs.destroy(old);
    const fresh = ecs.spawn(); // 复用同一槽位，世代自增
    ecs.add(fresh, POSITION, { x: 1, y: 1 });
    expect(ecs.get(old, POSITION)).toBeUndefined(); // 旧句柄失效
    expect(ecs.get(fresh, POSITION)).toEqual({ x: 1, y: 1 });
  });

  it('remove 单组件后 query 不再命中', () => {
    const ecs = new MiniEcs();
    const e = ecs.spawn();
    ecs.add(e, POSITION, { x: 0, y: 0 });
    ecs.add(e, VELOCITY, { x: 0, y: 0 });
    expect(ecs.remove(e, VELOCITY)).toBe(true);
    expect(ecs.query(POSITION, VELOCITY)).toEqual([]);
    expect(ecs.has(e, POSITION)).toBe(true);
  });
});