Hytale Spawning Entities

Hytale Spawning Entities

Use this skill when spawning visible, model-based entities in the world. Covers getting the World, creating entity Holders, attaching models, adding all required components, spawning, and persisting entities across server saves.

Related skills: For ECS fundamentals (Components, Systems, Queries), see hytale-ecs. For invisible text-only entities, see hytale-text-holograms. For NPC spawning helpers, see the Spawning NPCs guide.

Quick Reference

Prerequisites

Familiarize yourself with Hytale's Entity Component System (ECS) before proceeding. See the hytale-ecs skill for full reference.

Your plugin manifest.json must declare these dependencies:

{
  "dependencies": ["Hytale:EntityModule", "Hytale:BlockModule"]
}

Step-by-Step: Spawning an Entity

1. Get the World Object

You can retrieve the World from a player or by UUID:

// From a Player object
World world = player.getWorld();

// From Universe by world UUID
World world = Universe.get().getWorld("your-world-uuid");

2. Get the EntityStore

Store<EntityStore> store = world.getEntityStore().getStore();

3. Execute on World Thread

All entity mutations must run on the world thread. Use world.execute():

world.execute(() -> {
    // All entity creation and spawning code goes here
});

4. Create a Holder

A Holder is a staging buffer — you assemble all components on it, then add the complete entity to the store.

Holder<EntityStore> holder = EntityStore.REGISTRY.newHolder();

5. Get a Model

Look up a model by its asset name (see entity list for available names):

ModelAsset modelAsset = ModelAsset.getAssetMap().getAsset("Minecart");
Model model = Model.createScaledModel(modelAsset, 1.0f);

6. Create a TransformComponent (Position)

Choose one of these approaches:

From a player's current position:

// Get the player's Ref first
Ref<EntityStore> playerRef = /* player's entity ref */;
TransformComponent transform = store.getComponent(
    playerRef.getReference(),
    EntityModule.get().getTransformComponentType()
);

From explicit coordinates:

Vector3d position = new Vector3d(0, 0, 0);   // world position
Vector3f rotation = new Vector3f(0, 0, 0);   // rotation
TransformComponent transform = new TransformComponent(position, rotation);

7. Add Components to the Holder

Add the core visual and identity components:

// Position
holder.addComponent(
    TransformComponent.getComponentType(),
    new TransformComponent(position, new Vector3f(0, 0, 0))
);

// Model (visual appearance)
holder.addComponent(
    PersistentModel.getComponentType(),
    new PersistentModel(model.toReference())
);
holder.addComponent(
    ModelComponent.getComponentType(),
    new ModelComponent(model)
);

// Collision bounds
holder.addComponent(
    BoundingBox.getComponentType(),
    new BoundingBox(model.getBoundingBox())
);

// Network sync (required for clients to see the entity)
holder.addComponent(
    NetworkId.getComponentType(),
    new NetworkId(store.getExternalData().takeNextNetworkId())
);

// Interactions (needed if entity should be interactable)
holder.addComponent(
    Interactions.getComponentType(),
    new Interactions()
);

8. Ensure Required Base Components

Hytale expects certain "default" components on all entities:

holder.ensureComponent(UUIDComponent.getComponentType());
holder.ensureComponent(Interactable.getComponentType()); // if interactable

9. Spawn the Entity

store.addEntity(holder, AddReason.SPAWN);

Complete Example

world.execute(() -> {
    Store<EntityStore> store = world.getEntityStore().getStore();
    Holder<EntityStore> holder = EntityStore.REGISTRY.newHolder();

    // Model
    ModelAsset modelAsset = ModelAsset.getAssetMap().getAsset("Minecart");
    Model model = Model.createScaledModel(modelAsset, 1.0f);

    // Position
    Vector3d position = new Vector3d(100, 65, 200);

    // Add components
    holder.addComponent(
        TransformComponent.getComponentType(),
        new TransformComponent(position, new Vector3f(0, 0, 0))
    );
    holder.addComponent(
        PersistentModel.getComponentType(),
        new PersistentModel(model.toReference())
    );
    holder.addComponent(
        ModelComponent.getComponentType(),
        new ModelComponent(model)
    );
    holder.addComponent(
        BoundingBox.getComponentType(),
        new BoundingBox(model.getBoundingBox())
    );
    holder.addComponent(
        NetworkId.getComponentType(),
        new NetworkId(store.getExternalData().takeNextNetworkId())
    );
    holder.addComponent(
        Interactions.getComponentType(),
        new Interactions()
    );

    // Base components
    holder.ensureComponent(UUIDComponent.getComponentType());
    holder.ensureComponent(Interactable.getComponentType());

    // Spawn
    store.addEntity(holder, AddReason.SPAWN);
});

Required Components Summary

Making Entities Persist

Hytale automatically saves all entities, but NetworkId (required for clients to see the entity) must be re-added every time the entity is loaded from saved data. There are two approaches:

Option A: HolderSystem (Recommended)

Create a system that re-adds NetworkId when entities with your custom component are loaded:

public class AddNetworkIdToMyEntitySystem extends HolderSystem<EntityStore> {

    private final ComponentType<EntityStore, MyEntityComponent> myEntityComponentType =
        MyEntityComponent.getComponentType();
    private final ComponentType<EntityStore, NetworkId> networkIdComponentType =
        NetworkId.getComponentType();
    private final Query<EntityStore> query =
        Query.and(this.myEntityComponentType, Query.not(this.networkIdComponentType));

    @Override
    public void onEntityAdd(
            @NotNull Holder<EntityStore> holder,
            @NotNull AddReason reason,
            @NotNull Store<EntityStore> store) {
        if (!holder.getArchetype().contains(NetworkId.getComponentType())) {
            holder.addComponent(
                NetworkId.getComponentType(),
                new NetworkId(store.getExternalData().takeNextNetworkId())
            );
        }
    }

    @Override
    public void onEntityRemoved(
            @NotNull Holder<EntityStore> holder,
            @NotNull RemoveReason reason,
            @NotNull Store<EntityStore> store) {
        // No-op
    }

    @Override
    public @Nullable Query<EntityStore> getQuery() {
        return query;
    }
}

Register the system in your plugin's setup():

this.getEntityStoreRegistry().registerSystem(new AddNetworkIdToMyEntitySystem());

Option B: PropComponent

Add PropComponent to your entity. Hytale uses this for entities spawned with the Entity Tool — it automatically gets NetworkId and PrefabCopyableComponent on load.

holder.addComponent(PropComponent.getComponentType(), new PropComponent());

Warning: Hytale may add additional behavior to PropComponent in future versions. This could cause unexpected side effects. The HolderSystem approach is safer for custom entities.

Key Points

1. World Thread Required — All entity creation/mutation must run inside world.execute(() -> { ... })
2. NetworkId Required — Without it, clients cannot see the entity
3. UUIDComponent Required — Provides unique entity identity; use ensureComponent to auto-generate
4. Model Lookup — Use ModelAsset.getAssetMap().getAsset("Name") to find existing entity models
5. Persistence — NetworkId must be re-added on every load; use a HolderSystem or PropComponent
6. Holder Pattern — Always stage all components on a Holder before calling store.addEntity()

Troubleshooting

Reference

• Source: Hytale Modding — Spawning Entities Guide
• Related: Spawning NPCs
• Related: Entity List