R00TS

# 🌿 Roots (Minecraft Forge)

[![Minecraft Version] Minecraft-1.20.1
[![Forge Version] Forge-47.2.0

A change has been made to the mod: you can now add vanilla potion IDs with all their effects. Please report any bugs you encounter. We are currently on version 4.0.0, and we will soon update the GUI to ensure a comfortable user experience.

Roots is a highly optimized race and origins framework built specifically for Minecraft Forge 1.20.1. Inspired by the concept of mechanical heritage mods, Roots leverages Forge's Capability system and advanced network synchronization to deliver flawless performance in multiplayer servers, completely preventing attribute duplication and crashes.

The mod features a hybrid architecture: it includes hardcoded native races and a powerful dynamic loading engine that allows modpack creators to design and integrate custom races using simple JSON files.

---

##  Key Features

Full Persistence (Capability System): Race data is safely attached to the player using persistent server data. Upon death (/kill) or dimension travel, your race and its dynamic states are instantly cloned and synced without any visual or mechanical glitches.
Hybrid Java/JSON Design: Supports built-in static races within the mod core, alongside a dynamic config loader (RaceLoader) that scans an external data folder at runtime.
Zero Server Lag (Tick Optimization): Condition-based passives (such as burning under the sun or ambient status effects) are safely evaluated server-side once per second (every 20 ticks) instead of every microtick, heavily protecting the server's MSPT performance.
Any Vanilla Potion Effect as a Passive: Race passives aren't limited to a fixed list — any vanilla status effect (night_vision, poison, absorption, levitation, etc.) can be granted permanently through JSON, and it's automatically reapplied if something clears it (e.g. a milk bucket).
Synchronized Network: Custom packets (SyncRacePacket and SelectRacePacket) ensure that the client UI and server attributes stay in perfect harmony at all times.

---

##  Gameplay Mechanics (For Players)

Upon entering a new world or using the mod's exclusive item, the Race Scroll (roots:race_scroll), a smooth scrolling user interface (RaceSelectionScreen) will open. From here, players can view the stats, lore, and interactive icons of all available races before choosing their path.

The Race Scroll works in any game mode. The only difference is what happens to the item itself: in Survival, Adventure, or Hardcore it's consumed after picking a race (single use); in Creative it's never consumed, making it the easiest way to preview every race. I recommend handing it out as a quest reward for survival worlds — race progression is planned for a future update, to avoid stepping on other mods that grant player enhancements.

If the chosen race is defined with a dimension (and optionally a biome), selecting it will automatically teleport the player there, searching nearby for a safe spot to land and granting a few seconds of damage immunity on arrival.
---

## Built-in Native Races

Human (roots:human): Versatile and well-balanced. Features the unique human_xp_boost passive, which grants a flat +10% extra experience from all experience orbs. It has no weaknesses.
Zombie (roots:zombie): A slow-regenerating undead. Grants permanent Regeneration and Constant Hunger, at the cost of -2 hearts of maximum health. Its status effect overlays are completely clean, hiding the UI timers to show an infinite duration marker (**:**). However, they will spontaneously combust under direct sunlight if no helmet is equipped.
Skeleton (roots:skeleton): An agile ranged warrior. Starts the journey equipped with a bow and 64 arrows, enjoying a +15% bonus to base movement speed. This comes at a cost, as its maximum health is severely reduced to just 6 hearts (12 health points), and they share the zombie's extreme vulnerability to sunlight.

---

## Modpack Creator Guide (JSON Configuration)

Creating a custom race is incredibly straightforward! You don't need to write a single line of Java code. The mod automatically generates a configuration folder inside your instance root.

Race installation path:

your_instance/config/roots/races/

Any valid .json file dropped into this directory will be automatically parsed and registered by the framework upon client or server startup.

Passive types

Each entry in passives has a type, which can be:

An attribute: max_health, movement_speed, attack_damage, swim_speed — value is the amount, operation is "add" or "multiply".
A special behavior flag: burns_in_sun, constant_hunger, weakness_in_water — no meaningful value, they just switch the behavior on.
Any vanilla potion effect ID (night_vision, poison, absorption, levitation, regeneration, etc.), or modid:effect_name for another mod's effect — value is the amplifier, starting at 0 for level I. It's granted permanently and reapplied automatically if removed. instant_health and instant_damage are supported too, but only trigger once per login/respawn, since Minecraft doesn't treat them as an ongoing status.

### JSON Structure Example (`demon.json`):
{
  "id": "roots:demon",
  "enabled": true,
  "display_name": "Demon",
  "icon": "minecraft:nether_wart",
  "description": "An entity born from the underworld. Possesses devastating attack power, but the sun will incinerate their skin.",
  "dimension": "minecraft:the_nether",
  "biome": "minecraft:nether_wastes",
  "passives": [
    {
      "type": "max_health",
      "value": 6.0,
      "operation": "add",
      "enabled": true,
      "description": "+3 Extra Hearts of Maximum Health"
    },
    {
      "type": "attack_damage",
      "value": 2.5,
      "operation": "add",
      "enabled": true,
      "description": "+2.5 Base Modifier to Physical Attack Damage"
    },
    {
      "type": "fire_resistance",
      "value": 0,
      "operation": "add",
      "enabled": true,
      "description": "Immune to fire and lava"
    },
    {
      "type": "burns_in_sun",
      "value": 0.0,
      "operation": "add",
      "enabled": true,
      "description": "Weakness: Combusts when exposed to direct sunlight"
    }
  ]
}