Hytale ECS for Modders: A Code-Level Guide to Components, Systems, and Codecs — and the Update 6 Part 3 NPC Migration

If you maintain custom NPCs, the clock started Thursday. The Update 6 Part 3 patch notes that landed on June 11, 2026 carried a genuinely breaking change: NPC support objects — combat, state, and world — are no longer fields on Role and NPCEntity. They are now ECS components. Behavior methods receive a Ref<EntityStore> plus ExecutionSupport, and NPCEntity.getAlarmStore() is deprecated because AlarmStore is now a component too. To do that migration well, you have to actually understand the engine's hytale entity component system — not just pattern-match your way through compiler errors. This hytale ecs tutorial walks the fundamentals and the exact API you need to write your first component and system. One honest caveat up front: this is community-documented Early-Access API, sourced from the official-community docs at hytale-docs.pages.dev and hytalemodding.dev. It is real, but it is moving. Class names and signatures will shift between pre-release builds. Treat everything here as the shape of the system, verify against current docs before you ship, and expect the NPC-specific surface to keep changing across the Update 6 cycle. What ECS Is and Why Hytale Uses It An Entity Component System is a way of structuring game state around composition instead of inheritance. Instead of a deep class tree — Entity → LivingEntity → Mob → NPC → Guard — you have plain entities that are nothing more than an ID, plus components that are pure data, plus systems that contain the behavior. A guard is not a subclass; it is an entity that happens to have a HealthComponent, a PositionComponent, and an AlarmStore attached. Want a poisoned guard? Add a PoisonComponent. You compose behavior by attaching data, not by carving out new classes. The performance argument is the other half. Hytale's Early-Access server runs a custom in-house ECS on the Java engine — not FLECS; the C++/FLECS cross-platform rewrite was paused, so EA ships on the Java/"Legacy" engine. Components of the same shape are grouped into archetypes, and stored in contiguous ArchetypeChunk blocks. When a system iterates every entity that has both Health and Poison, it walks tightly packed memory rather than chasing pointers across a scattered object graph. That cache-friendly layout is why ECS scales to thousands of entities ticking every frame. The storage abstraction is Store<ECS_TYPE>, and on the server that store is the EntityStore. This also reflects Hytale's stated design philosophy: "build Hytale within Hytale." The studio's own developers use the same ECS, the same component model, and the same plugin tools they ship to modders. When NPC support objects migrate to components, that is not a modder-only chore — it is the engine team eating their own dog food. And because all of this is server-authoritative, it is anti-cheat by design: the client is compiled C#, not moddable, and the server streams required assets to it on join, so there is nothing for a player to tamper with locally. Defining Your First Component A component is data. In Hytale's API a component implements Component<EntityStore>, and its type handle is a ComponentType<EntityStore, T>. Here is the canonical hytale component example — a poison effect that ticks damage over time. Conceptually, your PoisonComponent implements Component<EntityStore> holds a couple of fields — say int ticksRemaining and float damagePerTick — and that is it. No methods that mutate the world, no behavior. It is a bag of plain values describing "this entity is poisoned, this badly, for this long." Pair it with an existing HealthComponent that holds float current and float max, and you have the two halves of a classic damage-over-time effect, expressed as pure data. Every component that needs to persist — survive a save/load or get serialized across the network — needs a codec. Hytale exposes BuilderCodec and KeyedCodec for this. The codec describes how each field is written and read, keyed by name, so the engine can round-trip your component to disk and back. A purely transient component (something you add and remove within a single tick) can skip persistence, but anything that should still be there after a restart needs its codec wired up. This is the single step most first-time ECS modders forget, and the symptom is always the same: your effect works until the chunk unloads, then vanishes. Registering the Component in setup() Components must be registered before the engine knows they exist. Hytale plugin development centers on extending JavaPlugin, which exposes a setup() lifecycle phase — that is where registration belongs. You fetch the registry and register the component type, handing over its codec. Inside setup() you call getEntityStoreRegistry().registerComponent(...), passing the component class and its codec. The call hands you back the ComponentType<EntityStore, PoisonComponent> handle, which you cache on your plugin — every later query, add, and remove references that handle, not the class directly. Registration in setup() guarantees your component type exists before any world loads or any system ticks, which is exactly the ordering you want. Skip it, or do it too late, and adds will fail because the store has no archetype slot for a type it has never been told about. Writing a System Behavior lives in systems. The base abstractions are TickingSystem, EntityTickingSystem, and ArchetypeTickingSystem. For most gameplay logic you want EntityTickingSystem (per-entity tick) or ArchetypeTickingSystem (you iterate whole chunks yourself for maximum throughput). Each runs its work inside a tick() method. A system declares which entities it cares about through a query. Queries compose with Query.and, Query.or, Query.not, and Query.any. Our poison system wants every entity that has both poison and health, so the query is conceptually Query.and(PoisonType, HealthType) — and you might add Query.not(InvulnerableType) to skip protected entities. Each tick, the engine narrows the world to exactly the matching entities and hands them to your tick(), where you read the PoisonComponent, subtract damagePerTick from the HealthComponent, and decrement ticksRemaining. Because the query is backed by archetypes, iteration only ever touches entities that genuinely match — no scanning, no instanceof checks. Mutating Safely with CommandBuffer Here is the rule that trips up everyone coming from object-oriented game code: you do not mutate the store mid-iteration. If your poison system decides an entity's poison has run out and the PoisonComponent should be removed — or the entity should be deleted entirely — you cannot remove it on the spot, because that would reshuffle the very archetype chunk you are walking. Doing so corrupts iteration. Instead you queue the change on a CommandBuffer. The buffer collects your intended structural changes — add a component, remove a component, removeEntity — and the engine applies them at a safe point after the tick completes. So the pattern is: read and mutate component fields freely during the tick (adjusting health, decrementing the timer), but route any structural change (adding/removing components, destroying entities) through the CommandBuffer. Internalize that split and most of the mysterious ECS crashes simply never happen. Archetypes, Chunks, and System Ordering You mostly do not manage archetypes by hand — the store assigns each entity to an archetype based on its exact set of components, and moving an entity between archetypes is precisely what adding or removing a component does. But understanding the model explains the performance rules: prefer small, focused components; query for the components you actually use; and reach for ArchetypeTickingSystem when you want to iterate ArchetypeChunk data contiguously for hot loops. Ref<> entity references carry an isValid() check precisely because an entity you held a reference to last tick may have been destroyed via a CommandBuffer this tick — always validate before dereferencing a stored ref. When systems depend on each other, order them explicitly. SystemDependency with Order.BEFORE or Order.AFTER lets you say "run my damage system before the death-cleanup system." Relying on registration order is fragile; declaring dependencies is how you keep a multi-system mod deterministic. Connecting It Back to the Part 3 NPC Migration Now the migration makes sense. Before Part 3, NPC support objects hung off Role and NPCEntity as fields, and you read them directly. After Part 3, those combat, state, and world support objects are ECS components living in the EntityStore — so behavior methods now receive a Ref<EntityStore> (the validated handle to the store) and an ExecutionSupport object, and you pull what you need through them instead of off the entity. AlarmStore followed the same path: it is now a component, which is why NPCEntity.getAlarmStore() is deprecated. Everything in this guide — registering a component, querying it, mutating through a CommandBuffer — is exactly the muscle you exercise to rebuild your custom sensors, actions, motions, and behaviors against the new pattern. If you are catching up on the broader picture, our modding API and server plugin development guide walks the plugin lifecycle end to end, and the deeper rationale for why none of this ships client-side lives in our breakdown of Hytale's server-side modding architecture. Together they frame why the hytale modding api is built the way it is: server-authoritative, component-driven, and shared between the studio and the modders who run hytale server mods in production. What Modders Should Do This Week The migration is the priority, and the timeline is now. Here is the practical checklist: Read the support objects as components. Audit every place your NPC code touched a support object off Role or NPCEntity and rewrite it to go through the Ref<EntityStore> and ExecutionSupport your behavior methods now receive. Anything still calling NPCEntity.getAlarmStore() needs to move to the AlarmStore component. Write one trivial component first. Before touching production NPCs, build a throwaway PoisonComponent-style effect: define it, give it a BuilderCodec, register it in setup(), query it in an EntityTickingSystem, and remove it via a CommandBuffer. Getting that round-trip working — including persistence across a chunk reload — teaches the API faster than any amount of reading. Wire up codecs for anything persistent. If a migrated NPC support object needs to survive a save, confirm it has a working codec. This is the most common silent failure. Order your systems explicitly. Use SystemDependency rather than trusting registration order, especially where damage, state, and cleanup systems interact. Keep your listing sharp. Pre-release weeks are when curious players go hunting for active, well-run servers to try the new build on. Make sure your HytaleCharts server listing is current — banner up to date, heartbeat reporting live player counts, description clear — so the players looking for somewhere to land choose you. The shift from inheritance to components is the defining move of modern Hytale modding, and Part 3 made it unavoidable for anyone who builds NPCs. Learn the hytale ecs model once — components as data, systems as behavior, CommandBuffer for safe mutation, archetypes for speed — and the rest of the hytale plugin development surface stops feeling like a maze. Migrate your NPC content this week, verify it against the current docs because this Early-Access API will keep moving, and you will be ready for whatever the next pre-release Thursday brings. For more guides and the live server scene, Hytale Charts is where to keep watching.