Documentation

---

Welcome to Roots v3.0.0

This update focuses on stability, fixing critical bugs from v2.0.0 and expanding the JSON passive system with new effect types. All races are fully data-driven via JSON files.

---

Changelog v3.0.0

Bug Fixes

• Fixed: Switching races no longer leaves effects from the previous race active
• Fixed: JSON races now correctly appear in the race selection screen when connecting to a server
• Fixed: Race effects from a previous session no longer persist after reconnecting
• Fixed: The race scroll item is now only consumed when a race is actually confirmed, not when closing the GUI
• Fixed: Text in the race selection screen no longer wraps incorrectly due to format codes (§)
• Fixed: Potion effects (regeneration, hunger, water breathing, etc.) are now truly permanent — drinking milk no longer removes them
• Fixed: Effect amplifier is now preserved correctly after reapplication (Strength II remains Strength II)

New Passive Types

• water_breathing — Permanent water breathing
• swim_speed — Increased swim speed (Forge attribute)
• fire_resistance — Permanent fire resistance
• speed — Permanent speed with configurable amplifier
• strength — Permanent strength with configurable amplifier

---

How to Create a Race

Place a .json file in:

config/roots/races/

On CurseForge instances:

C:\Users\User\curseforge\minecraft\Instances\YourInstance\config\roots\races\

Each .json file defines one race. You can have as many files as you want — one per race.

---

Full JSON Example

{
  "id": "roots:triton",
  "enabled": true,
  "display_name": "Triton",
  "icon": "minecraft:kelp",
  "description": "A half-aquatic, half-terrestrial being.",
  "dimension": "minecraft:overworld",
  "biome": "minecraft:ocean",
  "passives": [
    {
      "type": "max_health",
      "value": -6.0,
      "operation": "add",
      "enabled": true,
      "description": "-3 hearts"
    },
    {
      "type": "water_breathing",
      "value": 0,
      "operation": "none",
      "enabled": true,
      "description": "Permanent water breathing"
    },
    {
      "type": "swim_speed",
      "value": 3.0,
      "operation": "multiply",
      "enabled": true,
      "description": "Fast swimmer"
    }
  ]
}

---

Root Fields

Field	Type	Required	Description
id	String	✅	Unique race ID — format modid:race_name
enabled	Boolean	✅	Set to false to disable without deleting
display_name	String	✅	Name shown in the UI
icon	String	✅	Item registry name used as icon
description	String	✅	Short description shown in the UI
dimension	String	❌	Dimension ID for spawn teleport. Default: minecraft:overworld
biome	String	❌	Biome to prioritize for spawn. Optional
passives	List	❌	List of passive effect objects

---

Passive Object Fields

Field	Type	Description
type	String	Passive identifier — see table below
value	Number	Magnitude or amplifier — see table below
operation	String	"add", "multiply", or "none" — see table below
enabled	Boolean	Set to false to disable this passive only
description	String	Short text shown in the race selection UI

---

Available Passive Types

Type	Operation	Value	Description
max_health	add or multiply	HP points (2 per heart)	Modifies max health
movement_speed	add or multiply	Speed units	Modifies movement speed
attack_damage	add or multiply	Damage points	Modifies attack damage
swim_speed	add or multiply	Speed multiplier	Modifies swim speed (Forge)
fire_resistance	none	Ignored	Permanent fire resistance
water_breathing	none	Ignored	Permanent water breathing
regeneration	none	Amplifier (0=I, 1=II)	Permanent regeneration
strength	none	Amplifier (0=I, 1=II)	Permanent strength
speed	none	Amplifier (0=I, 1=II)	Permanent speed
burns_in_sun	none	Ignored	Burns under sunlight. Helmet degrades instead of burning
constant_hunger	none	Ignored	Permanent hunger debuff
weakness_in_water	none	Ignored	Takes drowning damage while in water

---

Operation Reference

Operation	Works with	Effect
"add"	Attributes only	Adds a flat value to the base attribute
"multiply"	Attributes only	Multiplies the base attribute by a percentage
"none"	Effects and tick passives	No numeric operation — just activates the effect

---

Common Examples

{ "type": "max_health", "value": 4.0, "operation": "add" }
// +2 hearts (base 20 HP + 4 = 24 → 12 hearts)

{ "type": "max_health", "value": -6.0, "operation": "add" }
// -3 hearts (base 20 HP - 6 = 14 → 7 hearts)

{ "type": "movement_speed", "value": 0.15, "operation": "multiply" }
// +15% movement speed

{ "type": "swim_speed", "value": 3.0, "operation": "multiply" }
// 4x swim speed

{ "type": "strength", "value": 1, "operation": "none" }
// Permanent Strength II (value = amplifier: 0=I, 1=II)

{ "type": "burns_in_sun", "value": 0, "operation": "none" }
// Burns under sunlight — helmet degrades, no helmet = fire

---

Disabling a Race or Passive

To disable a full race without deleting the file:

{ "enabled": false, ... }

To disable a single passive:

{ "type": "burns_in_sun", "enabled": false, ... }

---