Custom Scripts and Modding in Hytale

Hytale was built from the ground up with modding in mind. Unlike many games where modding is an afterthought, Hytale provides an integrated scripting engine and content creation pipeline that makes it possible to modify virtually every aspect of the game. This guide introduces the fundamentals of Hytale’s scripting and modding system for server owners on Witchly.host.

Overview of Hytale’s Modding Architecture

Hytale’s modding system is built around several core concepts:

Scripting Engine — A built-in scripting runtime that allows you to write custom game logic, events, and behaviors
Hytale Model Maker — A 3D modeling tool for creating custom models, animations, and visual effects
Data-Driven Configuration — JSON-based definition files for items, blocks, creatures, and other game objects
Asset Pipeline — A system for loading custom textures, sounds, and other assets into the game

These systems work together, allowing you to create anything from simple gameplay tweaks to entirely new game modes.

Getting Started with Scripting

Hytale’s scripting system uses a familiar programming approach that is accessible to both beginners and experienced developers.

Setting up your scripting environment:

Log in to Dashboard and select your Hytale server
Navigate to the Files tab
Locate or create a scripts directory in your server’s root folder
Script files use the appropriate extension based on Hytale’s scripting language

Your first script — a welcome message:

// welcome.js — Greets players when they join the server

onPlayerJoin(function(player) {
    player.sendMessage("Welcome to the server, " + player.name + "!");
    player.sendMessage("Type /help for a list of commands.");

    // Log the join event
    server.log(player.name + " joined the server.");
});

To install this script:

Create the file in your scripts directory using the Files tab or SFTP (port 2022)
Restart your server
The script will execute automatically when players join

Core Scripting Concepts

Events: The foundation of Hytale scripting. Events fire when specific things happen in the game, and your scripts respond to them.

Common events include:

onPlayerJoin / onPlayerLeave — Player connection events
onPlayerChat — Chat message events
onBlockBreak / onBlockPlace — Block interaction events
onEntitySpawn / onEntityDeath — Entity lifecycle events
onPlayerDamage — Combat and damage events
onServerTick — Runs every server tick (use sparingly to avoid performance issues)

Game Objects: Scripts can interact with players, entities, blocks, items, and the world itself.

// Example: Create a custom item drop when breaking a specific block
onBlockBreak(function(event) {
    if (event.block.type === "ancient_stone") {
        // 25% chance to drop a rare gem
        if (Math.random() < 0.25) {
            world.spawnItem("rare_gem", event.position);
            event.player.sendMessage("You found a rare gem!");
        }
    }
});

Timers and Scheduling:

// Broadcast a message every 10 minutes (600 seconds)
server.scheduleRepeating(600, function() {
    server.broadcast("Remember to check out /shop for daily deals!");
});

Creating Custom Content with Data Files

Hytale uses JSON definition files to describe game objects. You can create new items, blocks, and creatures by adding definition files to the appropriate directories.

Custom item definition:

{
    "identifier": "magic_sword",
    "display_name": "Enchanted Blade",
    "type": "weapon",
    "category": "melee",
    "damage": 12,
    "attack_speed": 1.4,
    "durability": 500,
    "rarity": "rare",
    "texture": "items/magic_sword.png",
    "lore": "A blade imbued with ancient magic."
}

Place item definitions in the content/items/ directory and their corresponding textures in the appropriate assets folder.

Custom block definition:

{
    "identifier": "crystal_ore",
    "display_name": "Crystal Ore",
    "hardness": 4.0,
    "tool_type": "pickaxe",
    "min_tool_tier": 2,
    "drops": [
        {
            "item": "crystal_shard",
            "count_min": 1,
            "count_max": 3
        }
    ],
    "texture": {
        "all": "blocks/crystal_ore.png"
    },
    "light_emission": 5
}

Custom Creatures and NPCs

Creating custom creatures involves defining their behavior, appearance, and stats:

{
    "identifier": "forest_guardian",
    "display_name": "Forest Guardian",
    "health": 80,
    "damage": 6,
    "speed": 0.3,
    "hostile": false,
    "behavior": "neutral_territorial",
    "spawn_biomes": ["forest", "ancient_forest"],
    "spawn_weight": 5,
    "drops": [
        {
            "item": "guardian_essence",
            "chance": 0.5
        }
    ],
    "model": "creatures/forest_guardian.hym"
}

Creature models can be created using Hytale Model Maker and exported for server use.

Script Organization and Best Practices

Directory structure for a well-organized mod:

mods/
  my-custom-mod/
    scripts/
      main.js
      commands.js
      events.js
    content/
      items/
      blocks/
      creatures/
    assets/
      textures/
      sounds/
      models/
    mod.json

The mod.json manifest:

{
    "name": "My Custom Mod",
    "version": "1.0.0",
    "author": "YourName",
    "description": "A custom mod for our Hytale server",
    "entry_point": "scripts/main.js",
    "dependencies": []
}

Performance Considerations

Custom scripts run on your server, so poorly optimized code can impact performance. Keep these guidelines in mind:

Avoid heavy logic in tick events — Code that runs every server tick (20 times per second) must be lightweight. Use scheduling for periodic tasks instead.
Cache data when possible — Avoid repeatedly querying the same information. Store frequently accessed data in variables.
Limit entity searches — Searching for entities in large areas is expensive. Use targeted searches with reasonable radius limits.
Profile your scripts — Monitor your server’s TPS after adding scripts. If performance drops, review your code for bottlenecks.
Clean up after yourself — Remove event listeners and cancel timers when they are no longer needed.

Plan recommendations for scripted servers:

Simple scripts (welcome messages, chat commands): The Scout (4 GB) is sufficient
Moderate scripting (custom game mechanics, NPCs): The Explorer (8 GB) recommended
Heavy scripting (custom game modes, complex systems): The Creator (16 GB) recommended

Testing and Debugging

Console logging:

Use server.log() to output debug information to the console, which you can view in the Console tab at Dashboard.

server.log("[DEBUG] Player " + player.name + " triggered event at " + event.position);

Testing workflow:

Write or modify your script
Upload it to the server via the Files tab or SFTP
Restart the server (or use reload if supported)
Test the feature in-game
Check the console for errors or debug output
Iterate until the behavior is correct

Once you have built custom content for your Hytale server, consider sharing it with the community:

Package your mod with clear documentation and a mod.json manifest
Share on community mod repositories or forums
Contribute to open-source projects on GitHub
Showcase your work in Discord

Resources

Hytale Modding Documentation — Official documentation from Hypixel Studios
Community Forums — Connect with other modders for help and inspiration
Witchly Discord — Our community at Discord has channels dedicated to modding discussion and support

Need help with your custom scripts? Our team and community are available on Discord.