verekia-architecture_skill

Overview

This skill documents day-to-day coding style and architecture for React Three Fiber game development using Miniplex ECS and TypeScript. It prescribes a headless-first, system-driven approach where React components are purely views and the ECS world is the single source of truth. The guidance focuses on practical patterns for queries, systems, entity/view separation, and Three.js syncing.

How this skill works

Systems contain all core game logic and run in useFrame or effects, iterating over component-based queries and mutating entity state. Views are dumb React components that render based on entity data; a ModelContainer attaches Three.js refs to entities so systems can manipulate scene objects directly. Miniplex APIs (world.add, world.remove, world.with, addComponent/removeComponent) are the only supported ways to modify entities.

When to use it

• Building R3F games where game logic must be decoupled from rendering
• When you need headless tests or server-side game simulations without a renderer
• Creating reusable, testable models that are independent of ECS internals
• Syncing Three.js objects to ECS state every frame
• Managing complex spawning, destruction, or state mutation logic in systems

Best practices

• Keep all authoritative state in the ECS world; React is only for rendering
• Define queries at module scope near their system, not in a central file
• Prefer component-based queries (world.with('position','velocity')) over type-based iteration
• Use the One + System pattern: single-entity pure functions + an iterator system
• Only use createReactAPI’s Entities as the React bridge; avoid miniplex-react hooks/components
• Store Three.js refs on entities via a ModelContainer and clean them up on unmount

Example use cases

• VelocitySystem: iterate over entities with velocity and update positions via a one() helper
• ThreeSystem: sync entity.position to entity.three.position each frame
• SpawnSystem: add entities in an effect to initialize enemies or objects
• CharacterEntity + CharacterModel: smart wrapper attaches ref, dumb model renders visuals
• Using Zustand for UI state while keeping game state in the ECS world