Data Files¶

All plugin data is stored as JSON files in plugins/HTSkyBlock/. This page documents each file and its purpose.

Editing Data Files

It is generally safe to edit config files while the server is stopped. Editing data files (islands.json, economy.json, etc.) while the server is running may cause data loss, as the plugin periodically saves to these files and will overwrite your changes.

Configuration Files¶

config.json¶

The main plugin configuration file. Controls all feature toggles, settings, and defaults.

See Configuration for a full reference of every field.

blockworth.json¶

Defines the score value of each block type for island ranking. Used when calculating island scores.

{
  "defaultWorth": 1,
  "blocks": {
    "Stone": 1,
    "Iron Ore": 10,
    "Gold Ore": 25,
    "Diamond Ore": 100
  }
}

Block Names

Block names should match Hytale block IDs. The system supports fuzzy matching (with or without namespace prefix).

challenges.json¶

Defines all available challenges, their requirements, and rewards.

{
  "levels": [
    {
      "id": "beginner",
      "friendlyName": "Beginner",
      "icon": "Wood Plank",
      "order": 1
    }
  ],
  "challenges": [
    {
      "id": "gather_wood",
      "friendlyName": "Lumberjack",
      "description": "Collect 64 wood planks",
      "level": "beginner",
      "type": "inventory",
      "requiredItems": [{"id": "Wood Plank", "amount": 64}],
      "takeItems": true,
      "moneyReward": 100,
      "repeatable": true,
      "maxRepeats": 5
    }
  ]
}

shop.json¶

Contains all shop categories and items. Managed via /htshop commands.

{
  "categories": [
    {
      "name": "Building",
      "icon": "Stone",
      "order": 1,
      "items": [
        {
          "id": "Stone",
          "name": "Stone",
          "buyPrice": 5.0,
          "sellPrice": 2.0,
          "sellable": true
        }
      ]
    }
  ]
}

dungeons.json¶

Stores dungeon template configurations including spawn groups, trigger points, spawn locations, and wave definitions. Managed via /dungeondev commands.

{
  "skydungeon1": {
    "id": "skydungeon1",
    "instanceName": "Skydungeon1",
    "displayName": "Sky Dungeon 1",
    "spawnGroups": [
      {
        "id": "room1",
        "triggerX": 10.0,
        "triggerY": 65.0,
        "triggerZ": 20.0,
        "triggerRadius": 10.0,
        "waveDelaySeconds": 3.0,
        "spawnPoints": [
          {"x": 12.0, "y": 65.0, "z": 22.0, "yaw": 90.0},
          {"x": 8.0, "y": 65.0, "z": 18.0, "yaw": -90.0}
        ],
        "waves": [
          {"mobType": "Trork_Warrior", "count": 3},
          {"mobType": "Trork_Grunt", "count": 5}
        ]
      }
    ]
  }
}

Key fields per template:

Field	Description
`id`	Unique template identifier
`instanceName`	Instance asset folder name (from `Server/Instances/`)
`displayName`	Friendly display name
`spawnGroups`	List of spawn group configurations

Key fields per spawn group:

Field	Description
`id`	Group identifier
`triggerX/Y/Z`	Center of the proximity trigger
`triggerRadius`	How close the player must be to activate (default: 10)
`waveDelaySeconds`	Delay between waves after all mobs die (default: 3)
`spawnPoints`	List of locations where mobs appear (x, y, z, yaw)
`waves`	Ordered list of waves (mobType = NPC role name, count = number of mobs)

In-Game Editing

Use /dungeondev commands to manage dungeons in-game rather than editing this file directly. The commands automatically save positions from your current location.

Player Data Files¶

islands.json¶

Stores all island data including locations, settings, members, scores, and boundaries.

Key fields per island:

Field	Description
`playerId`	Owner's UUID
`playerName`	Owner's username
`islandName`	Custom island name
`worldName`	World name containing the island
`location`	Island center coordinates (x, y, z)
`homeLocation`	Player home teleport location
`spawnLocation`	Visitor spawn location
`isPublic`	Whether visitors can enter freely
`pvpEnabled`	Whether PvP is allowed
`score`	Island score based on block worth
`rank`	Leaderboard rank position
`sizeTier`	Island size tier (1-4)
`members`	List of trusted member UUIDs and names
`generated`	Whether the island structure has been placed
`gridX` / `gridZ`	Grid position (single-world mode only)

economy.json¶

Player balances for the self-hosted economy provider. Not used when an external economy provider is configured.

{
  "balances": {
    "uuid-here": 1000.00
  }
}

homes.json¶

Named home locations per island.

{
  "homes": {
    "player-uuid": {
      "base": {"x": 0, "y": 65, "z": 0},
      "farm": {"x": 10, "y": 65, "z": 20}
    }
  }
}

flytime_data.json¶

Stores banked fly time per player in seconds.

{
  "flyTimes": {
    "player-uuid": 3600
  }
}

challenge_data.json¶

Tracks player challenge completion progress.

{
  "playerData": {
    "player-uuid": {
      "completed": ["gather_wood", "build_house"],
      "repeatCounts": {"gather_wood": 3}
    }
  }
}

Marketplace Files¶

ahlist.json¶

Active auction house listings.

Key fields per listing:

Field	Description
`sellerUuid`	Seller's UUID
`sellerName`	Seller's username
`itemId`	Item type ID
`quantity`	Number of items
`price`	Listing price
`createdAt`	Timestamp when listed
`expiresAt`	Timestamp when listing expires

ah_cooldowns.json¶

Tracks cooldowns between auction listings per player to prevent spam.

World Data Files¶

stacked_blocks.json¶

Stores block stack data for the block stacking system.

Key fields per stack:

Field	Description
`worldName`	World containing the stack
`x` / `y` / `z`	Stack position
`blockId`	Block type ID
`count`	Number of blocks in stack
`hologramUuid`	UUID of the count display entity

npcs.json¶

Stores NPC data including positions, skins, and chat messages.

Key fields per NPC:

Field	Description
`name`	Display name
`skinPlayerName`	Player whose skin to use
`worldName`	World the NPC is in
`x` / `y` / `z`	Position
`yaw` / `pitch`	Rotation
`chatMessages`	Messages shown on interaction

cinematics.json¶

Stores cinematic camera sequences.

Key fields per cinematic:

Field	Description
`name`	Cinematic name
`worldName`	World to play in
`locations`	List of camera positions with settings
`defaultOrbitSpeed`	Default camera orbit speed
`defaultOrbitRadius`	Default camera orbit radius
`defaultCameraHeight`	Default camera height
`defaultCameraPitch`	Default camera angle

visit_requests.json¶

Stores pending island visit requests.

Language Files¶

lang/en.json¶

English language file containing all translatable messages. Generated automatically on first run from built-in defaults. You can edit this file to customize any message.

Messages support:

Color codes: &a (green), &c (red), &f (white), &6 (gold), etc.
Bold/italic: &l (bold), &o (italic), &r (reset)
Hex colors: #RRGGBB at the start of a message
Placeholders: {player}, {amount}, {time}, etc.

Custom Languages

To add a new language, copy lang/en.json to lang/xx.json (e.g., lang/fr.json), translate the values, and set "language": "fr" in config.json.