RPG Leveling Integration

ArenaPvP integrates with RPG Leveling to manage player levels during arena matches and share experience between group members in the open world.

This integration is completely optional — if RPG Leveling is not installed, ArenaPvP works normally without it.

Internal API & Reflection

The RPGLeveling public API (RPGLevelingAPI) currently returns stale data for player levels and XP (always level=1, xp=0.0). To work around this limitation, ArenaPvP reads player data directly from the ECS Store and invokes internal RPGLeveling methods via Java reflection.

This means the integration depends on RPGLeveling's internal class structure (e.g. LevelingService, Formulas, PlayerLevelData, LevelingConfig). Any update to RPGLeveling that renames, removes, or changes the signature of these internal classes or methods may break the integration without warning. If this happens, ArenaPvP will fall back gracefully (level display and XP bar will show defaults or become hidden), but features like level save/restore and XP sharing may stop working until the integration is updated.

We recommend pinning your RPGLeveling version and testing thoroughly after any RPGLeveling update before deploying to production.

Features

Level Reset in Arenas

When enabled, player levels are saved and reset to base level upon entering an arena, then fully restored when the match ends. This ensures all players compete on equal footing regardless of their RPG progression.

Group members can automatically share a percentage of earned experience with nearby teammates when they are outside arenas. This encourages playing together in the open world.

Only activates when both the earner and the receiver are outside an arena
Receivers must be in the same world and within the configured distance
The shared XP is a configurable percentage of the original amount

Level Display in Group HUD

When enabled, each group member's current level is shown next to their name in the group HUD. The display format is fully customizable.

Example: PlayerName - Leader [Lvl. 12]

Experience Bar in Group HUD

When enabled, an experience bar is displayed for each group member in the group HUD, showing their progress toward the next level. The bar updates in real-time as players earn XP.

Requires ShowExpBarGroup: true in the configuration
Automatically hidden if RPG Leveling is not detected
Progress is calculated using RPGLeveling's internal XP formulas via reflection

Setup

Install RPG Leveling on your Hytale server.
Start the server — ArenaPvP detects it automatically.

Check the server log for:

[RPGLeveling] RPGLeveling detected - will connect when needed
[RPGLeveling] RPGLeveling integration enabled
[RPGLeveling] XP share listener registered

No additional setup is needed. The integration activates automatically when RPG Leveling is present.

Configuration

All RPG Leveling settings live inside the Integrations block of your config.json:

{
  "Integrations": {
    "RPGLeveling": {
      "ShareExp": true,
      "SharePercentage": 50,
      "ShareDistance": 1000,
      "ShowLvlGroup": true,
      "FormatLvlGroup": "Lvl. {0}",
      "ShowExpBarGroup": true,
      "FairPlayMode": true
    }
  }
}

Key	Type	Default	Description
`ShareExp`	boolean	`true`	Enable XP sharing between group members outside arenas
`SharePercentage`	integer	`50`	Percentage of earned XP to share with nearby group members (e.g. `50` = each member receives 50% of the original XP)
`ShareDistance`	integer	`1000`	Maximum distance (in blocks) between the earner and a group member for XP sharing to apply
`ShowLvlGroup`	boolean	`true`	Show each member's RPG level next to their name in the group HUD
`ShowExpBarGroup`	boolean	`true`	Show a real-time experience progress bar for each group member in the group HUD
`FormatLvlGroup`	string	`"Lvl. {0}"`	Format for level display in the group HUD. `{0}` is replaced by the player's level
`FairPlayMode`	boolean	`true`	Save and reset player level on arena entry, restore on exit. This ensures all players compete on equal footing regardless of their RPG level. Set to `false` to let players keep their level bonuses inside arenas

With the default settings (SharePercentage: 50, ShareDistance: 1000):

Player A kills a mob and earns 100 XP
Player B is in the same group, same world, 500 blocks away → receives 50 XP
Player C is in the same group, same world, 1500 blocks away → receives nothing (too far)
Player D is in the same group but inside an arena → receives nothing (in arena)

Level Format Examples

`FormatLvlGroup`	Result
`"Lvl. {0}"`	`[Lvl. 12]`
`"Level {0}"`	`[Level 12]`
`"Nv. {0}"`	`[Nv. 12]`
`"Lv{0}"`	`[Lv12]`

Data Persistence

Level snapshots are stored as JSON files in:

mods/arenapvp/data/rpgleveling/
  550e8400-e29b-41d4-a716-446655440000.json
  ...

Each file contains the player's level and XP data before entering the arena. If the server crashes or restarts, the data is preserved and will be restored when the player reconnects.

info

XP sharing does not reduce the earner's XP — the shared amount is bonus XP given to nearby group members on top of what the earner receives.

Without RPG Leveling

If RPG Leveling is not installed, the integration is silently disabled. No errors are logged and arenas function normally — players simply keep their levels during matches, and XP sharing is not available.

Known Limitations

Hot Reload Not Supported

ArenaPvP connects to RPG Leveling using a lazy initialization strategy: the API reference (RPGLevelingAPI.get()) is only obtained the first time it's actually needed, and then cached internally. This works well under normal conditions, but means that hot-reloading RPG Leveling while the server is running will break the integration.

When RPG Leveling is reloaded, its internal singleton is replaced with a new instance. However, ArenaPvP still holds a reference to the old (now invalid) instance, so:

XP sharing stops working — the registered listener is attached to the old API instance.
Level save/restore may fail — calls like getPlayerLevel() or setPlayerLevel() go through a stale reference.

This is a limitation of RPG Leveling's singleton API design, not something ArenaPvP can work around.

warning

If you need to reload RPG Leveling, restart the server entirely. A simple /reload or hot-swap of the RPG Leveling jar will silently break the integration until a full restart.

Reflection-Based Implementation

Because the RPGLeveling public API returns stale data, ArenaPvP accesses RPGLeveling internals via Java reflection. The following internal classes and methods are accessed:

Class	Methods / Fields Used
`RPGLevelingPlugin`	`get()`, `getLevelingService()`, `getLevelingConfig()`
`LevelingService`	`getPlayerLevelDataType()`, `setPlayerLevel()`, `getXPNeededForNextLevel()`
`LevelingConfig`	`getLevelBaseXP()`, `getLevelOffset()`, `getMaxLevel()`
`Formulas`	`xpNeededForNextLevel()` (static fallback)
`PlayerLevelData`	`getLevel()`, `getExperience()`, `setExperience()`, `clone()`

If any of these are modified in a future RPGLeveling update, the affected feature will fail gracefully:

Level/XP display: Falls back to defaults or hides the UI element.
XP bar: Falls back to a config-based formula approximation, then to level × 100.
Level save/restore: Logs an error and skips the operation — no data corruption.

Specific failure messages are logged under the [RPGLeveling] prefix when debugMode is enabled in the ArenaPvP config.

Features​

Level Reset in Arenas​

XP Sharing Between Group Members​

Level Display in Group HUD​

Experience Bar in Group HUD​

Setup​

Configuration​

XP Sharing Example​

Level Format Examples​

Data Persistence​

Without RPG Leveling​

Known Limitations​

Hot Reload Not Supported​

Reflection-Based Implementation​