Asset Architecture

Overview

Hytale uses a fully data-driven architecture. Game content (items, interactions, NPCs, projectiles) is defined in JSON files, not code. The server loads these at startup and syncs them to clients.

Base Game vs Packs

Base Game (Assets.zip)

The vanilla game content lives in: <Hytale Install>/release/package/game/latest/Assets.zip

This is read-only reference - use it to understand vanilla assets and find things to inherit from.

Packs (Custom Content)

Custom content goes in Packs - mod folders that mirror the base game structure:

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

Packs can:

• Add new assets (new items, NPCs, interactions)
• Override base game assets (same asset ID replaces vanilla)
• Inherit from base game assets (via Parent)

Folder Structure

Both base game and packs use identical structure:

[Pack or Assets.zip]/
├── Server/                    # Game logic (JSON definitions)
│   ├── Item/
│   │   ├── Items/             # Item definitions
│   │   ├── Interactions/      # Interaction behaviors
│   │   ├── RootInteractions/  # Interaction entry points
│   │   ├── Recipes/           # Crafting recipes
│   │   └── Animations/        # Per-weapon animation sets
│   ├── Entity/                # Entity components (stats, effects)
│   ├── NPC/                   # AI behaviors, roles
│   ├── Projectiles/           # Projectile configs
│   ├── Drops/                 # Loot tables
│   └── ...
│
└── Common/                    # Shared assets (visuals, audio)
    ├── Items/                 # .blockymodel, textures
    ├── Characters/            # Player animations
    ├── Sounds/                # .ogg audio
    ├── Particles/             # Particle definitions
    └── Icons/                 # UI icons

Key insight: Server/ contains behavior, Common/ contains presentation.

Pack Manifest

Every pack needs a manifest.json in its root:

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

Asset ID Rules

Asset IDs (derived from filenames) 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, Explosive_Arrow

Core Systems

1. Asset Loading (BuilderCodec)

All JSON is parsed through a typed codec system that provides validation, inheritance, and schema generation.

Code: com.hypixel.hytale.codec.builder.BuilderCodec Code: com.hypixel.hytale.assetstore.AssetStore

Each asset type has a codec that defines its fields:

// from com.hypixel.hytale.server.core.modules.interaction.interaction.config.Interaction
CODEC = BuilderCodec.builder(Interaction.class, ...)
    .append("RunTime", FLOAT, (o,v) -> o.runTime = v, ...)
    .append("Effects", InteractionEffects.CODEC, ...)
    .build();

This means:

• JSON fields are validated at load time
• Unknown fields cause warnings
• Missing required fields cause errors
• You can’t invent new fields without code changes

2. Inheritance System

Assets can inherit from other assets using Parent:

Example (from base game Server/Item/Items/Weapon/Sword/Weapon_Sword_Iron.json):

{
  "Parent": "Template_Weapon_Sword",
  "InteractionVars": {
    "Swing_Left_Damage": {
      "Interactions": [{
        "Parent": "Weapon_Sword_Primary_Swing_Left_Damage",
        "DamageCalculator": { "BaseDamage": { "Physical": 9 } }
      }]
    }
  }
}

Inheritance chain:

Weapon_Sword_Iron
    └── Parent: Template_Weapon_Sword
            └── Parent: Template_Weapon
                    └── (base item properties)

Key fields:

• Parent - Inherit all fields from another asset
• InteractionVars - Override specific nested interactions by variable name
• Fields you specify override parent values

Custom packs can inherit from base game assets:

{
  "Parent": "Template_Weapon_Sword",
  "TranslationProperties": { "Name": "My Custom Sword" }
}

3. Item to Interaction Flow

Items don’t contain attack logic directly. They reference interactions via trigger bindings.

Trigger types (com.hypixel.hytale.protocol.InteractionType):

• Primary - Left click
• Secondary - Right click
• Ability1, Ability2, Ability3 - Ability keys
• Use - Interact key (E)
• SwapTo, SwapFrom - Equip/unequip
• Held, Equipped - Passive while holding/wearing
• ProjectileHit, ProjectileMiss - Projectile events
• CollisionEnter, Death - Entity events

4. Interaction Execution

Interactions form a behavior tree executed by the server.

Code: com.hypixel.hytale.server.core.modules.interaction.interaction.config.Interaction Code: com.hypixel.hytale.server.core.modules.interaction.interaction.config.RootInteraction

Execution flow:

5. Client-Server Authority Split

Different interaction types have different authority models:

Aspect	Authority	Why
Combo index	Client	Responsiveness
Charge time	Client	Responsiveness
Hit detection (Selector)	Client	Lag compensation
Damage calculation	Server	Anti-cheat
Status effects	Server	Anti-cheat
Inventory changes	Server	Anti-cheat

Code: com.hypixel.hytale.protocol.InteractionSyncData - Packet containing client state Code: com.hypixel.hytale.protocol.WaitForDataFrom - Enum: Client, Server, None

When an interaction has WaitForDataFrom.Client, the server waits for client input (like which combo attack or what entities were hit).

6. Variable Override System (InteractionVars)

Items can override specific parts of their interaction chain without redefining everything.

Example: Same attack animation, different damage per weapon tier:

In your pack’s item (Server/Item/Items/Weapon/My_Sword.json):

{
  "Parent": "Template_Weapon_Sword",
  "InteractionVars": {
    "Swing_Left_Damage": {
      "Interactions": [{
        "Parent": "Weapon_Sword_Primary_Swing_Left_Damage",
        "DamageCalculator": { "BaseDamage": { "Physical": 25 } }
      }]
    }
  }
}

The base game interaction chain uses Var references (from Server/Item/Interactions/Weapons/Sword/...):

{
  "Type": "Selector",
  "HitEntity": {
    "Interactions": [{
      "Type": "Replace",
      "Var": "Swing_Left_Damage",      // this gets replaced
      "DefaultOk": true,
      "DefaultValue": { "Interactions": ["Weapon_Sword_Primary_Swing_Left_Damage"] }
    }]
  }
}

Flow:

1. Selector detects hit
2. Looks for Swing_Left_Damage in item’s InteractionVars
3. If found, use item’s override
4. If not found, use DefaultValue

This allows:

• Shared interaction chains across weapon tiers
• Per-item damage, effects, sounds
• No duplication of attack logic

7. Animation Binding

Items reference animation sets, not individual animations.

Example (base game Server/Item/Items/Weapon/Sword/Template_Weapon_Sword.json):

{
  "PlayerAnimationsId": "Sword"
}

This loads animation set from Server/Item/Animations/Sword.json:

{
  "Animations": {
    "Idle": { "ThirdPerson": "...", "FirstPerson": "..." },
    "Walk": { ... },
    "SwingLeft": { ... },
    "SwingRight": { ... }
  }
}

Interactions reference animations by ID:

{
  "Effects": {
    "ItemAnimationId": "SwingLeft"   // looks up in current weapon's animation set
  }
}

8. Projectile System

Projectiles are separate assets referenced by interactions.

Interaction (launches projectile):

{
  "Type": "LaunchProjectile",
  "ProjectileId": "My_Custom_Bullet"
}

Projectile definition (Server/Projectiles/My_Custom_Bullet.json):

{
  "Appearance": "Bullet_Blunderbuss",
  "MuzzleVelocity": 300,
  "Gravity": 10,
  "Damage": 50,
  "TimeToLive": 50
}

Projectiles can have their own interactions for hit/miss events.

Key Patterns

Pattern 1: Template Inheritance

Create a template with shared properties, inherit for variants:

Template_Weapon_Sword          (defines interactions, animations)
    ├── Weapon_Sword_Wooden    (low damage)
    ├── Weapon_Sword_Iron      (medium damage)
    └── Weapon_Sword_Diamond   (high damage)

Pattern 2: Interaction Chains

Break complex behaviors into reusable pieces:

Root_Sword_Primary
    └── Sword_Primary_Chain (Chaining - cycles through attacks)
            ├── Swing_Left (Simple - animation + sound)
            │       └── Swing_Left_Selector (Selector - hit detection)
            │               └── Swing_Left_Damage (DamageEntity)
            ├── Swing_Right
            │       └── ...
            └── Swing_Down
                    └── ...

Pattern 3: Var Overrides for Customization

Use Var + InteractionVars for per-item customization without duplicating chains:

// in interaction chain
{ "Var": "MyDamage", "DefaultValue": { ... } }

// in item
{ "InteractionVars": { "MyDamage": { "Interactions": [...] } } }

File Reference

Base Game (read-only reference)

Located at <Hytale Install>/release/package/game/latest/Assets.zip:

What	Location in Assets.zip
Item definitions	Server/Item/Items/
Recipes	Server/Item/Recipes/
Interactions	Server/Item/Interactions/
Root interactions	Server/Item/RootInteractions/
Animation sets	Server/Item/Animations/
Projectiles	Server/Projectiles/
NPC roles	Server/NPC/Roles/
Entity stats	Server/Entity/Stats/
Status effects	Server/Entity/Effects/
Drops	Server/Drops/
Models	Common/Items/
Sounds	Common/Sounds/
Particles	Server/Particles/

Your Pack (custom content)

Located at mods/YourPackName/:

What	Location in Pack
Custom items	Server/Item/Items/
Custom recipes	Server/Item/Recipes/
Custom interactions	Server/Item/Interactions/
Custom projectiles	Server/Projectiles/
Custom NPCs	Server/NPC/Roles/
Custom drops	Server/Drops/
Custom models	Common/Items/
Pack metadata	manifest.json

Code Reference

System	Package
Asset loading	com.hypixel.hytale.assetstore.AssetStore
Codec system	com.hypixel.hytale.codec.builder.BuilderCodec
Interaction base	com.hypixel.hytale.server.core.modules.interaction.interaction.config.Interaction
Interaction types	com.hypixel.hytale.server.core.modules.interaction.interaction.config.none.*
	com.hypixel.hytale.server.core.modules.interaction.interaction.config.client.*
	com.hypixel.hytale.server.core.modules.interaction.interaction.config.server.*
Sync data	com.hypixel.hytale.protocol.InteractionSyncData
Trigger types	com.hypixel.hytale.protocol.InteractionType
Item config	com.hypixel.hytale.server.core.asset.type.item.config.Item
Projectile config	com.hypixel.hytale.server.core.asset.type.projectile.config.Projectile