Hytale Entity Component System (ECS)

Master Hytale’s ECS architecture for performant game mechanics.

What is ECS?

ECS is an architectural pattern that separates:

• Entity: A unique identifier (just an ID)
• Component: Pure data (no logic)
• System: Pure logic (no data)

This enables:

• ✅ Better performance (cache-friendly)
• ✅ Easier composition (mix and match)
• ✅ Cleaner code (separation of concerns)

Core Concepts

Entity

An entity is just an ID – a number that groups components together.

// Entity has no data or behavior itself
Entity player = world.createEntity();
Entity monster = world.createEntity();

Component

Components are data containers – they describe what an entity “has”.

// Components are pure data
public record PositionComponent(float x, float y, float z) {}

public record HealthComponent(float current, float max) {}

public record VelocityComponent(float vx, float vy, float vz) {}

public record NameComponent(String name) {}

System

Systems contain logic – they operate on entities with specific components.

// Systems process entities with required components
public class MovementSystem implements System {
    @Override
    public void update(World world, float deltaTime) {
        // Query all entities with Position AND Velocity
        world.query(PositionComponent.class, VelocityComponent.class)
            .forEach((entity, pos, vel) -> {
                // Update position based on velocity
                entity.setComponent(new PositionComponent(
                    pos.x() + vel.vx() * deltaTime,
                    pos.y() + vel.vy() * deltaTime,
                    pos.z() + vel.vz() * deltaTime
                ));
            });
    }
}

Composition Over Inheritance

❌ Traditional OOP (Inheritance)

       Entity
         │
    ┌────┴────┐
    │         │
 Character  Item
    │
┌───┴───┐
│       │
Player  NPC

Problem: What if NPC needs inventory like Player?

✅ ECS (Composition)

Player Entity:
  + PositionComponent
  + HealthComponent
  + InventoryComponent
  + PlayerControllerComponent

NPC Entity:
  + PositionComponent
  + HealthComponent
  + InventoryComponent  ← Easy to add!
  + AIControllerComponent

Item Entity:
  + PositionComponent
  + ItemDataComponent

Working with Components

Adding Components

Entity player = world.createEntity();

player.addComponent(new PositionComponent(0, 64, 0));
player.addComponent(new HealthComponent(100, 100));
player.addComponent(new InventoryComponent());

Getting Components

// Get single component
var health = entity.getComponent(HealthComponent.class);
if (health != null) {
    float current = health.current();
}

// Check if has component
if (entity.hasComponent(FlyingComponent.class)) {
    // Handle flying entity
}

// Optional API
entity.getComponentOptional(HealthComponent.class)
    .ifPresent(h -> h.heal(10));

Removing Components

// Remove a component
entity.removeComponent(FlyingComponent.class);

// Entity becomes "different" without that component
// Systems that require FlyingComponent will skip it

Entity Queries

Query entities based on their components:

// All entities with Health
world.query(HealthComponent.class)
    .forEach((entity, health) -> {
        if (health.current() <= 0) {
            entity.destroy();
        }
    });

// All entities with Position AND Velocity AND NOT Flying
world.query()
    .with(PositionComponent.class)
    .with(VelocityComponent.class)
    .without(FlyingComponent.class)
    .forEach((entity, pos, vel) -> {
        // Apply gravity
    });

Common Component Patterns

Transform Components

public record PositionComponent(float x, float y, float z) {}
public record RotationComponent(float pitch, float yaw, float roll) {}
public record ScaleComponent(float x, float y, float z) {}

Gameplay Components

public record HealthComponent(float current, float max) {
    public boolean isDead() { return current <= 0; }
}

public record DamageComponent(float amount, Entity source) {}

public record InventoryComponent(List<ItemStack> items) {}

AI Components

public record AITargetComponent(Entity target) {}
public record PatrolRouteComponent(List<Position> waypoints) {}
public record AggroRangeComponent(float range) {}

Tags (Empty Components)

// Tag components have no data
public record PlayerTag() {}
public record HostileTag() {}
public record InvulnerableTag() {}

// Use for filtering
world.query(PlayerTag.class, HealthComponent.class)
    .forEach((entity, _, health) -> {
        // Only players with health
    });

System Design

System Interface

public interface System {
    void update(World world, float deltaTime);
    
    default int priority() { return 0; }  // Lower = runs first
}

Example Systems

public class GravitySystem implements System {
    @Override
    public void update(World world, float deltaTime) {
        world.query(VelocityComponent.class)
            .without(FlyingComponent.class)
            .forEach((entity, vel) -> {
                entity.setComponent(new VelocityComponent(
                    vel.vx(),
                    vel.vy() - 9.8f * deltaTime,  // Apply gravity
                    vel.vz()
                ));
            });
    }
    
    @Override
    public int priority() { return 10; }  // Run early
}

public class DamageSystem implements System {
    @Override
    public void update(World world, float deltaTime) {
        world.query(HealthComponent.class, DamageComponent.class)
            .forEach((entity, health, damage) -> {
                float newHealth = health.current() - damage.amount();
                entity.setComponent(new HealthComponent(newHealth, health.max()));
                entity.removeComponent(DamageComponent.class);
            });
    }
}

Best Practices

Do

Don’t

Quick Reference

Resources

• Hytale API: See hytale-plugin-dev skill
• Java Features: See java-25-hytale for records/patterns