ecs-systems

narehart 的头像作者 narehart

Create ECS system functions that mutate the game world

📖 中文导读:Create ECS system functions that mutate the game world 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: ecs-systems description: Create ECS system functions that mutate the game world

ECS Systems

Write system functions in src/ecs/systems/ that implement game logic.

Requirements

  • File naming: *System.ts (e.g., moveItemSystem.ts)
  • Must reference: world or imported query functions from src/ecs/queries/
  • One system per file

Pattern

import { world } from '../world';
import type { Entity } from '../world';

interface SystemNameProps {
  entityId: string;
  // other parameters
}

interface SystemNameReturn {
  success: boolean;
  // optional data on success
}

export function systemName(props: SystemNameProps): SystemNameReturn {
  const { entityId } = props;

  // Query entities
  const entity = world.get(entityId);
  if (entity === undefined) {
    return { success: false };
  }

  // Perform mutations
  world.update(entity, {
    /* component changes */
  });

  return { success: true };
}

Rules

  1. No pure helper functions - Extract to src/utils/ instead
  2. Props interface - All parameters via single props object
  3. Return object - Always return { success: boolean, ...data }
  4. Query before mutate - Validate entities exist before changing them
  5. Single responsibility - One logical operation per system

Examples

Good system names:

  • moveItemSystem - moves an item between grids
  • destroyItemSystem - removes an item from the world
  • equipItemSystem - places item in equipment slot

Bad (should be utils):

  • findFreePosition - pure calculation, no world access
  • isSpaceFree - pure validation, no world access