Configuration

Configuration

KS Dungeons’ configuration is stored in the mod’s data folder. The main file is config.json, with additional folders for biomes, rooms, and loot tables.

File Structure

dungeons/
  config.json              — Main configuration
  biomes/
    caverns.json           — Caverns biome definition
    jungle.json            — Jungle biome definition
    frost.json             — Frost biome definition
    void.json              — Void biome definition
    undead.json             — Undead biome definition
  rooms/
    caverns/               — Room templates for Caverns
    jungle/                — Room templates for Jungle
    ...
  loot/
    caverns.json           — Loot tables for Caverns
    jungle.json            — Loot tables for Jungle
    ...
  localization/
    en-US.json             — English translations
    de-DE.json             — German translations

config.json

{
  "_info": "KyuubiSoft Dungeons Configuration",
  "enabled": true,
  "language": "en-US",
  "dungeon": {
    "maxConcurrentInstances": 10,
    "maxPlayersPerRun": 4,
    "defaultLives": 5,
    "entryCoordinates": { "x": 0, "y": 80, "z": 0 },
    "returnCoordinates": { "x": 0, "y": 64, "z": 0 },
    "entryCooldownSeconds": 300,
    "timeoutMinutes": 45,
    "cleanupDelaySeconds": 30
  },
  "party": {
    "maxPartySize": 4,
    "inviteTimeoutSeconds": 60,
    "allowPublicParties": true
  },
  "difficulty": {
    "default": "NORMAL",
    "modifierCount": {
      "NORMAL": 0,
      "HARD": 1,
      "NIGHTMARE": 2,
      "MYTHIC": 3
    },
    "livesMultiplier": {
      "NORMAL": 1.0,
      "HARD": 1.0,
      "NIGHTMARE": 0.6,
      "MYTHIC": 0.4
    }
  },
  "scoring": {
    "baseScore": 1000,
    "timeBonus": true,
    "timeBonusMaxSeconds": 1200,
    "killPoints": 10,
    "deathPenalty": 50,
    "modifierMultiplier": 0.25,
    "bossKillBonus": 500
  },
  "tokens": {
    "enabled": true,
    "baseReward": 50,
    "difficultyMultiplier": {
      "NORMAL": 1.0,
      "HARD": 1.5,
      "NIGHTMARE": 2.5,
      "MYTHIC": 4.0
    }
  },
  "permissions": {
    "adminPermission": "kyuubisoft.dungeons.admin",
    "playPermission": "kyuubisoft.dungeons.play"
  }
}

Settings Reference

Dungeon

Setting	Type	Default	Description
maxConcurrentInstances	int	10	Maximum dungeon instances running at once
maxPlayersPerRun	int	4	Maximum players per dungeon run
defaultLives	int	5	Team lives pool per run
entryCoordinates	object	{0,80,0}	Dungeon world spawn point
returnCoordinates	object	{0,64,0}	Return point after dungeon ends
entryCooldownSeconds	int	300	Cooldown between dungeon entries
timeoutMinutes	int	45	Maximum dungeon run duration
cleanupDelaySeconds	int	30	Delay before dungeon instance is cleaned up

Party

Setting	Type	Default	Description
maxPartySize	int	4	Maximum party members
inviteTimeoutSeconds	int	60	Time before party invite expires
allowPublicParties	boolean	true	Allow players to join parties without invite

Difficulty

Setting	Type	Default	Description
default	string	"NORMAL"	Default difficulty for new runs
modifierCount	object	varies	Number of random modifiers per difficulty
livesMultiplier	object	varies	Multiplier applied to defaultLives per difficulty

Scoring

Setting	Type	Default	Description
baseScore	int	1000	Starting score for a run
timeBonus	boolean	true	Enable time-based bonus
timeBonusMaxSeconds	int	1200	Time window for maximum bonus
killPoints	int	10	Points per mob kill
deathPenalty	int	50	Points deducted per death
modifierMultiplier	float	0.25	Score bonus per active modifier (25% each)
bossKillBonus	int	500	Bonus points for boss kill

Tokens

Setting	Type	Default	Description
enabled	boolean	true	Enable token rewards
baseReward	int	50	Base token reward per completion
difficultyMultiplier	object	varies	Token multiplier per difficulty

---

Biome Configuration

Each biome has its own JSON file in the biomes/ folder.

{
  "id": "caverns",
  "name": "The Caverns",
  "description": "Dark underground tunnels filled with lava and stone traps.",
  "icon": "caverns.png",
  "minRooms": 6,
  "maxRooms": 12,
  "mobPool": [
    { "npcId": "Trork_Warrior", "weight": 40 },
    { "npcId": "Trork_Archer", "weight": 30 },
    { "npcId": "Trork_Shaman", "weight": 15 },
    { "npcId": "Cave_Spider", "weight": 15 }
  ],
  "bossId": "stone_golem",
  "bossRoom": "caverns_boss_arena",
  "traps": ["lava_pit", "falling_rocks", "spike_floor"],
  "ambientEffects": ["dripping_lava", "cave_echo"],
  "unlockRequirement": null
}

Field	Type	Description
id	string	Unique biome identifier
name	string	Display name
description	string	Flavor text shown in UI
icon	string	Icon file in assets
minRooms / maxRooms	int	Room count range per run
mobPool	array	Weighted mob spawn pool
bossId	string	Boss encounter ID
bossRoom	string	Room template used for boss fight
traps	array	Available trap types
ambientEffects	array	Ambient particle/sound effects
unlockRequirement	string/null	Requirement to unlock (e.g., “clear_caverns_hard”)

---

Room Templates

Room templates are structure files in the rooms/<biome>/ folders. Each room is a JSON file describing layout, spawn points, and connections.

{
  "id": "caverns_corridor_01",
  "type": "CORRIDOR",
  "size": { "x": 32, "y": 16, "z": 32 },
  "connections": ["NORTH", "SOUTH"],
  "spawnPoints": [
    { "x": 8, "y": 1, "z": 16, "type": "MOB" },
    { "x": 24, "y": 1, "z": 16, "type": "MOB" },
    { "x": 16, "y": 1, "z": 8, "type": "TRAP" }
  ],
  "lootSpawns": [
    { "x": 16, "y": 1, "z": 24, "table": "caverns_chest" }
  ]
}

Room Types

Type	Description
ENTRANCE	Starting room (one per run)
CORRIDOR	Connecting passage between rooms
ARENA	Combat encounter room
TREASURE	Bonus loot room (optional spawn)
BOSS	Boss encounter arena (one per run, always last)
TRAP	Environmental hazard room

---

Loot Tables

Loot tables are defined per biome in the loot/ folder. Each table supports difficulty-scaled entries.

{
  "tables": {
    "caverns_chest": {
      "picks": 3,
      "entries": [
        { "item": "Iron_Ingot", "amount": [2, 5], "weight": 40 },
        { "item": "Gold_Ingot", "amount": [1, 3], "weight": 25 },
        { "item": "Diamond", "amount": 1, "weight": 10 },
        { "item": "Health_Potion", "amount": [1, 2], "weight": 25 }
      ]
    },
    "caverns_boss": {
      "picks": 5,
      "guaranteed": [
        { "item": "Dungeon_Token", "amount": [10, 25] }
      ],
      "entries": [
        { "item": "Stone_Golem_Core", "amount": 1, "weight": 5, "minDifficulty": "HARD" },
        { "item": "Rare_Ore", "amount": [3, 8], "weight": 30 },
        { "item": "Epic_Weapon_Crate", "amount": 1, "weight": 10, "minDifficulty": "NIGHTMARE" }
      ]
    }
  }
}

Field	Type	Description
picks	int	Number of random items to pick
guaranteed	array	Items always given (on top of picks)
entries[].item	string	Item ID
entries[].amount	int/array	Fixed amount or [min, max] range
entries[].weight	int	Random weight
entries[].minDifficulty	string	Minimum difficulty required for this entry to appear