PlayerSync/docs/code-analysis.md

PlayerSync — Code Analysis

1. Project Overview

PlayerSync is a Minecraft Forge 1.20.1 server-side mod that synchronizes player data across multiple Forge servers sharing a centralized MySQL database. It is designed for Forge 群组服 (Forge group server) architectures where players can move between different physical sub-servers and their inventory, equipment, advancements, effects, and other data must follow them seamlessly.

Property	Value
Mod ID	playersync
Minecraft	1.20.1
Forge	47.4.0+
Java	17
License	GPL-3.0
Author	mlus
DB	MySQL (via JDBC mysql-connector-j)

---

2. Project File Structure

src/main/java/vip/fubuki/playersync/
├── PlayerSync.java              # Main mod class, DB initialization
├── CommandInit.java             # `/playersync` command registration
├── config/
│   └── JdbcConfig.java          # All mod configuration (ForgeConfigSpec)
├── sync/
│   ├── VanillaSync.java         # Core player data sync (inventory, effects, advancements, etc.)
│   ├── ChatSync.java            # Cross-server chat sync orchestrator
│   ├── chat/
│   │   ├── ChatSyncServer.java  # TCP chat server (one designated server)
│   │   └── ChatSyncClient.java  # TCP chat client (all servers)
│   └── addons/
│       ├── ModsSupport.java     # Curios, Sophisticated Backpacks & Mekanism integration
│       ├── CuriosCache.java     # Death-safe Curios data caching
│       └── MekanismSupport.java # Mekanism personal chest inventory sync
└── util/
    ├── JDBCsetUp.java           # MySQL JDBC connection & query helper
    ├── LocalJsonUtil.java       # Lightweight map⇔string parser
    └── PSThreadPoolFactory.java # Named thread factory for async DB operations

src/main/resources/
└── assets/playersync/lang/
    ├── en_us.json               # English translations
    └── zh_cn.json               # Chinese translations

src/main/templates/
├── META-INF/mods.toml           # Mod metadata template
└── pack.mcmeta                  # Resource pack metadata

---

3. Architecture

3.1 Deployment Topology

┌──────────────┐   ┌──────────────┐   ┌──────────────┐
│  Server A    │   │  Server B    │   │  Server C    │
│ (forge-1)    │   │ (forge-2)    │   │ (forge-3)    │
│ PlayerSync   │   │ PlayerSync   │   │ PlayerSync   │
└──────┬───────┘   └──────┬───────┘   └──────┬───────┘
       │                  │                  │
       └──────────────────┼──────────────────┘
                          │
                   ┌──────▼──────┐       ┌──────────────┐
                   │   MySQL DB  │◄──────│  Chat Server │
                   │  playersync │       │  (TCP:7900)  │
                   └─────────────┘       └──────────────┘

• All sub-servers read/write player data to the same MySQL database.
• One designated server runs the chat sync server (TCP). All servers connect to it as clients to broadcast chat messages across servers.
• Each server gets a unique server_id (randomly generated on first config load).

3.2 Data Flow Summary

Player Login:
  1. PlayerNegotiationEvent → doPlayerConnect()     [check if already online on another server]
  2. OnDatapackSyncEvent  → restore advancements     [write JSON to disk]
  3. PlayerLoggedInEvent  → doPlayerJoin()           [restore all data from DB]
                             └─ ModsSupport.doCuriosRestore()
                             └─ ModsSupport.doBackPackRestore()
                             └─ MekanismSupport.restorePersonalChestData()

Player Playing:
  4. PlayerEvent.SaveToFile → doPlayerSaveToFile()   [periodic save]
  5. TickEvent.ServerTick   → auto-save every 1200t  [~1 min]
  6. ServerChatEvent        → ChatSyncClient → TCP   [chat broadcast]

Player Death (with keepInventory):
  6. LivingDeathEvent → CuriosCache.tryStoreCuriosToCache()  [snapshot curios]

Player Logout:
  7. PlayerLoggedOutEvent → onPlayerLeave() → store() + curios save
                              └─ if dead: use CuriosCache, else normal save

Server Shutdown:
  8. ServerStoppedEvent → mark server disabled in DB

---

4. Core Module Analysis

4.1 PlayerSync.java — Main Mod Class

Path: src/main/java/vip/fubuki/playersync/PlayerSync.java

The entry point and lifecycle controller.

Method	Trigger	Responsibility
PlayerSync()	Mod construction	Register config, event bus
commonSetup()	FMLCommonSetupEvent	Register JDBC driver, init VanillaSync, conditionally init ChatSync
onServerStarting()	ServerStartingEvent	Create DB, create/alter tables, register server heartbeat, mark players offline
onServerStopping()	ServerStoppingEvent	Shutdown ChatSync

Database tables created on server start:

Table	Purpose
player_data	Core player state (inv, armor, enderchest, advancements, effects, XP, health, food, score, left_hand, cursors, online flag, last_server)
server_info	Server heartbeat (id, enable, data_version, last_update)
curios	Curios inventory (only if Curios mod loaded)
backpack_data	Sophisticated Backpacks NBT data (only if mod loaded)
mekanism_personal_chest	Mekanism personal chest inventory data (only if Mekanism loaded)

The mod runs automatic schema migration — it checks column counts and data types on startup and alters tables as needed.

---

4.2 VanillaSync.java — Core Sync Engine

Path: src/main/java/vip/fubuki/playersync/sync/VanillaSync.java

The largest and most critical class. All methods are static and registered via @Mod.EventBusSubscriber.

Thread Pool

CORE: 2 threads, MAX: 8 threads, QUEUE: 256 (LinkedBlockingQueue)
Rejection policy: CallerRunsPolicy (backpressure)

All DB operations run via executorService.submit(...) to avoid blocking the server thread. The bounded thread pool with CallerRunsPolicy was a fix for #169 — previously an unbounded CachedThreadPool could spawn 25000+ threads under load.

Event Handlers

Event	Method	Behavior
OnDatapackSyncEvent	onDataPackSyncEvent()	Restore advancements JSON from DB to disk, then reload
PlayerNegotiationEvent	onPlayerConnect()	Pre-login check: kick if player is already online on another active server (5-minute heartbeat window)
PlayerLoggedInEvent	onPlayerJoin()	Full data restore: health, food, XP, score, inventory, armor, ender chest, effects, left hand, cursor. Returns generic placeholders for unknown modded items.
PlayerEvent.SaveToFile	onPlayerSaveToFile()	Save current state to DB (skipped if player not yet synced)
PlayerLoggedOutEvent	onPlayerLogout()	Mark offline in DB, save data, handle dead/dying edge cases
LivingDeathEvent	onPlayerDeath()	Cache Curios data (for keepInventory worlds)
TickEvent.LevelTick	onUpdate()	Server heartbeat: update last_update every 1800 ticks (~90s)
TickEvent.ServerTick	onServerTick()	Auto-save all online players every 1200 ticks (~1 min); clean expired Curios cache every 36000 ticks (~30 min)
ServerStoppedEvent	onServerShutdown()	Mark server as disabled in DB

Serialization

• New format (default): Base64 with B64: prefix (B64:<base64-nbt-string>)
• Legacy format: Custom character replacement (|, ^, <, >, ~ for ,, ", {, }, ')
• The mod reads both formats but writes using the configured format (use_legacy_serialization config flag)
• NBT is always tagged with the current data version for forward compatibility

Placeholder Items

When an item from one server's mod set doesn't exist on another, it becomes a paper item with:

• Red italic name: "Item Voucher" (customizable)
• Lore showing the original item ID and stack count
• Stored playersync:original_item_nbt tag for later restoration
• Unique UUID to prevent stacking

XP Calculation

• getTotalExperience() — converts level+progress to absolute XP using Minecraft's level curve formulas (different for levels 0-15, 16-30, 31+)
• setXpForPlayer() — inverse: distributes absolute XP into level+progress, bypassing giveExperience() side effects (events, packets, score)

Dead/Dying Player Edge Case

When a player dies during login (isDeadOrDying()), the mod:

1. Clears the player_synced tag
2. Teleports to respawn point
3. Sets health to 1
4. Updates online status
5. Disconnects player with a reconnect message

This avoids saving corrupted "dead" state as the player's synced data.

---

4.3 ChatSync.java — Chat Sync Orchestrator

Path: src/main/java/vip/fubuki/playersync/sync/ChatSync.java

Starts both the TCP server (if configured as chat server) and TCP client on separate threads.

• ChatSyncServer (port 7900 default) — accepts client connections, broadcasts received messages to all other connected clients
• ChatSyncClient — connects to the chat server, relays ServerChatEvent messages, receives and broadcasts messages from the server to local players
• Uses exponential backoff for reconnect (5s base, up to 60s, max 10 attempts)

---

4.4 JdbcConfig.java — Configuration

Path: src/main/java/vip/fubuki/playersync/config/JdbcConfig.java

All configuration is done via Forge's ForgeConfigSpec system (TOML file on server). Key entries:

Config Key	Default	Description
host	localhost	MySQL host
db_port	3306	MySQL port
use_ssl	false	SSL for DB connection
user_name	playersync	DB username
password	pleaseChangeThisPassword	DB password
db_name	playersync	Database name
Server_id	random int	Unique server identifier
sync_world	[]	World names for advancements (empty = auto-detect)
sync_advancements	true	Enable advancement sync
sync_chat	false	Enable cross-server chat
IsChatServer	false	This server acts as chat relay host
ChatServerIP	127.0.0.1	Chat server address
ChatServerPort	7900	Chat server port
kick_when_already_online	true	Prevent multi-server login
use_legacy_serialization	false	Use old serialization format
item_placeholder_title_override	""	Custom placeholder title
item_placeholder_description_override	""	Custom placeholder description
sync_mekanism_personal_chest	false	Sync Mekanism personal chest inventories

---

4.5 JDBCsetUp.java — Database Utility

Path: src/main/java/vip/fubuki/playersync/util/JDBCsetUp.java

Encapsulates all MySQL operations:

Method	Purpose
getConnection(selectDatabase)	Create JDBC connection; selectDatabase=false for DDL statements
executeQuery()	Run SELECT, returns QueryResult record
executeUpdate()	Run INSERT/UPDATE/DELETE/DDL with database
executeUpdateWithoutDatabase()	Run DDL without default database
update()	Parameterized update (anti-SQL-injection)

The QueryResult record (Connection, PreparedStatement, ResultSet) implements AutoCloseable for try-with-resources support.

Note: SQL queries in VanillaSync use string concatenation for UUID values rather than parameterized queries — this is a potential SQL injection risk if UUIDs could be attacker-controlled (though Minecraft UUIDs are generally safe). The JDBCsetUp.update() method does provide parameterized queries but is not used for the main sync queries.

---

4.6 LocalJsonUtil.java — Lightweight Map Parser

Path: src/main/java/vip/fubuki/playersync/util/LocalJsonUtil.java

A minimal parser that converts Java Map.toString() output back into Map<String, String> or Map<Integer, String>. Used because the item/effect data is stored as {0=..., 1=..., 2=...} format (Java map string representation), not standard JSON.

Uses = as key-value separator (not :), matching Java's Map.toString() format.

---

4.7 PSThreadPoolFactory.java — Named Thread Factory

Path: src/main/java/vip/fubuki/playersync/util/PSThreadPoolFactory.java

Simple ThreadFactory implementation producing threads named PlayerSync-thread-N for easier debugging.

---

4.8 CommandInit.java — Command Registration

Path: src/main/java/vip/fubuki/playersync/CommandInit.java

Registers the /playersync command (permission level 2 required). Currently has a reconnect subcommand that is a stub (returns 0, implementation commented out).

---

4.9 Addon Support (ModsSupport.java & CuriosCache.java)

Curios Integration

• Save: Serializes all Curios slot items as {slotType:index=serializedNbt, ...} map, stored in curios table
• Restore: Clears all Curios slots, reads DB data, deserializes with placeholder support
• Death handling: CuriosCache snapshots Curios inventory on death (keepInventory worlds only), used on logout to prevent empty-save bug from the "Title Screen" disconnect case
• Cache entries expire after 1 hour

Sophisticated Backpacks Integration

• Save: Iterates backpack items via PlayerInventoryProvider.runOnBackpacks(), extracts contentsUuid via NBTHelper, stores NBT in backpack_data table using REPLACE INTO
• Restore: On player join, reads backpack NBT from DB and calls BackpackStorage.get().setBackpackContents() to inject it

Mekanism Integration

Jetpack Mode (already synced): The jetpack mode (NORMAL/HOVER/DISABLED) is stored in the ItemStack NBT at path mekData.mode. PlayerSync's existing serializeNBT() → Base64 pipeline preserves all ItemStack NBT including mekData.*, so jetpack state is automatically synced without any additional code. The PlayerState.activeJetpacks set is purely runtime memory (used for sound/particle effects) and is cleared by Mekanism on player logout — it does not need persistence.

Personal Chest (new sync): Personal chest inventories are stored in Mekanism's world-level SavedData files (<world>/data/mekanism_personal_storage/<uuid>), NOT on the ItemStack. The ItemStack only carries a UUID reference (mekData.personalStorageId). When a player moves between servers, the ItemStack is restored but the target server's SavedData has no inventory for that UUID — the chest appears empty.

MekanismSupport.java solves this by:

• Save: Iterates the player's inventory + ender chest, finds every item with a mekData.personalStorageId tag. Uses reflection to call PersonalStorageManager.getInventoryIfPresent(stack), then serializes all 54 IInventorySlot entries via slot.serializeNBT() into a single NBT CompoundTag, which is Base64-encoded and stored in the mekanism_personal_chest table keyed by storage_id.

• Restore: After inventory is restored (in doPlayerJoin()), iterates the player's items again to find personal chests. For each, queries the DB for saved inventory data. Uses reflection to call PersonalStorageManager.getInventoryFor(stack) to create/retrieve the SavedData entry on the target server, then calls slot.deserializeNBT() on each of the 54 slots.

• Reflection: PersonalStorageManager and PersonalStorageData are in Mekanism's implementation JAR (not the API JAR), so access is via Class.forName() + Method.invoke(). The IInventorySlot interface IS in the API JAR and is used directly at compile time.

• Config: Controlled by sync_mekanism_personal_chest (default false).

Method	Purpose
collectPersonalChestItems(player)	Scan inventory + ender chest for personal chest items, return map of storageId → ItemStack
savePersonalChestData(player)	Serialize each chest's 54 slots, write to DB via REPLACE INTO
restorePersonalChestData(player)	Read from DB, call getInventoryFor(), deserialize slots into target world's SavedData
getInventoryIfPresent(stack)	Reflection wrapper for PersonalStorageManager.getInventoryIfPresent()
getInventoryFor(stack)	Reflection wrapper for PersonalStorageManager.getInventoryFor()
getInventorySlots(inventory)	Reflection wrapper for AbstractPersonalStorageItemInventory.getInventorySlots(null)
getPersonalStorageId(stack)	Extract personalStorageId UUID from ItemStack NBT mekData

5. Synchronized Data

Data	Storage Column	Type	Format
Inventory (36 slots)	inventory	MEDIUMBLOB	{0=B64:..., 1=B64:..., ...}
Armor (4 slots)	armor	BLOB	{0=B64:..., ...}
Off-hand	left_hand	BLOB	Base64 NBT string
Cursor (carried)	cursors	BLOB	Base64 NBT string
Ender Chest (27 slots)	enderchest	MEDIUMBLOB	{0=B64:..., ...}
Advancements	advancements	MEDIUMBLOB	Raw JSON bytes
Active Effects	effects	BLOB	{effectId=B64:nbt, ...}
XP	xp	INT	Absolute XP value
Health	health	INT	HP as integer
Food Level	food_level	INT	0-20
Score	score	INT	Display score
Online Status	online	TINYINT	0 or 1
Last Server	last_server	INT	Server ID
Curios	curios_item (separate table)	BLOB	{slotType:index=B64:..., ...}
Backpacks	backpack_nbt (separate table)	MEDIUMBLOB	Base64 NBT string
Mekanism Personal Chest	inventory_data (separate table)	MEDIUMBLOB	Base64 NBT of 54 slots (via IInventorySlot.serializeNBT())

---

6. Lifecycle Events Summary

Server Starting
├── commonSetup: register JDBC driver, register VanillaSync, (optionally) ChatSync
└── onServerStarting:
    ├── CREATE DATABASE IF NOT EXISTS
    ├── CREATE/ALTER player_data table
    ├── CREATE/ALTER server_info table
    ├── CREATE curios table (if Curios loaded)
    ├── CREATE backpack_data table (if SophisticatedBackpacks loaded)
    ├── CREATE mekanism_personal_chest table (if Mekanism loaded)
    ├── INSERT/UPDATE server_info (heartbeat)
    └── Reset stale online flags

Player Connecting
├── onPlayerConnect: check already-online, kick if needed
├── onDataPackSyncEvent: write advancements JSON to disk
└── onPlayerJoin:
    ├── Restore: health, food, XP, score
    ├── Restore: left_hand, cursors, armor, inventory, enderchest, effects
    ├── Restore: Curios items (ModsSupport)
    ├── Restore: Backpack data (ModsSupport)
    └── Restore: Mekanism personal chest data (MekanismSupport)

Player Playing
├── onPlayerSaveToFile: save() to DB (per save event)
├── onServerTick: auto-save all players every ~1 min
├── onUpdate: heartbeat every ~90s
└── ServerChatEvent → ChatSyncClient → TCP

Player Logging Out
├── onPlayerDeath: cache Curios (if keepInventory)
└── onPlayerLogout:
    ├── Dead/dying: use CuriosCache, don't save new data
    ├── Sync incomplete: skip save (safety)
    └── Normal: store() + ModsSupport.onPlayerLeave()

Server Shutting Down
├── onServerShutdown: mark server disabled
└── onServerStopping: shutdown ChatSync

---

7. Key Design Decisions

1. Thread pool bounded with CallerRunsPolicy — Fix for #169. Prevents thread explosion under concurrent player load by limiting to 8 threads + 256 queue, with natural backpressure.

2. Base64 NBT serialization — Replaced legacy character-replacement format. Backward-compatible read of both formats; config flag to force legacy writes.

3. Placeholder items for missing mods — When a modded item's registry entry doesn't exist on the current server (e.g., player moved from Mekanism server to vanilla), a paper voucher preserves the original NBT so the item can be restored when the player returns.

4. Dead/dying player handling — Special case for players who die during the login process or disconnect via "Title Screen" while dead. Uses CuriosCache to snapshot Curios data on death so it's not lost on logout.

5. Advancement sync via filesystem — Rather than direct NBT manipulation, advancements are synced by writing the JSON file to the world's advancements directory and calling reload(). This leverages Minecraft's built-in advancement loading.

6. Schema auto-migration — The mod checks column existence and data types on startup and alters tables as needed, supporting upgrades without manual SQL.

7. Server heartbeat system — Each server writes last_update every ~90s. Other servers check this to determine if a player is genuinely online elsewhere (5-minute window) before kicking.

8. Reflection-based mod addon support — Third-party mod data whose storage classes are not in the public API JAR (like Mekanism's PersonalStorageManager) are accessed via Class.forName() + Method.invoke(). This avoids hard-compile-dependencies on implementation JARs while still enabling deep data sync at runtime. The compile-time dependency stays on the API JAR only (IInventorySlot, NBTConstants).