Code Patterns

Archetypes group entities with the same component signature for cache-efficient iteration. Entities with components [A,B] are stored together, separate from [A,B,C]. This enables fast system processing.

EntityEventSystem implementation

Efficiently iterate over all entities with a specific component using forEachChunk for cache-friendly access.

ComponentType<T> provides type-safe access to components. Every component class has a static getComponentType() method that returns its ComponentType for Store operations.

Custom EntityStore component

Create custom ECS components with data and clone support.

Define custom ECS components with proper clone support and optional serialization.

Handle ECS events like crafting, block breaking, damage using EntityEventSystem.

Entity Component System (ECS) architecture overview for Hytale modding. ECS separates data (Components) from logic (Systems), with Entities being just IDs that group components together.

Understanding why Hytale uses ECS instead of traditional OOP. ECS avoids inheritance problems and enables better performance through data-oriented design.

Create new entities using Holder blueprint pattern. Collect all components first, then add to store.

EntityTickingSystem processes entities every tick (frame). It receives an index into an ArchetypeChunk for efficient iteration. Use for per-entity per-frame logic like movement, AI, or HUD updates.

Custom EntityStore component

RefSystem implementation

Holder<EntityStore> wraps an entity reference with convenient component access methods. Created from ArchetypeChunk index using EntityUtils.toHolder().

EntityTickingSystem implementation

EntityTickingSystem implementation

Custom EntityStore component

Create marker components (boolean flags) using singleton pattern for entities without data.

EntityEventSystem implementation

Custom EntityStore component

EntityTickingSystem implementation

Always validate entity references before use since entities can be deleted at any time.

React to entity creation and removal events.

The Store<EntityStore> and Ref<EntityStore> pattern is the core way to access entity components in Hytale ECS. Store is your accessor, Ref identifies which entity.

Create systems that run every game tick with query filtering.

Hytale world structure: Universe contains multiple Worlds, each World has an EntityStore. The Universe represents the entire game session, Worlds are individual dimensions/areas.