kadajett/bitecs-agent-skill

Overview

This skill is a concise, practical guide to using bitECS v0.4.0, a minimal, data-oriented Entity Component System library for TypeScript. It explains world and entity management, component formats and operations, querying patterns, relationships, prefabs, serialization hooks, and observers. Use it to build performant game and simulation architecture with clear examples and recommended patterns.

How this skill works

bitECS stores components as arrays (SoA, AoS, or typed arrays) attached to a World object; entities are numeric IDs created and recycled by the world or a shared entity index. Systems operate by running queries that return entities matching component compositions, relationships, or hierarchical constraints. Observers and relation hooks let you react to component lifecycle events, and serialization utilities support binary save/load and networking.

When to use it

• Building games or simulations with ECS architecture
• Managing entities, components, and hierarchical relationships
• Implementing prefabs and entity templates with inheritance
• Querying and iterating entities efficiently, including nested and hierarchical traversal
• Serializing/deserializing ECS state for networking or save systems
• Reacting to component changes with observers and validation hooks

Best practices

• Prefer SoA with TypedArrays for multithreading and cache-friendly access; use AoS only for small collections (<100k)
• Register components or use addComponent consistently so world.components stays accurate
• Use versioned entity indices when you need robust ID lifecycle handling across recycles
• Mark entities for removal via a tag component and perform batched deletions to avoid iterator invalidation
• Use query modifiers (asBuffer, isNested/noCommit) for safe nested iteration and to return contiguous buffers for native loops
• Define onSet/onGet observers when using prefabs so instance access inherits values correctly

Example use cases

• Create a physics system that queries Position and Velocity (SoA float arrays) and updates positions per tick
• Implement an inventory relationship (Contains) with a store for item counts and queries for all containers of a target
• Build prefabs (IsA) for shared templates such as NPC archetypes and instantiate fast entity instances at runtime
• Serialize a subset of world components to a binary buffer for network state sync and deserialize on clients
• Use Hierarchy/Cascade to process parent entities before children for scene graph updates