Skip to main content

​
Level Rewards Config

File: mods/Zuxaw_RPGLeveling/LevelRewardsConfig.json Defines rewards that players can claim when they reach specific levels. Each reward can grant items (into the player’s inventory) and/or reset points (used with the RESET ALL button on the Stats page to refund allocated stat points). Rewards are claimed in the Rewards tab of the Stats GUI (/lvl gui).

​
Configuration Structure

The file uses PascalCase keys (same convention as Zone Level Config).
OptionTypeDescription
VersionStringPlugin version (auto-updated on load).
RewardsArrayList of reward entries, one per level threshold. If empty, no level rewards exist — players cannot earn or claim any rewards from the Rewards tab.

​
Reward Entry

Each element of Rewards has:
OptionTypeDefaultDescription
LevelInteger—Level at which this reward is unlocked. Must be > 0.
ItemsArray[]List of items to give when the reward is claimed.
ResetPointsInteger0Number of reset points to grant when claimed. Reset points are used with the RESET ALL button on the Stats page.
CommandString""Optional command to run when the reward is claimed (e.g. lvl setlevel {player} 10). See Running a command when a reward is claimed below.
CommandTitleString""Optional label shown in the Rewards tab for this reward (e.g. “Set level”). If empty, the command string is shown when present.

​
Running a command when a reward is claimed

You can run one command per reward when a player claims it. Use Command for the command string and, optionally, CommandTitle for the text shown in the Additional rewards column of the Rewards tab.

​
Placeholder: {player}

  • In Command, the placeholder {player} is replaced with the username of the player who claimed the reward.
  • Example: Command": "lvl setlevel {player} 10" runs as lvl setlevel TheirName 10 when that player claims the reward.

​
Built-in: lvl setlevel

The plugin runs lvl setlevel {player} <level> itself when it appears in a reward. You do not need the game’s command system for this:
  • Use it to set the claiming player’s level when they claim (e.g. level 10 reward: "Command": "lvl setlevel {player} 10").
  • Works even when the server’s CommandManager is unavailable.
  • Level is applied immediately (no restart). Leaderboard is updated if enabled.

​
Other commands (any mod)

Any other command (e.g. gamemode adventure {player}, give money, or commands from other mods) is executed via the game’s CommandManager. The plugin tries several strategies so that mod commands work when possible: running the command as the claiming player, then as the server console, and retrying once on the world thread. If CommandManager is not available in your environment, only the built-in lvl setlevel reward command will run; other commands will be skipped and a warning will be logged.

​
Example with command

{
  "Level": 10,
  "Items": [ { "ItemId": "Ore_Copper", "Quantity": 10 } ],
  "ResetPoints": 0,
  "Command": "lvl setlevel {player} 10",
  "CommandTitle": "Set level"
}
  • When the player claims this reward: items are granted, and the command lvl setlevel TheirName 10 is run (setting that player to level 10).
  • In the Rewards tab, the Additional column shows “Set level” (from CommandTitle). If CommandTitle were empty, it would show the command string instead.
Use "Command": "" and "CommandTitle": "" (or omit them) when a reward has no command.

​
Item Entry

Each element of Items has:
OptionTypeDescription
ItemIdStringHytale item asset ID (e.g. Ore_Copper, Rock_Gem_Emerald).
QuantityIntegerNumber of items to add to the player’s inventory (storage).
Items are added to the player’s storage (main backpack) when the reward is claimed. Invalid or missing ItemId values are skipped and logged.

​
Example

{
  "Version": "0.2.7",
  "Rewards": [
    {
      "Level": 10,
      "Items": [
        { "ItemId": "Ore_Copper", "Quantity": 15 },
        { "ItemId": "Rock_Gem_Emerald", "Quantity": 4 }
      ],
      "ResetPoints": 0,
      "Command": "lvl setlevel {player} 10",
      "CommandTitle": "Set level"
    },
    {
      "Level": 15,
      "Items": [],
      "ResetPoints": 1,
      "Command": "",
      "CommandTitle": ""
    },
    {
      "Level": 20,
      "Items": [
        { "ItemId": "Ore_Iron", "Quantity": 10 }
      ],
      "ResetPoints": 0,
      "Command": "",
      "CommandTitle": ""
    }
  ]
}
  • Level 10 — Player receives 15 Copper Ore and 4 Emerald when they claim; no reset points; command lvl setlevel {player} 10 runs (sets that player to level 10). Additional column shows “Set level”.
  • Level 15 — No items; 1 reset point when claimed; no command.
  • Level 20 — 10 Iron Ore when claimed; no reset points; no command.

​
How Rewards Work

If the Rewards array is empty, no rewards are defined and players cannot earn or claim any level rewards.
  1. Unlock — When the player’s level is greater than or equal to a reward’s Level, that reward is available to claim.
  2. Claim — In the Stats GUI, open the Rewards tab. Each row shows level, items, reset points (if any), and a status: Unclaim (click to claim) or Claimed.
  3. Claim All — If there is at least one unclaimed reward the player has reached the level for, a Claim All button appears. Clicking it claims every such reward at once (items added to storage, reset points added).
  4. One-time — Each reward level can only be claimed once per character. Claimed levels are stored in player data and persist across sessions (and in the external database if Database Sync is enabled).

​
Reset Points

  • Earned — By claiming rewards that have ResetPoints > 0.
  • Display — Shown on the Stats tab as xN next to the RESET ALL button (e.g. x5).
  • Use — The RESET ALL button consumes 1 reset point and refunds all allocated stat points to available, then reapplies stats so Health/Stamina etc. return to base values. The button is disabled when the player has 0 reset points.
  • Admin — Use /lvl setreset <player> <amount> to set a player’s reset points (see Commands).

​
File Location and Reload

  • Path: mods/Zuxaw_RPGLeveling/LevelRewardsConfig.json
  • The plugin creates a default file on first run if it does not exist.
  • Config is loaded at startup. To apply changes without restarting the server, use /lvl reload (admin/OP). This reloads all config files, including RPGLevelingConfig, StatsLevelConfig, and DatabaseConfig (DatabaseConfig: in-memory only; DB connection changes require restart).