personalstats 1.4.0

Personal Stats 1.4.0

Personal Stats is a universal client-server code mod for Vintage Story. It records player activity, turns qualifying kills into a configurable 700-level progression system, provides personal statistics and rankings, and displays the synchronized level above every player:

[ LvL X ] PlayerName

• the brackets are gray;
• LvL X is orange;
• the real player name remains white.

The mod does not modify the player's actual name, UID, save identity, or database identity. The existing chat prefix is separate and remains unchanged.

Compatibility and distribution

• Mod ID: personalstats
• Release and network version: 1.4.0
• Tested Vintage Story version: 1.22.3
• Metadata dependency: Vintage Story 1.22.3 or newer
• Side: Universal
• Required on server: yes
• Required on client: yes

Server owners install the ZIP on the server. When a player joins, Vintage Story can automatically download the matching Universal release from the official ModDB into that server's ModsByServer directory. Players normally do not need to copy the ZIP manually.

For automatic download to work, the server ZIP and ModDB release must have the same modid (personalstats) and version (1.4.0). Keep the ZIP packed and keep only one enabled Personal Stats version.

Quick installation for server owners

1. Back up the world and the server data directory.
2. Stop the Vintage Story server cleanly.
3. Put personalstats_1.4.0.zip in the server's VintagestoryData/Mods directory. Do not unpack it.
4. Remove or disable older personalstats ZIPs so only one version can load.
5. Start the server.
6. On a new installation, let the mod create ModConfig/personalstats.json and its default SQLite database.
7. Join with a Vintage Story 1.22.3 client and accept the automatic mod download.
8. Verify /mystats, /ranks, and the colored level nametag above another player.

The default SQLite setup needs no external database server, database account, or password.

Client installation and automatic download

Personal Stats 1.4.0 contains both parts in one ZIP:

• the server part owns configuration, persistence, tracking, commands, progression, and level synchronization;
• the client part only installs the colored nametag renderer and reads the synchronized level.

The server sends the level through the player's WatchedAttributes. The client never connects to SQLite or MariaDB and never receives database credentials.

If a client previously cached a broken or different copy, exit the game, remove only that server's subdirectory from VintagestoryData/ModsByServer, restart the game, and join again. Vintage Story will recreate it and download the server's required releases. Do not delete unrelated single-player mods or other servers' directories.

How the level system works

The stored count of qualifying kills is the single source of truth. The level is calculated from that count; no second level database or client-side counter exists. When records are loaded, the same progression calculation is used again.

Default early thresholds:

Level	Total qualifying kills required
1	0
2	8
3	10
4	12
5	16
6	19
7	23

After level 6, the default curve uses these bands:

Current level band	Kills required for each next level
6-10	4
11-25	5
26-50	6
51-100	8
101-200	10
201-350	12
351-500	15
501-699	20

Useful milestones:

Level	Total qualifying kills required
10	35
25	109
50	258
100	656
200	1,654
350	3,452
500	5,699
700	9,694

The default configuration contains 100 titles. A new title is reached every seven levels, starting at level 7 and ending at level 700. Levels 1-6 have no title. The active title is always the highest title whose level requirement has been reached.

Progression is configurable in the Progression section of ModConfig/personalstats.json. The early thresholds must be strictly increasing and the tier ranges must continuously cover every level up to MaxLevel - 1. Invalid or incomplete progression configuration is rejected instead of silently producing inconsistent levels.

Changing the progression curve does not replace kill totals. It changes how the existing totals are interpreted, so make a configuration and database backup before changing it.

Which kills count

The server records both the exact runtime entity code and a normalized entity group. By default, obvious non-progression targets are excluded, including players, traders, villagers, armor stands, and straw dummies.

Kills are attributed to the stable PlayerUID, not to the current display name. A renamed player therefore keeps the same statistics, while two different UIDs do not become the same player merely because they used the same name.

Tracked statistics

In addition to total kills and per-entity kill counts, the server-side tracker records activity used by the statistics service, including:

• time played and active/AFK time;
• walking, sprinting, swimming, and mounted distance;
• minimum and maximum height;
• discovered chunks;
• blocks placed and broken;
• crops planted and harvested;
• ores mined and trees felled;
• damage dealt and received;
• deaths grouped by cause;
• temporal storms survived;
• survival time and kill streak records.

Movement samples that look like a teleport, respawn, or dimension change are filtered so they do not inflate distance. The mod also persists placed-block positions for a limited time to stop simple place-break farming. Natural crop growth is handled separately so a grown crop is not incorrectly treated as a freshly placed foreign block.

Frequent events are accumulated in memory and written in batches. Autosave takes a consistent snapshot of changed players and flushes it outside the main game loop. A time-limited final flush runs during clean server shutdown.

Player commands

/mystats

Shows your current level, title, total qualifying kills, progress toward the next level, and the configured number of top entity groups and exact entities.

/ranks

Shows the leaderboard. The default size is 20. Ranking is ordered by level, then total kills, with the player name used only as a final display-order tie breaker.

/chciresetovatstats

Starts a two-step self-reset. The same player must repeat the command within the configured confirmation window, 30 seconds by default. The reset is transactional and the previous state is saved to an audit record. This command affects the invoking player's Personal Stats data; it does not change the Vintage Story account, UID, inventory, claims, or world save identity.

Configuration location

The server creates the active configuration after the first start:

• Windows default: %AppData%\VintagestoryData\ModConfig\personalstats.json
• Dedicated Linux server: <server-data-path>/ModConfig/personalstats.json

The exact server data path depends on how the server was installed. Edit the active file in ModConfig, not a file inside the release ZIP.

Stop the server before changing storage settings. Keep configuration files containing passwords readable only by the server account. Never upload the active configuration to ModDB, source control, Discord, or a support ticket.

Storage option 1: SQLite (default and recommended for simple setups)

New public installations default to SQLite:

{
  "StorageType": "SQLite",
  "SQLite": {
    "FileName": "personalstats.sqlite3"
  }
}

The database is created under the server's mod data directory, normally:

<server-data-path>/ModData/personalstats/personalstats.sqlite3

SQLite is a good choice for one Vintage Story server when no external dashboard or shared database service is required. Back up the SQLite file only while the server is stopped or by using a SQLite-aware backup method; copying a database during active writes can produce an inconsistent backup.

Storage option 2: MariaDB (optional)

Use MariaDB when you deliberately want a separately managed database service, centralized backups, or an external read-only reporting integration. MariaDB is not required for normal gameplay.

1. Prepare a dedicated database and least-privilege account

Run the following as a MariaDB administrator and replace every example value. Do not copy the example password into production.

CREATE DATABASE `vs_personalstats`
  CHARACTER SET utf8mb4
  COLLATE utf8mb4_unicode_ci;

CREATE USER 'vs_personalstats_app'@'GAME_SERVER_IP'
  IDENTIFIED BY 'REPLACE_WITH_A_LONG_RANDOM_PASSWORD';

GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, INDEX
  ON `vs_personalstats`.*
  TO 'vs_personalstats_app'@'GAME_SERVER_IP';

SHOW GRANTS FOR 'vs_personalstats_app'@'GAME_SERVER_IP';

Use the game server's real source IP or a narrowly restricted host pattern. Avoid '%' unless network access is independently restricted and you understand the exposure. The application account does not need global privileges, GRANT OPTION, user administration, or access to other databases.

Version 1.4.0 creates its required tables and indexes automatically. A future release that performs a schema migration may document an additional temporary privilege such as ALTER; do not grant it pre-emptively unless that release requires it.

2. Configure Personal Stats

Start once with SQLite to generate the configuration, stop the server, back up the generated config and current database, then edit only the storage section:

{
  "StorageType": "MariaDB",
  "MariaDB": {
    "Host": "db.example.internal",
    "Port": 3306,
    "Database": "vs_personalstats",
    "User": "vs_personalstats_app",
    "Password": "REPLACE_WITH_THE_REAL_SECRET_OUTSIDE_THE_MOD_ZIP",
    "SslMode": "VerifyFull",
    "ConnectionTimeoutSeconds": 10,
    "CommandTimeoutSeconds": 15,
    "MaximumPoolSize": 10
  }
}

Keep the rest of the generated configuration intact.

3. Choose the TLS mode correctly

• VerifyFull is the preferred mode for a remote database. It encrypts the connection and verifies both the certificate authority and the database hostname. The certificate must be trusted by the game server's operating system and its name must match Host.
• VerifyCA encrypts and validates the certificate authority but does not require a hostname match.
• Required encrypts the connection but does not validate the CA or hostname; it is weaker against an active man-in-the-middle attack.
• None/Disabled does not use TLS. Use it only for a trusted local transport such as database access bound to loopback on the same host.

MariaDB must have TLS configured before a verifying mode can work. Restrict port 3306 with the host firewall or private network; do not expose it broadly to the internet.

4. Start and verify

After starting the server, verify all of the following without printing the password:

• the server log says that Personal Stats started with the selected storage;
• the repository loaded player records successfully;
• /mystats works;
• a qualifying kill changes progress and survives a clean restart;
• SHOW GRANTS contains only the intended database privileges;
• for a remote database, the MariaDB session uses TLS.

The mod uses parameterized queries, transactions, connection pooling, and bounded retries for transient MariaDB errors.

Important: changing storage is not a migration

Switching StorageType selects another independent data store. It does not copy existing statistics between SQLite and MariaDB. If a populated server changes backends without a planned migration, players will appear to start with the data already present in the selected backend. Always stop writes, back up both sides, and use an explicit validated migration procedure.

Database model in plain language

Personal Stats separates stable identity from counters and detailed records:

• player identity is keyed by PlayerUID; the last known name is display data;
• lifetime totals and activity counters are stored separately from per-entity, per-block, and per-death counts;
• progression rows mirror the configured thresholds and titles so external read-only reporting can use the same curve as the game;
• reset audit data preserves the pre-reset snapshot;
• discovered chunks and recent placed-block positions support exploration statistics and anti-farming behavior;
• personal records keep values such as streak and survival milestones.

Database tables are implementation details and may evolve. Integrations should use a separate read-only database account, must not write into Personal Stats tables, and should be tested again after every mod update.

Optional web dashboard integration

The public 1.4.0 release does not include a ready-to-deploy public website, production proxy configuration, database credentials, or deployment files. Dashboard support is disabled by default.

When an administrator explicitly enables WebDashboard.Enabled, the mod can maintain privacy-preserving player linkage for a separately operated dashboard. It stores an HMAC-SHA256 hash of the canonical IP address rather than the readable IP. The HMAC key is created in the mod data directory using the filename configured by IpHashSecretFile.

Treat that key as a secret: keep it outside the ZIP and source control, restrict filesystem permissions, include it in protected backups, and never expose it to the client. Losing or rotating the key breaks continuity of those hashes. This feature is optional and is not needed for levels, nametags, commands, SQLite, or MariaDB storage.

Nametag implementation

The server calculates the level from the same statistics service used by commands and publishes it in a watched attribute on the player entity. The client replaces only the name-tag texture generation through Vintage Story's public name-tag renderer registry.

This preserves the vanilla name-tag background, scaling, render distance, sneaking behavior, and spectator behavior. The prefix refreshes when the player connects, spawns, respawns, or changes level. No Harmony patch is required by this implementation.

Updates and backups

Before updating:

1. stop the server cleanly;
2. back up the world, ModConfig/personalstats.json, and the selected database;
3. read the new release notes for game-version, configuration, and schema changes;
4. replace the old ZIP and keep only one enabled release;
5. start the server and inspect the log;
6. test automatic client download, /mystats, /ranks, one qualifying kill, a respawn, and persistence across a clean restart.

Do not rename the ZIP's internal metadata, change modid, or edit the version to force compatibility. The ModDB version, server version, client version, and network version must agree.

Troubleshooting

Client says Release not found

• Confirm the exact server version exists as an accessible ModDB release under mod ID personalstats.
• Confirm the server ZIP reports version 1.4.0, not only that its filename contains 1.4.0.
• Confirm the release is marked Universal and required on the client.
• Exit Vintage Story, remove only the affected server's cached ModsByServer subdirectory, restart, and join again.
• Check both client-main.txt and server-main.txt without posting passwords or full active configuration files.

Server loads but clients cannot join

• Make sure client and server run compatible Vintage Story versions.
• Remove duplicate or unpacked copies of Personal Stats.
• Confirm that automatic ModDB downloads are available from the server/client network.
• Read the first Personal Stats error in the logs; later messages may only be consequences.

MariaDB Access denied

• Check the MariaDB account's user and host part.
• Use SHOW GRANTS as an administrator.
• Confirm the database name and source IP.
• Confirm the firewall/private-network path.
• Do not paste the password into chat or logs while diagnosing.

MariaDB TLS or certificate error

• Confirm MariaDB actually has TLS enabled.
• With VerifyFull, use a hostname present in the certificate and trusted by the game server OS.
• Do not solve certificate errors by exposing an unencrypted database to the internet.

Level or nametag does not update

• Confirm 1.4.0 loaded on both server and client.
• Verify the kill target is not excluded.
• Test reconnect and respawn synchronization.
• Run /mystats to distinguish server progression from client rendering.
• Check for another mod that replaces the same name-tag renderer.

Statistics disappear after changing storage

Switch back to the original StorageType. The configuration switch does not migrate data. Do not initialize or overwrite either database until backups have been checked.

Privacy and security

• Stable PlayerUID is the identity key; the display name is not rewritten.
• Database work runs only on the server.
• Clients receive the synchronized level, not database credentials.
• MariaDB statements use parameters and transactions.
• The public ZIP contains no active configuration, database, password, API key, log, debug symbols, production path, dashboard secret, or deployment artifact.
• Use a dedicated least-privilege database account and protected backups.
• Redact secrets, public IP addresses, player identifiers, and full configurations from support logs.

Package contents and licenses

The public ZIP contains the compiled Personal Stats mod, the runtime libraries required by the mod, metadata, documentation, and license notices. See LICENSE.md for the mod's terms and THIRD-PARTY-NOTICES.md for bundled dependency notices.

The ZIP should be installed as downloaded. Do not unpack it, add configuration files to it, or redistribute a package containing your server's secrets.

Administrator verification checklist

• Exactly one personalstats ZIP is enabled on the server.
• modid, release version, and network version match ModDB.
• The server starts without a Personal Stats error.
• SQLite works without external setup, or MariaDB uses a dedicated restricted account.
• No active config or secret was added to the ZIP.
• A fresh client automatically downloads the mod and connects.
• /mystats and /ranks return data.
• A qualifying kill updates level progress.
• The colored nametag appears and refreshes after respawn.
• Statistics survive a clean server restart.
• Backups and a rollback copy of the previous ZIP exist.

Official references

• Vintage Story Wiki: Adding mods
• Vintage Story Wiki: Server ModDB commands
• MariaDB: CREATE USER
• MariaDB: GRANT
• MariaDB: Securing connections with TLS
• MySqlConnector: Connection options and SSL modes