> ## Documentation Index
> Fetch the complete documentation index at: https://hyperscape-ai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Entity Component System

> Understanding Hyperscape's ECS architecture

## Overview

Hyperscape uses an Entity Component System (ECS) architecture for all game logic. This pattern separates data from behavior, making the codebase modular and extensible.

## Core Concepts

### Entities

Entities are game objects with 3D representation, networking, physics, and component-based architecture:

```typescript theme={"theme":{"light":"github-light","dark":"css-variables"}}
// From packages/shared/src/entities/Entity.ts (lines 7-13)
// Key Features:
// - **3D Representation**: Three.js Object3D with mesh, position, rotation, scale
// - **Component System**: Modular components for combat, stats, interaction, etc.
// - **Physics**: Optional PhysX rigid body integration
// - **Networking**: State synchronization across clients
// - **Lifecycle**: spawn(), update(), fixedUpdate(), destroy()
```

Examples: Players, Mobs, Items, Resources, NPCs, Headstones

### Components

Components are registered data containers. Hyperscape uses a component factory system:

```typescript theme={"theme":{"light":"github-light","dark":"css-variables"}}
// From packages/shared/src/entities/Entity.ts (lines 17-23)
// Component Architecture:
// - CombatComponent: Health, attack, defense
// - StatsComponent: Skills, levels, XP
// - InteractionComponent: Player interaction handlers
// - DataComponent: Custom data storage
// - UsageComponent: Item usage logic
// - VisualComponent: 3D model, materials, animations
```

| Component   | Data                                      |
| ----------- | ----------------------------------------- |
| `transform` | Position, rotation, scale (auto-added)    |
| `health`    | Current/max HP, regeneration rate, isDead |
| `combat`    | Attack style, target, cooldown, range     |
| `stats`     | All skills with levels and XP             |
| `inventory` | 28 item slots with quantities             |
| `equipment` | Weapon, armor slots                       |
| `movement`  | Speed, destination, path, isRunning       |
| `stamina`   | Current/max, drain/regen rates            |

### Systems

Systems contain all game logic. They query entities by component and process them each tick.

| System              | Responsibility                |
| ------------------- | ----------------------------- |
| `CombatSystem`      | Damage calculation, hit rolls |
| `MovementSystem`    | Pathfinding, position updates |
| `SkillSystem`       | XP gain, level calculations   |
| `InventorySystem`   | Item management               |
| `PersistenceSystem` | Database saves                |

## Why ECS?

### Composition Over Inheritance

Instead of deep class hierarchies, entities gain capabilities by adding components:

```
Player = Entity + Position + Health + Inventory + Stats + Combat
Tree = Entity + Position + Resource + Harvestable
```

### Performance

Systems process entities in batches, enabling efficient updates for many game objects.

**Recent Optimizations:**

* **Raycast Proxy**: Invisible capsule meshes for instant entity click detection (\~700-1800ms improvement over VRM SkinnedMesh raycast)
* **Event-Driven Health**: Client health bars use events instead of polling (eliminates race conditions)
* **React Optimizations**: `useMemo` and `useCallback` in InventoryPanel for render efficiency
* **Map-Based Tracking**: O(1) lookups for eat delay and attack cooldown management
* **Model Normalization**: Scale normalization runs once at load time, before caching

### Flexibility

Add new features by creating new components and systems without modifying existing code.

## Data Flow

```mermaid theme={"theme":{"light":"github-light","dark":"css-variables"}}
flowchart TD
    A[Game Tick] --> B[Systems Process]
    B --> C[Query Entities]
    C --> D[Read Components]
    D --> E[Execute Logic]
    E --> F[Update Components]
    F --> G[Sync to Clients]
```

## Working with ECS

### Adding Components

```typescript theme={"theme":{"light":"github-light","dark":"css-variables"}}
// From packages/shared/src/entities/Entity.ts (lines 409-446)
addComponent<T extends Component = Component>(
  type: string,
  data?: Record<string, unknown>,
): T {
  const component = createComponent(type, this, data);
  this.components.set(type, component);
  if (component.init) component.init();
  return component as T;
}
```

### Getting Components

```typescript theme={"theme":{"light":"github-light","dark":"css-variables"}}
// Get component with type safety
const healthComponent = entity.getComponent<HealthComponent>('health');
if (healthComponent?.data) {
  const currentHealth = healthComponent.data.current;
}

// Check if entity has component
if (entity.hasComponent('combat')) {
  // Entity can fight
}
```

### Entity Lifecycle

```typescript theme={"theme":{"light":"github-light","dark":"css-variables"}}
// From packages/shared/src/entities/Entity.ts (lines 40-46)
// Lifecycle:
// 1. Constructor: Creates entity with initial data/config
// 2. spawn(): Called when entity is added to world (override in subclasses)
// 3. update(delta): Called every frame for visual updates
// 4. fixedUpdate(delta): Called at fixed timestep (30 FPS) for physics
// 5. destroy(): Cleanup when entity is removed
```

### Network Synchronization

```typescript theme={"theme":{"light":"github-light","dark":"css-variables"}}
// Mark entity as needing network sync
entity.markNetworkDirty();

// Get data for network transmission
const networkData = entity.getNetworkData();
```

## Key Files

| Location                          | Purpose                  |
| --------------------------------- | ------------------------ |
| `packages/shared/src/entities/`   | Entity class definitions |
| `packages/shared/src/systems/`    | System implementations   |
| `packages/shared/src/components/` | Component definitions    |

## Design Principles

1. **Entities are data containers**—no logic in entity classes
2. **Systems own all behavior**—logic lives in systems
3. **Components are plain objects**—no methods, just data
4. **Use existing systems**—don't create new ones without good reason