Asset System

Quick reference for creating custom content using the JSON asset system.

Overview

Hytale uses a declarative JSON system for defining game content. Most customization is possible without code:

• Weapons, tools, items
• NPCs and creatures
• Attacks and abilities
• Projectiles
• Status effects

Custom content is added via Packs - mod folders that mirror the base game structure.

How Packs Work

Packs are content mods stored in:

• Singleplayer/Local: %AppData%/Roaming/Hytale/UserData/mods/
• Dedicated Server: <server>/mods/

The game merges your pack assets with base game assets. Your pack can:

• Add new assets (new items, NPCs, etc.)
• Override base game assets (by using the same asset ID)
• Inherit from base game assets (via Parent)

Creating a Pack

1. In-game: Creative Tools > Assets > Asset Editor > Add Pack
2. Manual: Create folder in mods/ with this structure:

YourPackName/
├── manifest.json           # Required - pack metadata
├── Common/                 # Visual assets (models, textures, icons)
│   ├── Items/
│   │   └── Weapons/
│   └── Icons/
└── Server/                 # Game logic (items, interactions, NPCs)
    ├── Item/
    │   ├── Items/
    │   ├── Interactions/
    │   ├── RootInteractions/
    │   └── Recipes/
    ├── Projectiles/
    └── NPC/
        └── Roles/

manifest.json

{
  "Group": "MyGroup",
  "Name": "MyPack",
  "Version": "1.0.0",
  "Description": "Custom weapons and NPCs",
  "Authors": [{ "Name": "YourName" }],
  "ServerVersion": "*",
  "Dependencies": {},
  "DisabledByDefault": false
}

Asset ID Rules

Asset IDs are derived from filenames. They must follow:

• Only A-Z, a-z, 0-9, and _ allowed
• First letter and letters after _ must be uppercase
• Examples: My_Custom_Sword, Fire_Wolf, Arrow_Explosive

Referencing Assets

• Your pack: Just use the asset ID (e.g., My_Custom_Sword)
• Base game: Use Hytale:Hytale prefix or just the ID (base game is default)
• Other packs: Use Group:PackName prefix

Folder Structure

Your pack mirrors the base game structure found in Assets.zip:

YourPackName/
├── manifest.json
│
├── Common/                          # Client-side visuals
│   ├── Items/
│   │   ├── Weapons/
│   │   │   └── Sword/
│   │   │       ├── My_Sword.blockymodel
│   │   │       └── My_Sword_Texture.png
│   │   └── Projectiles/
│   ├── NPC/                         # NPC models
│   ├── Icons/                       # UI icons
│   └── Sounds/                      # Audio files
│
└── Server/                          # Server-side definitions
    ├── Item/
    │   ├── Items/                   # Item definitions
    │   │   └── Weapon/
    │   │       └── My_Sword.json
    │   ├── Interactions/            # Attack/ability logic
    │   │   └── Weapons/
    │   │       └── My_Sword_Attack.json
    │   ├── RootInteractions/        # Entry points with cooldowns
    │   └── Animations/              # Animation set bindings
    │
    ├── Projectiles/                 # Projectile definitions
    │   └── My_Arrow.json
    │
    ├── NPC/
    │   ├── Roles/                   # NPC behavior definitions
    │   │   └── My_Wolf.json
    │   └── Spawn/                   # Spawn rules
    │
    ├── Drops/                       # Loot tables
    ├── Entity/
    │   ├── Effects/                 # Status effects
    │   └── ModelVFX/                # Visual effects
    └── Particles/                   # Particle systems

Quick Start

Add a Custom Sword

Create Server/Item/Items/Weapon/My_Sword.json:

{
  "Parent": "Template_Weapon_Sword",
  "TranslationProperties": { "Name": "My Sword" },
  "Model": "Items/Weapons/Sword/Iron.blockymodel",
  "Texture": "Items/Weapons/Sword/Iron_Texture.png",
  "Icon": "Icons/ItemsGenerated/Weapon_Sword_Iron.png",
  "InteractionVars": {
    "Swing_Left_Damage": {
      "Interactions": [{
        "Parent": "Weapon_Sword_Primary_Swing_Left_Damage",
        "DamageCalculator": {
          "BaseDamage": { "Physical": 30 }
        }
      }]
    }
  }
}

Add a Custom NPC

Create Server/NPC/Roles/My_Wolf.json:

{
  "Type": "Variant",
  "Reference": "Template_Predator",
  "Modify": {
    "Appearance": "Wolf",
    "MaxHealth": 60,
    "MaxSpeed": 9,
    "Attack": "Root_NPC_Attack_Melee",
    "DropList": "Drop_Wolf"
  }
}

Add a Custom Projectile

Create Server/Projectiles/My_Fireball.json:

{
  "Appearance": "Fireball",
  "MuzzleVelocity": 40,
  "Gravity": 5,
  "Damage": 35,
  "TimeToLive": 20,
  "DeathParticles": { "SystemId": "Explosion_Fire" }
}

Enable Your Pack

1. Launch Hytale, go to Worlds tab
2. Right-click your world
3. Enable your pack toggle
4. Enter the world

Documentation

Document	Purpose
architecture.md	Core systems, asset loading, inheritance
adding-drops.md	Drop tables, loot, weighted random drops
adding-items.md	Creating weapons, tools, consumables
adding-interactions.md	Attacks, abilities, combos
adding-npcs.md	Creatures, AI, drops
adding-particles.md	Particle effects, block particles
adding-projectiles.md	Bullets, arrows, magic
adding-sounds.md	Sound effects, block/item sound sets
reference/interaction-types.md	All interaction type fields
adding-recipes.md	Recipe definitions, bench types, processing
Crafting & Recipes	Runtime recipe management, crafting events
reference/common-patterns.md	Reusable snippets

Key Concepts

Inheritance (Parent)

All assets support inheritance from base game. Override only what you need:

{
  "Parent": "Template_Weapon_Sword",
  "Quality": "Legendary"
}

Variable Overrides (InteractionVars)

Customize behavior without duplicating interaction chains:

{
  "InteractionVars": {
    "Swing_Left_Damage": { "Interactions": [{ ... }] }
  }
}

Interaction Flow

Items lead to RootInteractions, which lead to Interactions (tree of effects)

Item.Primary
    └── Root_Sword_Primary (cooldown)
            └── Sword_Primary_Chain (Chaining)
                    ├── Swing_Left (Serial: animation, hit detection, damage)
                    ├── Swing_Right
                    └── Swing_Down

Base Game Reference

To see the complete base game asset structure, examine: <Hytale Install>/release/package/game/latest/Assets.zip

This contains all vanilla items, interactions, NPCs, etc. that you can inherit from or use as reference.

Code References

Core systems in com.hypixel.hytale.server.core.modules:

System	Package
Asset Loading	asset.AssetStore
JSON Parsing	asset.codec.BuilderCodec
Interactions	interaction.interaction.config.*
Items	items.ItemType
NPCs	npc.roles.*
Projectiles	projectile.*

Resources

• Hytale Modding Documentation
• Hytale Modding Strategy

Tips

1. Use templates - Inherit from existing base game templates
2. Check Assets.zip - Look at similar vanilla items for correct field names
3. Use the Asset Editor - In-game tool for creating/editing assets
4. Test incrementally - Make small changes and verify they work

Advanced: Code-Based Extensions

Most content can be added via JSON packs without code. For advanced use cases:

Goal	Approach
Add items, NPCs, interactions	JSON packs (this page)
Add new interaction types	Codec Registry
Add new NPC role types	Codec Registry
Create new asset categories	Asset Registry

See Registries for code-based extensions.