Hostiles (Enemies) Reference

A hostile is an individual enemy unit — a ship, creature, drone, or boss that the player fights inside a dungeon room. Hostiles define how strong an enemy is: health, damage, attack rate, and crit chance.

Files live in: <your_pack_id>/data/enemies/hostiles/<group_folder>/<enemy_name>.json

File Structure

{
  "hostile": {
    "id": "...",
    "displayName": "...",
    "meta": {
      "health": 0,
      "defense": 0.0,
      "damage": 0.0,
      "criticalChance": 0.0,
      "attackRate": 0.0
    }
  }
}

Field Reference

Field	Type	Required	Description
id	string	✅	Namespaced ID. Format: pack_id:group/enemy_name
displayName	string	✅	Display name. Can be a translation key or a raw string.
meta.health	number	✅	Total hit points. Enemy is defeated when this reaches zero.
meta.defense	number	✅	Flat damage reduction per hit. Higher = tankier.
meta.damage	number	✅	Base damage dealt per attack to the player.
meta.criticalChance	number	✅	Probability (0.0–1.0) that an attack is a critical hit. 0.1 = 10% crit chance.
meta.attackRate	number	✅	How many attacks the enemy makes per second. Higher = faster attacker.

Stat Scaling Guide

Stat	Low	Standard	Boss-tier
health	10–50 (swarm)	100–500	500+
defense	0.0 (none)	1.0–3.0 (light)	15.0+ (boss)
damage	1.0–5.0 (weak)	5.0–15.0	30.0+
criticalChance	0.0 (none)	0.1–0.2	0.25–0.5
attackRate	0.3–0.5 (slow)	1.0	2.0–5.0 (fast)

Example — Fragile Swarm Unit

{
  "hostile": {
    "id": "stellar_forge:drones/nano_swarm",
    "displayName": "enemies.stellar_forge.drones.nano_swarm",
    "meta": {
      "health": 20,
      "defense": 0.0,
      "damage": 1.5,
      "criticalChance": 0.05,
      "attackRate": 3.5
    }
  }
}

Very low health, no armor, tiny damage per hit — but attacks 3.5 times per second. Designed to swarm the player in numbers.

Example — Standard Combat Enemy

{
  "hostile": {
    "id": "stellar_forge:guards/mining_enforcer",
    "displayName": "enemies.stellar_forge.guards.mining_enforcer",
    "meta": {
      "health": 200,
      "defense": 2.5,
      "damage": 8.0,
      "criticalChance": 0.12,
      "attackRate": 1.0
    }
  }
}

Example — Heavy Gunship

{
  "hostile": {
    "id": "stellar_forge:ships/heavy_gunship",
    "displayName": "enemies.stellar_forge.ships.heavy_gunship",
    "meta": {
      "health": 750,
      "defense": 8.0,
      "damage": 25.0,
      "criticalChance": 0.1,
      "attackRate": 0.4
    }
  }
}

Example — Boss

{
  "hostile": {
    "id": "stellar_forge:bosses/excavator_prime",
    "displayName": "enemies.stellar_forge.bosses.excavator_prime",
    "meta": {
      "health": 2500,
      "defense": 12.0,
      "damage": 35.0,
      "criticalChance": 0.25,
      "attackRate": 0.7
    }
  }
}

displayName: Translation Key vs Raw String

The displayName field can be either a translation key (recommended for multi-language support):

"displayName": "enemies.stellar_forge.drones.nano_swarm"

Or a raw string (fine for prototyping, no translation support):

"displayName": "Nano Swarm Drone"