Hytale Modding Tutorial: How to Create Your First Hytale Mod

Hytale launched into Early Access on January 13, 2026, and within weeks players had downloaded more than 20 million mods across 5,000+ creations on CurseForge [9]. The community didn’t wait around.

The good news: you don’t need to be an experienced programmer to join in. Hytale’s modding system splits into two very different tracks — one that requires zero code, and one that uses Java — and you can build genuinely impressive content without ever touching a programming language. This guide walks you through both paths, from your very first folder structure to publishing on CurseForge.

One quick note before we start: Hytale is in Early Access, which means the modding API and documentation can change between updates. The information below is current as of March 2026 — always check the HytaleModding Discord and official docs after major game updates.

The Three Types of Hytale Mods

Before you open a single file, it helps to understand what kind of mod you’re actually making. According to CurseForge’s official Hytale modding documentation, mods split into three categories [1]:

Packs are the no-code option. They’re asset and content packs — new blocks, items, furniture, creatures, and behaviour changes. Everything in a Pack is driven by JSON files and image textures. No programming required. This is where you’ll start if you’ve never written a line of code, and honestly, you can build impressive stuff here.

Plugins are where Java comes in. Plugins use Hytale’s Java API to extend and modify core game functionality — custom game modes, economy systems, combat mechanics, server-side logic. If you want to build something Packs can’t express, Plugins are the tool [1].

Early Plugins (also called Bootstrap Plugins) operate outside the standard plugin environment and make low-level bytecode alterations. Unless you’re an experienced Java developer with a very specific reason to be here, skip this tier entirely [1].

This guide focuses on Packs first — the right starting point for most players — then covers Plugin environment setup if you want to go further.

Your First Pack Mod: Adding a Decorative Block

Walk through this with me. By the end of this section, you’ll have a working custom block running inside Hytale. All you need is a text editor and an image editor — even Paint works for the textures.

What You Need

• Hytale (Early Access) installed on your PC
• A text editor — VS Code is free and excellent for editing JSON files
• An image editor that saves PNG files (GIMP, Aseprite, or just Paint)
• About 20 minutes

Step 1: Create Your Pack Folder Structure

Navigate to this folder on Windows [2]:

C:\Users\YourName\AppData\Roaming\Hytale\UserData\Mods\

Create a new folder inside Mods\ — this is your Pack. Name it something descriptive with no spaces, like MyFirstBlock. Inside it, create this structure:

MyFirstBlock/
  manifest.json
  Common/
    BlockTextures/
      my_block.png
    Icons/
      ItemsGenerated/
        my_block.png
  Server/
    Item/
      Items/
        my_block.json
    Languages/
      en-US/
        server.lang

The Common/ folder holds visual assets — textures and icons. The Server/ folder holds the functional definitions — what your block actually is.

Step 2: Write the manifest.json

The manifest.json lives in your Pack’s root folder and tells Hytale everything it needs to know about your mod [2]. Create it with this content:

{
  "Group": "YourName",
  "Name": "My First Block",
  "Version": "1.0.0",
  "Description": "A custom decorative block - my first Hytale mod.",
  "Authors": [
    {
      "Name": "YourName",
      "Email": "your@email.com",
      "Url": ""
    }
  ],
  "ServerVersion": "*"
}

The fields that matter most:

Step 3: Define Your Block

Create my_block.json inside Server/Item/Items/. This file defines everything about your block — its texture, physical properties, sound effects, and inventory behaviour [3]:

{
  "TranslationProperties": {
    "Name": "server.my_block.name"
  },
  "MaxStack": 100,
  "Icon": "Icons/ItemsGenerated/my_block.png",
  "Categories": ["Blocks.Rocks"],
  "PlayerAnimationsId": "Block",
  "BlockType": {
    "Material": "Solid",
    "DrawType": "Cube",
    "Group": "Stone",
    "Textures": [
      {
        "All": "BlockTextures/my_block.png"
      }
    ],
    "ParticleColor": "#a0a08a",
    "BlockSoundSetId": "Stone",
    "BlockBreakingDecalId": "Breaking_Decals_Rock"
  }
}

Want different textures on the top, bottom, and sides — like a wooden plank or log? Replace the Textures array with this [3]:

"Textures": [
  {
    "Top": "BlockTextures/my_block_top.png",
    "Bottom": "BlockTextures/my_block_bottom.png",
    "Sides": "BlockTextures/my_block_side.png"
  }
]

Step 4: Add Your Texture

Create a 16×16 PNG image for your block. Save it at both locations [3]:

• Common/BlockTextures/my_block.png — applied to the block’s faces in the world
• Common/Icons/ItemsGenerated/my_block.png — the inventory icon (can be the exact same file)

Filenames must exactly match what you typed in the JSON. Case matters — My_Block.png and my_block.png are treated as different files.

Step 5: Add the Display Name

Create server.lang inside Server/Languages/en-US/:

my_block.name = My Decorative Block

Notice the server. prefix is dropped here. The block JSON uses server.my_block.name as the translation key, but the lang file just needs my_block.name = Your Display Name. That’s your complete Pack mod — five files, zero code.

Using the Asset Editor (The Truly No-Code Route)

If file structures and JSON feel overwhelming, the Asset Editor is Hytale’s built-in creation tool — and it handles all that scaffolding for you automatically [1][2]. Here’s how to access it:

1. Launch Hytale and create a Creative World
2. Once inside, run /op self in chat to give yourself full permissions
3. Open your Inventory
4. Navigate to Creative Tools → Assets → Asset Editor
5. Click the three-dot menu in the top-left corner
6. Select Add Pack
7. Fill in your Pack’s name and description — Hytale creates the entire folder structure automatically

From here, you can add blocks, items, and mobs through the editor’s visual interface and preview texture changes in real-time inside the game world. The Asset Editor is the fastest way to iterate — change a texture, see it update instantly, adjust, move on.

That said, understanding the underlying file structure is worth the hour it takes. When something eventually breaks (and at some point it will), being able to open the JSON directly will save you a lot of frustrated searching.

Setting Up a Plugin Development Environment

Once you’ve built a Pack or two and you’re thinking I want to do more, Plugins are the next step. This section assumes you’re comfortable with basic programming concepts — variables, classes, methods. You don’t need to be a Java expert, but you need to be comfortable learning from code examples.

What You Need

• Java 25 JDK — mandatory; earlier versions are not compatible with the Hytale Plugin API [4]
• IntelliJ IDEA Community Edition — free and the officially recommended IDE [4]
• The Hytale Plugin Template from the HytaleModding GitHub (created by Darkhax & Jared) — link in the Resources section

Setup Steps

1. Download and install Java 25 JDK from jdk.java.net
2. Download IntelliJ IDEA Community Edition — the free version is all you need
3. Clone the Hytale Plugin Template from the HytaleModding GitHub (link in Resources below)
4. Open the template in IntelliJ — it comes pre-configured with Gradle [4]
5. Go to File → Project Structure → Project and set the SDK to Java 25

Your basic Plugin class looks like this [4]:

public class MyPlugin extends JavaPlugin {
    public MyPlugin(@Nonnull JavaPluginInit init) {
        super(init);
        getLogger().info("MyPlugin has been loaded!");
    }

    @Override
    public void onEnable() {
        getLogger().info("MyPlugin enabled!");
    }

    @Override
    public void onDisable() {
        getLogger().info("MyPlugin disabled!");
    }
}

Build your Plugin with ./gradlew build in the terminal (or via the Gradle panel in IntelliJ under Tasks → build → build). This produces a .jar file you drop into your Hytale mods folder alongside your Packs.

The Plugin API is designed to be explored through IntelliJ’s autocomplete — start browsing the included dependencies and you’ll find every game system exposed. As noted in the Hytale Modding Documentation, the Hytale Technical Director has confirmed: "We’re building Hytale with modding at its core. Most of what you see in the game can be changed, extended, or removed entirely." [7]

Testing Your Mod in Single Player

Before sharing anything publicly, always test locally first. Here’s the full workflow [2][8]:

1. Confirm your mod folder is inside AppData\Roaming\Hytale\UserData\Mods\
2. Launch Hytale and go to Worlds
3. Right-click your world (or create a new one) and click the settings cog
4. Find your mod in the list, toggle it on, then hit Save world settings
5. Enter the world — your custom block will appear under the Creative Tools tab in your inventory

For Plugin mods, install the Better Modlist mod from CurseForge and run /modlist in-game. It shows every active mod and confirms your Plugin loaded without errors [6].

Common issues when your first mod doesn’t work:

Publishing Your Mod to CurseForge

Once local testing confirms everything works, CurseForge is where the Hytale modding community lives. There are already 5,000+ mods and 20 million downloads on the platform since Early Access launched in January 2026 [9]. Here’s how to publish [8]:

1. Create a CurseForge Mod Author account at curseforge.com
2. Go to the Hytale section and click Upload a Project
3. Give your mod a name and description, then choose the right category (Blocks, Gameplay, World Generation, etc.)
4. Upload your file — a .zip of your Pack folder, or a .jar for Plugins
5. Tag your supported game versions and click Submit

One of the best things about Hytale modding compared to Minecraft: Hytale uses a server-side-first architecture [6]. When a player joins your modded world, the game automatically syncs all your mod’s assets to their client. Nobody has to manually install anything — your mod reaches players the instant they connect, with zero friction on their end.

The New Worlds Contest: Win Up to $10,000

If you’re building a mod right now, this is worth knowing about: Hypixel Studios and CurseForge have launched the Hytale New Worlds Modding Contest with $100,000 in prizes across 65 winners [5].

Prize Structure Per Category

There are three main categories to enter [5]:

• WorldGen V2 — Build a new biome, region, or world using Hytale’s visual node editor
• NPCs — Create new critters, enemies, or boss fights
• Experiences — Build adventure maps, minigames, or custom gameplay systems

Key dates:

• Submissions open: March 3, 2026
• Submissions close: April 28, 2026
• Finalists announced / voting opens: May 5, 2026
• Winners announced: May 12, 2026

The contest is open worldwide to anyone with a CurseForge account. Teams can enter together, and you can submit to multiple categories. One important restriction: AI-generated visual assets are prohibited [5] — all textures, models, and artwork must be human-made. You can use AI tools for planning and ideation, but not for the visuals themselves.

To enter: upload your project to CurseForge, then complete the official submission form on the contest page. Your Pack mod qualifies — you don’t need to write a single line of Java to compete.

Modding Resources and Community

You don’t have to figure this out alone. The Hytale modding community is one of the most active in the indie gaming space right now, and the official resources are genuinely well-maintained.

• HytaleModding Documentation — Community-maintained comprehensive guides covering Packs, Plugins, server administration, and tools. Maintained in partnership with Hytale Creators and updated regularly.
• HytaleModding GitHub — The Plugin Template repository (what you need for Plugin development), community tools, and open-source mod examples.
• HytaleModding Discord — discord.gg/hytalemodding — 9,600+ members, active help channels, mod showcases, and community feedback.
• Official Hytale Discord — discord.gg/hytale — 567,000+ members, official announcements, patch notes, and direct developer interaction.

The technical documentation used in this guide — Getting Started with Packs, Adding a Block, and Getting Started with Plugins — are all linked in the Sources section below.

For more Hytale game mechanics, our Hytale Teleporter Guide covers the in-game network infrastructure in detail — useful context once you start building server-side mods.

Frequently Asked Questions

Do I need to know how to code to mod Hytale?
No — not for Pack mods. Everything in a Pack is driven by JSON files and PNG textures, and the Asset Editor removes even that barrier for most visual work. Java is only required if you want to create Plugins [1].

What version of Java is required for Plugin development?
Java 25, specifically. Earlier versions are not compatible with the Hytale Plugin API — this is a hard requirement, not a recommendation [4].

Won’t my mod break when Hytale updates?
Possibly — Hytale is in Early Access, which means the API and Pack structure can change between versions. The ServerVersion field in your manifest.json helps indicate compatibility. Check the HytaleModding Discord after major updates; the community typically documents breaking changes within hours.

Do players need to manually install my mod to join my world?
No. Hytale’s server-side-first architecture syncs mod assets automatically when players join your modded world. They don’t need to download or install anything on their end [6].

Can I use the Asset Editor for Plugin development too?
No — the Asset Editor is designed exclusively for Pack mods. Plugin development happens entirely in Java using IntelliJ IDEA and the Gradle build system [1][4].

Can I enter the New Worlds contest with a basic Pack mod?
Yes. All three contest categories — WorldGen V2, NPCs, and Experiences — are achievable with Pack mods using Hytale’s content creation tools. You don’t need to write Java to be eligible [5].

Conclusion

Hytale hit 20 million mod downloads in its opening weeks, and the momentum shows no sign of slowing. Between Pack mods that require zero code, a built-in Asset Editor, a proper Java API for developers, and a $100,000 contest closing April 28 — there’s never been a better time to start building.

If this is your first mod ever, start with the Pack tutorial in this guide: get a custom block running in your world today. The folder structure and JSON look intimidating on first read, but once you’ve done it once, you’ll see exactly how the system fits together. From there, the Asset Editor makes iteration fast. If you’re already comfortable with Java, jump straight to the Plugin Template and start exploring the API through IntelliJ’s autocomplete.

Sources

• CurseForge Support. Hytale Modding. CurseForge. [1]
• Britakee Studios / Hytale Creators. Getting Started with Packs. Hytale Modding Documentation. [2]
• Britakee Studios / Hytale Creators. Adding a Block. Hytale Modding Documentation. [3]
• Britakee Studios / Hytale Creators. Getting Started with Plugins. Hytale Modding Documentation. [4]
• CurseForge / Hypixel Studios. Hytale New Worlds Modding Contest. CurseForge. [5]
• CurseForge Blog. How to Install Mods for Hytale. CurseForge. [6]
• Britakee Studios / Hytale Creators. Hytale Modding Documentation Overview. Hytale Creators. [7]
• CurseForge Support. Install Hytale Mods. CurseForge. [8]
• Dot Esports. Hytale Celebrates 20M Mod Downloads, Launches $100K Modding Contest. Dot Esports. [9]

References

1. CurseForge Support. Hytale Modding. CurseForge.
2. Britakee Studios / Hytale Creators. Getting Started with Packs. Hytale Modding Documentation.
3. Britakee Studios / Hytale Creators. Adding a Block. Hytale Modding Documentation.
4. Britakee Studios / Hytale Creators. Getting Started with Plugins. Hytale Modding Documentation.
5. CurseForge / Hypixel Studios. Hytale New Worlds Modding Contest. CurseForge.
6. CurseForge Blog. How to Install Mods for Hytale. CurseForge.
7. Britakee Studios / Hytale Creators. Hytale Modding Documentation Overview. Hytale Creators.
8. CurseForge Support. Install Hytale Mods. CurseForge.
9. Dot Esports. Hytale Celebrates 20M Mod Downloads, Launches $100K Modding Contest. Dot Esports.