Menu
  Log out
 

Hytale Lua API: Custom Entity Spawning Guide

Hytale Guide • Updated Feb 21, 2026

Hytale Lua API: Custom Entity Spawning Guide

One of the most powerful features of the Hytale Early Access build is the native Lua Scripting API. Unlike other sandbox games that require complex Java injection, Hytale allows server administrators to spawn and control entities directly through scripts. This guide covers how to use the World.spawnEntity method for custom gameplay events.

🧬 Component-Based Entities

In Hytale, entities are not just classes—they are collections of components. You can add or remove components (like Health or AITarget) at runtime via Lua.

📍 Coordinate Logic

Hytale uses a double-precision coordinate system. For smooth spawning, ensure your scripts check for isCollisionFree before placing a mob.

Basic Spawning Script

To spawn a basic "Trork" at a specific location, you can use the following snippet in your scripts/main.lua:

-- Hytale Lua Example: Spawning a mob
function onPlayerInteract(player, block)
    local pos = block.getPosition():add(0, 1, 0)
    local trork = World.spawnEntity("hytale:trork_warrior", pos)
    
    trork:setComponent("hytale:display_name", { text = "Scripted Guardian" })
    trork:broadcastMessage("I have been summoned by " .. player:getName())
end

1. Handling "Entity Limits"

Each Hytale dedicated server has a max_scripted_entities limit in the config.json (default 500). If your script exceeds this, the world will stop spawning natural mobs to prevent a server crash. Always implement a "despawn timer" for temporarily summoned entities.

2. Adding Custom AI Behaviors

You can override the default AI behavior pack by passing a JSON object in the Lua call. This allows you to create "Hostile Kweebecs" or "Passive Void Dragons" for your community events.

Admin Tip: Changes made via Lua are Persistent. If you spawn 1000 entities via a script, they will still be there after a server restart unless you manually clear the universe/entities.db file.

Performance and Cleanup

Entity spawning is CPU-intensive during the initialization phase. If you plan to spawn large waves (e.g., for a tower defense mod), use task.yield() between spawns to prevent a server-wide lag spike. At Supercraft, our Hytale servers are optimized for high-thread-count Lua processing, ensuring your scripted events run at a locked 20 TPS.

← Back to Hytale Guides
Top