Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.rpg-leveling.zuxaw.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Database Sync

Sync player data (level, XP, stat allocations) to an external database for analytics, web dashboards, or external tools.
One-way sync only. Data flows from the game to the database. Hytale storage is the source of truth. Changes made directly in the database do not affect players in-game. This may evolve in future versions.

​
How It Works

  1. Hytale storage — Player data (level, XP, stats) is stored by Hytale in JSON files under universe/players/. This is always the authoritative source.
  2. Database mirror — When enabled, the plugin copies this data to an external database table whenever it changes.
  3. When sync runs:
    • On startup — All players from disk are synced to the DB (table is created if it does not exist).
    • On change — Whenever a player levels up, gains XP, allocates stats, or has stats reset, their data is synced asynchronously.

​
Configuration File

DatabaseConfig.json is in mods/Zuxaw_RPGLeveling/ (next to other config files).

​
All Parameters

ParameterTypeDefaultDescription
Versionstring(plugin version)Auto-written by the plugin. Used for config compatibility.
EnabledbooleanfalseWhen true, database sync is active. When false, no DB connection is made.
JdbcUrlstringH2 file URLFull JDBC connection URL. See Connection URLs below.
Usernamestring""Database username. Empty for H2 file mode.
Passwordstring""Database password.
MaxPoolSizeinteger10HikariCP connection pool size (1–…). Higher values allow more concurrent sync operations.

​
Example Configuration

MariaDB / MySQL: 
{
  "Version": "0.2.0",
  "Enabled": true,
  "JdbcUrl": "jdbc:mariadb://localhost:3306/rpgleveling",
  "Username": "rpguser",
  "Password": "rpgpass",
  "MaxPoolSize": 10
}
PostgreSQL: 
{
  "Version": "0.2.0",
  "Enabled": true,
  "JdbcUrl": "jdbc:postgresql://localhost:5432/rpgleveling",
  "Username": "rpguser",
  "Password": "rpgpass",
  "MaxPoolSize": 10
}
H2 (no external DB): 
{
  "Version": "0.2.0",
  "Enabled": true,
  "JdbcUrl": "jdbc:h2:file:./mods/Zuxaw_RPGLeveling/data/sync;MODE=MySQL",
  "Username": "",
  "Password": "",
  "MaxPoolSize": 5
}

​
Connection URLs

DatabaseJDBC URL format
MariaDBjdbc:mariadb://host:port/database
MySQLjdbc:mysql://host:port/database
PostgreSQLjdbc:postgresql://host:port/database
H2 (file)jdbc:h2:file:./path/to/file;MODE=MySQL
  • Replace host, port, and database with your values.
  • H2 file mode stores data locally; no external server is needed. Username and Password are usually empty.
  • All table names use the RPGLeveling_ prefix for consistency with the plugin.

​
Table Schema

The plugin creates RPGLeveling_players automatically when it connects (if it does not exist).
ColumnTypeDescription
uuidVARCHAR(36)Player UUID (primary key)
usernameVARCHAR(64)Display name
levelINTCurrent level
experienceDOUBLECurrent XP
available_stat_pointsINTUnallocated stat points
allocated_statsTEXTJSON map of stat allocations, e.g. {"Damage":5,"Defense":3}
last_updatedBIGINTLast sync timestamp (milliseconds since epoch)

​
Example Queries

Get data for one player (by UUID or username): 
SELECT * FROM RPGLeveling_players WHERE uuid = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx';

SELECT uuid, username, level, experience, available_stat_points, allocated_stats
FROM RPGLeveling_players WHERE username = 'PlayerName';

​
Important Notes

  • Sync is one-way. Edits in the database (e.g. via SQL) are not applied to players in-game.
  • Hytale storage wins. If there is any conflict, the in-game data is authoritative.
  • Performance — Sync runs asynchronously; it does not block gameplay.
  • Failure handling — If the DB is unreachable, sync fails quietly and is logged. The game continues normally.