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
- Hytale storage — Player data (level, XP, stats) is stored by Hytale in JSON files under
universe/players/. This is always the authoritative source.
- Database mirror — When enabled, the plugin copies this data to an external database table whenever it changes.
- 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
| Parameter | Type | Default | Description |
|---|
| Version | string | (plugin version) | Auto-written by the plugin. Used for config compatibility. |
| Enabled | boolean | false | When true, database sync is active. When false, no DB connection is made. |
| JdbcUrl | string | H2 file URL | Full JDBC connection URL. See Connection URLs below. |
| Username | string | "" | Database username. Empty for H2 file mode. |
| Password | string | "" | Database password. |
| MaxPoolSize | integer | 10 | HikariCP 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
}
{
"Version": "0.2.0",
"Enabled": true,
"JdbcUrl": "jdbc:postgresql://localhost:5432/rpgleveling",
"Username": "rpguser",
"Password": "rpgpass",
"MaxPoolSize": 10
}
{
"Version": "0.2.0",
"Enabled": true,
"JdbcUrl": "jdbc:h2:file:./mods/Zuxaw_RPGLeveling/data/sync;MODE=MySQL",
"Username": "",
"Password": "",
"MaxPoolSize": 5
}
Connection URLs
| Database | JDBC URL format |
|---|
| MariaDB | jdbc:mariadb://host:port/database |
| MySQL | jdbc:mysql://host:port/database |
| PostgreSQL | jdbc: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).
| Column | Type | Description |
|---|
uuid | VARCHAR(36) | Player UUID (primary key) |
username | VARCHAR(64) | Display name |
level | INT | Current level |
experience | DOUBLE | Current XP |
available_stat_points | INT | Unallocated stat points |
allocated_stats | TEXT | JSON map of stat allocations, e.g. {"Damage":5,"Defense":3} |
last_updated | BIGINT | Last 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.
