⏱️ TECHNICAL SPECIFICATION & ARCHITECTURE: CHRONOSREWARDS

100% Server-Side Playtime & Daily Streak Rewards Engine for Fabric 🚀

1. 🎯 INTRODUCTION AND CORE PHILOSOPHY

ChronosRewards is a high-performance, progression-focused, 100% server-side Fabric mod designed to solve player retention issues in multiplayer environments. By processing all logic via standard networking and container packets, vanilla clients can connect seamlessly and interact with fully color-coded custom menus without downloading any client-side modifications! 🌟

The mod introduces a balanced, highly satisfying system that tracks and rewards players for both daily consistency and long-term playtime grind simultaneously under intense, max-capacity stress testing setups with hundreds of concurrent players. ⚡

2. 🎛️ SYSTEM ARCHITECTURE & CORE MECHANICS

2.1 Dynamic Virtual Inventory Interface (GUI Engine) 📦

The interface maps out raw data directly into container screens using a vanilla GenericContainerScreenHandler structure matching the row parameters provided in the config file.

• Max Capacity Layout: The system allocates a full 6-row chest interface (54 slots total) as designated in the configuration ("rows": 6), maximizing item density for comprehensive progression paths! 📊
• Slot Distribution Matrix: Items are placed directly into explicit slots specified in the JSON mapping.
• Placeholder Normalization: The inventory engine scans item metadata on-the-fly, converting raw string nodes such as {streak}, {playtime}, and {status} (e.g., §aClaimable, §cLocked, §7Claimed) into fully rendered client-side components using formatting markers (§). ✨

2.2 Precise Temporal Streak Validation ⏳

Daily login tracking avoids buggy local system calendar dependencies by calculating the exact epoch timestamp delta (in milliseconds) between the current login and the player's last recorded daily claim:

• minimum_window_millis (20 hours): The threshold preventing players from spam-claiming rewards early. 🛑
• maximum_window_millis (48 hours): If the time delta exceeds this window, the current day-streak counter resets to 1. If the delta falls perfectly between the two limits, the streak increments by 1. 📈

2.3 Instant Join-Item Delivery Matrix 🎁

To welcome players, the mod intercepts player entry handlers. When a connection is initialized, the mod evaluates the player's immediate eligibility status. If the player is cleared for a daily or a milestone reward, the engine directly injects the concrete base item straight into the player's inventory using player.getInventory().insertStack(). 📥

• Overflow Protection: If the player's inventory container is full, the engine drops the item as a physical ItemEntity at the player's exact BlockPos coordinate context, guaranteeing zero data loss! 💎

3. 🛠️ MODDED EXECUTION SPECIFICATIONS BY TARGET FAMILY

3.1 📂 MINECRAFT 26.2.x EXECUTION SPECIFICATION

• Target Architecture: Minecraft 26.2.x using the latest Mojang and Fabric Loader parameters.
• Runtime Environment: Java 25.
• Dependency Constraints: Strictly zero external dependencies; no reliance on the Fabric API framework.

Low-Level Packet Interception 🛰️

The mod injects via a core Mixin targeting ServerPlayNetworkHandler.onPlayerJoin(). Upon execution, it triggers an asynchronous read of the JSON cache, runs the streak calculation delta, and drops any pending entry item blocks straight into the user's data container.

Thread Performance Optimizations 🏎️

Playtime calculations use a global ticking map managed through direct injections into MinecraftServer.tick(). To maximize the performance of processing cores, runtime values are mapped using Java 25 Scoped Values and lightweight Virtual Threads, reducing execution frame drops on tightly packed dedicated architectures.

3.2 📂 MINECRAFT 26.1.x EXECUTION SPECIFICATION

• Target Architecture: Minecraft 26.1.x using the initial 26-family Mojang mappings.
• Runtime Environment: Java 25.
• Dependency Constraints: Strictly zero external dependencies; pure Fabric Loader Mixins.

Registry Evaluation 🔍

Since 26.1.x introduces refined data serialization protocols, item stacks are built dynamically by querying the Registries.ITEM registry inside the server block execution thread. Playtime states are synced natively with Brigadier command execution nodes via CommandRegistrationCallback.

3.3 📂 MINECRAFT 1.21.x GENERAL SPECIFICATION

• Target Architecture: Minecraft 1.21, 1.21.1, 1.21.2, 1.21.3, 1.21.4, 1.21.11.
• Runtime Environment: Java 21.
• Dependency Constraints: Zero Fabric API requirements.

Data Component Registry Integration 🧩

Minecraft 1.21.x completely lacks legacy NBT stacks for menu items, relying instead on type-safe Data Component systems. Item generation maps string components inside the config into type-safe instances using the active registry database. Text modifications are attached via DataComponentTypes.LORE and DataComponentTypes.CUSTOM_NAME parameters.

Thread-Isolated Storage Architecture 💾

To prevent server stuttering during auto-save loops (autosave_interval_ticks), runtime metrics clone data profiles onto an asynchronous storage thread pool. This background engine serializes player playtime maps and timestamps directly into the directory using standard GSON configurations.

4. ⚙️ PRODUCTION MASTER CONFIGURATION (config/chronos_rewards.json)

(Shorter optimized config with exactly 3 reference examples max for clean code generation) 📄

{
  "command": "rewards",
  "autosave_interval_ticks": 1200,
  "menu": {
    "title": "Chronos Max Capacity Stress Test",
    "rows": 6
  },
  "streak": {
    "minimum_window_millis": 72000000,
    "maximum_window_millis": 172800000
  },
  "rewards": [
    {
      "id": "daily_1", 
      "type": "daily", 
      "slot": 0, 
      "required_streak": 1,
      "title": "§aDay 1 Welcome", 
      "item": "minecraft:emerald",
      "lore": ["Streak: {streak}", "{status}"], 
      "commands": ["give {player} emerald 1"]
    },
    {
      "id": "playtime_1m", 
      "type": "playtime", 
      "slot": 27, 
      "required_ticks": 1200,
      "title": "§ePlaytime: 1m Starter", 
      "item": "minecraft:bread",
      "lore": ["Time: {playtime}", "{status}"], 
      "commands": ["give {player} bread 2"]
    },
    {
      "id": "playtime_100h", 
      "type": "playtime", 
      "slot": 53, 
      "required_ticks": 7200000,
      "title": "§4Playtime: 100h Legend", 
      "item": "minecraft:elytra",
      "lore": ["Time: {playtime}", "{status}"], 
      "commands": ["give {player} elytra 1"]
    }
  ]
}

5. ⚡ HARDWARE PERFORMANCE & MEMORY MANAGEMENT

• Target Hardware Environment: High-performance multi-core processors (e.g., Ryzen 7 processors on a 24/7 server architecture).

Memory Profile Reduction via FastUtil 🧠

To completely avoid memory waste from boxing primitive types, all player runtime mappings (UUID to playtime ticks and claim timestamps) are strictly maintained via high-performance primitive maps like Object2LongOpenHashMap from the FastUtil library. This ensures minimal overhead, maintaining ultra-low garbage collection cycle metrics even with high concurrent player counts under max capacity stress tests! 📈

🛠️ HOW TO USE THE JSON CONFIGURATION

• Step 1: Locate your config folder 📂

• Open your Minecraft server framework directory.

• Navigate into the root config folder, and look for the folder designated for the rewards mod (named chronos_rewards).

• Step 2: Open or create the file 📄

• Inside that folder, locate the configuration file named exactly chronos_rewards.json.

• If the file does not exist yet, boot the server instance once to let the backend framework generate it automatically, or manually create a new file named exactly chronos_rewards.json.

• Step 3: Paste the code 📋

• Open the JSON file using an advanced text editor like VS Code or Notepad++.

• Highlight everything inside the file, delete it, and paste the entire production configuration block provided above.

• Ensure no trailing commas or closing brackets are broken so the GSON parsing layer validates the syntax successfully.

• Step 4: Save your changes 💾

• Save the file and safely close your text editor.

• Step 5: Apply it in-game 🔄

• If the server is actively running, execute the mod's native hot-reload command via the server console, or completely restart the engine to refresh the configuration stream.

• Players can now type /[command] (defaults to /rewards) in the chat network to open up the fully populated 6-row reward menu grid tracking their live statistics! 🎮