Hytale Asset Pack Development

When to Use Assets vs Java (Decision Matrix)

ALWAYS check this table before writing Java code for NPC/item/combat features. See engineering-philosophy/references/decision-gates.md Gate 1 for the full framework.

Anti-Pattern: Java BT Manipulation

WRONG (CorruptionMod v0.8.2-v0.8.9 — fought the engine at every step):

// Every 500ms per mob in a scheduler loop:
overrideAttitude(player, FRIENDLY, duration);  // temporary, resets
clearDamageData();                              // SensorDamage bypasses it
clearMarkedEntity(0);                           // removes target lock temporarily
resetAllInstructions();                         // resets entire behavior tree
setLeashPoint(crystalPos);                      // fights native pathfinding

RIGHT (engine-native, zero Java code):

{
    "DisableDamageGroups": ["Onyxium"],
    "Instructions": [{
        "Sensor": { "Type": "Block", "Range": 50, "Blocks": "Crystals", "Reserve": true },
        "BodyMotion": { "Type": "Seek", "StopDistance": 2.5 }
    }]
}

The JSON approach is instant (applied on spawn), permanent (no resets), correct (engine's own targeting), and zero Java (less to maintain).

Asset Pack Structure

Asset packs live in the Server/ directory at JAR root. Set "IncludesAssetPack": true in manifest.json.

Server/
├── Item/
│   ├── Block/Sets/              # Block set definitions (wildcard groups)
│   ├── Items/<Category>/<Sub>/  # Item/block JSON definitions
│   ├── Interactions/NPCs/<Faction>/<Mob>/  # Attack interaction chains
│   └── RootInteractions/NPCs/<Faction>/<Mob>/  # Root interaction entry points
├── NPC/
│   ├── Roles/<Faction>/         # NPC role definitions (AI behavior trees)
│   └── Balancing/<Faction>/     # CombatActionEvaluator configs
├── Biomes/                      # World generation biome definitions
├── WorldStructure/              # World structure, density, framework
├── Density/                     # Density node definitions (SimplexNoise, etc.)
└── Assignments/                 # Material assignment rules

Common/
└── UI/
    └── Custom/                  # Custom .ui markup files + Common.ui library

Block Sets

Block sets define groups for NPC targeting sensors. Use wildcard patterns:

{ "IncludeBlockTypes": ["Rock_Crystal_White_*"] }

This matches all blocks starting with Rock_Crystal_White_ — used by NPC Block sensors to detect target blocks.

NPC Role Definitions (AI Behavior Trees)

Roles define NPC behavior through a priority-based instruction hierarchy. The NPC evaluates instructions top-to-bottom, executing the first matching sensor.

Top-level fields:

• DefaultSubState: initial state (usually "Start")
• Type: "Generic" for most NPCs
• Appearance: visual model ID
• DisableDamageGroups: factions NPC won't damage (e.g., ["Void"])
• HotbarItems: equipped items
• MotionControllerList: movement capabilities (Walk/Fly/Swim)
• MaxHealth: use { "Compute": "MaxHealth" } with Parameters block
• Instructions: nested priority selector

Instruction Hierarchy Pattern

{
  "Instructions": [
    {
      "Instructions": [
        {
          "Sensor": { "Type": "Block", "Range": 30, "Blocks": "BlockSetName", "Reserve": true },
          "Instructions": [
            {
              "Sensor": { "Type": "Block", "Range": 3.5, "Blocks": "BlockSetName" },
              "Actions": [{ "Type": "Attack", "Attack": "Root_Attack_Name", "AttackPauseRange": [1.5, 2.5] }],
              "HeadMotion": { "Type": "Aim", "RelativeTurnSpeed": 1 }
            },
            {
              "Sensor": { "Type": "Block", "Range": 30, "Blocks": "BlockSetName" },
              "BodyMotion": { "Type": "Seek", "StopDistance": 3.0, "SlowDownDistance": 4, "RelativeSpeed": 1 }
            }
          ]
        },
        {
          "Sensor": { "Type": "Player", "Range": 20, "LockOnTarget": true },
          "Instructions": [
            { "Sensor": { "Type": "Player", "Range": 2.5 }, "Actions": [{ "Type": "Attack", "Attack": "Root_Attack_Name" }] },
            { "Sensor": { "Type": "Player", "Range": 20 }, "BodyMotion": { "Type": "Seek", "StopDistance": 1.5 } }
          ]
        },
        {
          "Sensor": { "Type": "Any" },
          "BodyMotion": { "Type": "Wander", "MaxHeadingChange": 45, "RelativeSpeed": 0.3 }
        }
      ]
    }
  ]
}

Priority: Block sensor (crystal targeting) > Player sensor (combat) > Wander (idle). Reserve: true: prevents multiple NPCs from targeting the same block.

Sensor Types

• Block: detects specific block sets. Range, Blocks (set name), Reserve (exclusive)
• Player: detects players. Range, LockOnTarget (persist targeting)
• Any: always matches (fallback/idle behavior)

Motion Types

• Seek: pathfind toward target. StopDistance, SlowDownDistance, RelativeSpeed
• Wander: random movement. MaxHeadingChange, RelativeSpeed
• Aim (head): look at target. RelativeTurnSpeed

MotionControllerList

{ "Type": "Walk", "MaxWalkSpeed": 6, "RunThreshold": 0.7, "Gravity": 10, "MaxFallSpeed": 20, "Acceleration": 10 }

CombatActionEvaluator (CAE) Configs

CAE controls NPC combat decision-making: when to attack, how much damage, cooldowns.

{
  "Type": "CombatActionEvaluator",
  "TargetMemoryDuration": 10,
  "CombatActionEvaluator": {
    "RunConditions": [
      { "Type": "TimeSinceLastUsed", "Curve": { "ResponseCurve": "Linear", "XRange": [0, 5] } },
      { "Type": "Randomiser", "MinValue": 0.75, "MaxValue": 1 }
    ],
    "MinRunUtility": 0.5,
    "MinActionUtility": 0.01,
    "AvailableActions": { ... },
    "ActionSets": { ... }
  }
}

ActionSets — BasicAttacks

{
  "BasicAttacks": {
    "Attacks": ["Root_Crystal_Spawn_Attack"],
    "InteractionVars": {
      "Melee_Damage": {
        "Interactions": [{
          "Parent": "NPC_Attack_Melee_Damage",
          "DamageCalculator": { "Type": "Absolute", "BaseDamage": { "Physical": 48 }, "RandomPercentageModifier": 0.1 },
          "DamageEffects": { "Knockback": { "Force": 0.5 }, "WorldSoundEventId": "SFX_Sword_T2_Impact" }
        }]
      }
    },
    "MaxRange": 3.5,
    "CooldownRange": [0.5, 1.0],
    "Timeout": 0.001
  }
}

Interaction System

Interactions define attack animation chains with hit detection and damage.

Hierarchy: Root → Chaining → Simple → Parallel → Selector

Root Interaction (entry point):

{ "Interactions": [{ "Type": "Chaining", "ChainId": "Slashes", "ChainingAllowance": 15, "Next": ["Swing_Left", "Swing_Right"] }], "Tags": { "Attack": ["Melee"] } }

Simple (animation trigger):

{ "Type": "Simple", "Effects": { "ItemPlayerAnimationsId": "...", "ItemAnimationId": "SwingLeft" }, "RunTime": 0.1, "Next": { ... } }

Parallel (concurrent branches):

{ "Type": "Parallel", "Interactions": [ { "Interactions": [/* hit detection */] }, { "Interactions": [/* sound */] }, { "Interactions": [/* block break */] } ] }

Selector (hit detection cone):

{ "Type": "Selector", "RunTime": 0.25, "Selector": { "Id": "Horizontal", "Direction": "ToLeft", "StartDistance": 0.5, "EndDistance": 2, "Length": 60, "YawStartOffset": -30 }, "HitEntity": { "Interactions": [{ "Type": "Replace", "DefaultOk": true, "Var": "Melee_Damage" }] } }

Replace (damage injection from CAE):

{ "Type": "Replace", "DefaultOk": true, "DefaultValue": { "Interactions": ["NPC_Attack_Melee_Damage"] }, "Var": "Melee_Damage" }

Hedera-Pattern Block_Break

Add Block_Break as a Parallel branch to enable NPC block destruction without any plugin code:

{ "Interactions": [{ "Type": "Simple", "RunTime": 0, "Next": "Block_Break" }] }

This is the v5.5.9 pattern — the engine handles block breaking natively through the interaction system.

Sound Event IDs — WARNING

WorldSoundEventId in interaction DamageEffects sections MUST reference valid sound events. Invalid IDs cause SEVERE asset validation failure and the entire mod will not load (server shuts down).

Known INVALID IDs (do not exist in current Hytale build):

• SFX_Zombie_Attack_Impact
• SFX_Light_Melee_T2_Impact
• SFX_Unarmed_Impact

Safe approach: When unsure if a sound ID exists, omit WorldSoundEventId and WorldParticles from DamageEffects. Keep only Knockback:

"DamageEffects": {
  "Knockback": { "Force": 0.5, "VelocityY": 3 }
}

Boss NPC Pattern (Hedera-style)

Multi-file pattern for boss NPCs with special attacks:

1. Custom Drop Table (Server/Drops/NPCs/<Faction>/Drop_Boss_Custom.json)

{
  "Entries": [
    { "ItemId": "Ore_Special", "Count": 18 },
    { "Type": "Choice", "Entries": [
      { "Weight": 25, "ItemId": "Weapon_Daggers_Special", "Count": 1 },
      { "Weight": 25, "ItemId": "Weapon_Sword_Special", "Count": 1 },
      { "Weight": 25, "ItemId": "Weapon_Mace_Special", "Count": 1 },
      { "Weight": 25, "ItemId": "Weapon_Axe_Special", "Count": 1 }
    ]}
  ]
}

2. Enhanced Attack Interaction (Server/Item/Interactions/NPCs/<Faction>/<Boss>/Boss_Special_Attack.json)

Override vanilla damage with custom values:

{
  "DamageCalculator": { "Type": "Absolute", "BaseDamage": { "Physical": 30 } },
  "DamageEffects": {
    "Knockback": { "Force": 3, "VelocityY": 5 },
    "StaminaDrainMultiplier": 2.0,
    "CameraEffect": { "Name": "HitBoss", "Intensity": 1 }
  }
}

3. Block-Damaging Swing (add HitBlock > DestroyBlock)

If the boss should destroy blocks with melee attacks, add HitBlock with DestroyBlock to the interaction's Parallel branch:

{ "HitBlock": { "Interactions": [{ "Type": "Simple", "RunTime": 0, "Next": "DestroyBlock" }] } }

4. Custom Role with DropList Override

Reference the custom drop table in the NPC Role JSON:

{ "DropList": "Drop_Boss_Custom" }

Item/Block Definitions

Items at Server/Item/Items/<Category>/<SubCategory>/<ItemId>.json:

{
  "TranslationProperties": { "NameKey": "...", "DescriptionKey": "..." },
  "Icon": { "Type": "Item", "ItemId": "..." },
  "Categories": [...],
  "BlockType": { "Material": "Solid", "DrawType": "Cube", "Opacity": "Opaque", ... },
  "Gathering": { "DropList": [...], "GatherType": "..." },
  "Recipe": { "Input": [{ "ItemId": "...", "Quantity": 4 }], "BenchRequirement": { "Id": "...", "Type": "...", "Categories": [...] } }
}