Razer Lights Control

=====================================================================
                    RAZER LIGHTS CONTROL - CAPABILITIES
                    Minecraft NeoForge 1.21.1 Mod
=====================================================================

OVERVIEW
--------
Razer Lights Control connects Minecraft with Razer Chroma SDK, making your RGB
lights react dynamically to everything happening in the game. The mod uses a
9-layer system where each layer modifies the color from the previous one,
creating rich, context-aware lighting effects.

Requirements: Razer Synapse running with Chroma SDK enabled.

DEBUG VISUAL (F9): - Press F9 to toggle an on-screen overlay showing the current state of every layer in real time. - Displays each layer's input/output color, active modifiers, blend percentages, and final computed RGB value. - Shows the final color that is actually being sent to the Chroma SDK. - Useful for diagnosing why a specific color is being shown on the LEDs and for tuning palette constants in RGBPalette. - Default state: OFF (toggle persists only for the current session).

=====================================================================
LAYER 1: BASE ENVIRONMENT
=====================================================================

Determines the base color according to your current location.

DIMENSIONS:
  - Overworld: Biome grass color adjusted by time of day
  - Nether: Red-orange glow based on local light level
  - The End: Purple glow based on local light level

SURFACE (Overworld):
  - Daytime: Full biome grass color at 85% brightness
  - Dusk: Warm orange-red transition tones
  - Dawn: Cool blue-purple transition tones
  - Night: Dark blue tones that vary with moon phase
    (Full moon = brighter blue, New moon = nearly off)

UNDER TREES (Shade):
  - Daytime: Biome color heavily dimmed (35% brightness)
  - Night: Nearly off, very faint blue-green glow

CAVES:
  - Blue-green dim glow that darkens with depth
  - Minimum 15% brightness even in total darkness (LEDs never fully turn off)
  - Brighter near torches or other light sources

WATER:
  - Blue tones from biome water color
  - Darkens progressively with depth (up to 20 blocks deep)
  - Surface water: Brighter blue
  - Deep water: Dark navy blue
  - Night underwater: Very dark blue

=====================================================================
LAYER 2: BIOME MODIFIERS
=====================================================================
Blends specific colors based on biome type (Overworld only).

  Biome                    Color            Blend
  ------------------------------------------------
  Desert                   Sandy yellow     60%
  Snowy Plains             Ice white-blue   50%
  Ice Spikes               Ice white-blue   50%
  Snowy Taiga              Ice white-blue   50%
  Snowy Slopes             Ice white-blue   50%
  Frozen Peaks             Ice white-blue   50%
  Jagged Peaks             Ice white-blue   50%
  Jungle                   Vivid green      60%
  Bamboo Jungle            Vivid green      60%
  Sparse Jungle            Vivid green      60%
  Cherry Grove             Soft pink        50%
  Swamp                    Dark green       40%
  Mangrove Swamp           Dark green       40%
  Mushroom Fields          Purple-pink      50%
  Badlands                 Red-orange       60%
  Eroded Badlands          Red-orange       60%
  Wooded Badlands          Red-orange       60%
  Deep Dark                Near-black blue  70%
  Lush Caves               Bright green     50%
  Dripstone Caves          Brown            40%

=====================================================================
LAYER 3: WEATHER
=====================================================================
Modifies lighting based on current weather conditions.

RAIN:
  - Gray-blue tint
  - Overall brightness reduced to 65%

SNOW:
  - White-blue tint
  - Overall brightness reduced to 70%

THUNDERSTORM:
  - Heavy darkening (40-50% brightness)
  - Random white lightning flashes (3% chance per tick)

=====================================================================
LAYER 4: PLAYER SITUATION
=====================================================================
Changes color based on what the player is doing.

FLYING WITH ELYTRA:
  - Sky blue color that intensifies with altitude
  - Low altitude: Lighter blue
  - High altitude (256+ blocks): Deep bright blue

SLEEPING:
  - Warm dim orange glow (campfire feeling)
  - Very low brightness (50%)

SPRINTING:
  - Subtle yellow tint indicating speed

CROUCHING/SNEAKING:
  - All colors dimmed to 60% (stealth mode)

RIDING A MOUNT:
  - Subtle brown tint (leather/saddle feeling)

=====================================================================
LAYER 5: PROXIMITY DETECTION
=====================================================================
Detects nearby entities and blocks within 16 blocks (entities) or 5 blocks (blocks).
Cache updates every 20 ticks (1 second) for performance.

BOSS MOBS (highest priority):
  - Ender Dragon: Intense purple glow
  - Wither: Near-black with random white flashes (5% chance)

PORTALS:
  - End Portal nearby: Deep purple glow
  - Nether Portal nearby: Purple-red glow

MOBS:
  - Hostile mobs nearby: Pulsing red glow (sinusoidal pulse)
  - Passive mobs nearby: Subtle green tint

BLOCKS:
  - Spawner nearby: Pulsing green glow
  - Beacon nearby: Bright white boost

=====================================================================
LAYER 6: HELD ITEMS
=====================================================================
Changes color based on the item in your main hand.

  Item                     Color
  ------------------------------------------------
  Diamond (any tool)       Cyan-blue
  Emerald                  Bright green
  Netherite (any tool)     Dark gunmetal gray
  Gold (any tool)          Bright gold/yellow
  Iron (any tool)          Light silver gray

ENCHANTED ITEMS:
  - Any enchanted item gets a purple glow overlay
  - Combines with the base item color

=====================================================================
LAYER 7: STATUS EFFECTS
=====================================================================
Reacts to active potion effects and conditions.
Only one critical status applies at a time (priority order).

CRITICAL STATUS (blocks health layer):
  - Frozen: Bright ice blue that intensifies with freeze level
    (Starts light blue, becomes pure white-blue when fully frozen)
  - On Fire: Intense orange glow

OTHER STATUS (priority order):
  - Poison: Bright green
  - Wither: Dark gray
  - Nausea/Confusion: Purple swirl

ACCUMULATIVE EFFECTS (always apply on top):
  - Blindness: Near-black (10% brightness)
  - Darkness: Very dark (15-20% brightness)
  - Night Vision: 150% brightness boost

=====================================================================
LAYER 8: HEALTH
=====================================================================
Progressive red tint based on remaining health.
Does NOT apply if player has critical status (frozen or on fire).

  Health Range    Effect
  ------------------------------------------------
  100%            No effect
  60-100%         No effect
  40-60%          Slight red tint (30% blend)
  20-40%          Moderate red (50% blend, green/blue reduced)
  0-20%           Intense red (80% blend, green/blue at 10%)

=====================================================================
LAYER 9: LOCAL ENVIRONMENT
=====================================================================
Detects immediate surroundings within 2 blocks.

LAVA NEARBY:
  - Strong orange glow
  - 50% blend with existing color

=====================================================================
TEMPORARY FLASH EVENTS
=====================================================================
These are independent from the layer system and override briefly.

PLAYER DAMAGE:
  - Red flash (255, 40, 40)
  - Duration: 350ms
  - Triggered when player takes damage

EXPLOSION NEARBY:
  - Orange flash (255, 180, 50)
  - Duration: 300ms
  - Triggered when explosion occurs within 20 blocks

MOB KILL:
  - Yellow flash (220, 220, 100)
  - Duration: 200ms
  - Triggered when a mob dies within 10 blocks

=====================================================================
TECHNICAL DETAILS
=====================================================================

COMMUNICATION:
  - Uses Razer Chroma SDK REST API
  - Session-based connection with automatic heartbeat (3 second interval)
  - Automatic reconnection if session is lost

COLOR ENCODING:
  - Custom rotation mapping: (G<<16) | (R<<8) | B
  - Ensures correct channel output through the ChromaLink pipeline

PERFORMANCE:
  - Proximity cache updated every 20 ticks (1 second)
  - Color requests throttled to minimum 150ms interval
  - Background daemon thread for all Chroma SDK communication
  - No impact on main game thread

COMPATIBILITY:
  - Minecraft 1.21.1
  - NeoForge 21.1.0 or higher
  - Java 21+
  - Requires Razer Synapse with Chroma SDK enabled

=====================================================================
EVENT LISTENERS
=====================================================================

  ClientTickEvent.Post          - Main color calculation loop
  LivingIncomingDamageEvent     - Damage flash
  ExplosionEvent.Detonate       - Explosion flash
  LivingDeathEvent              - Mob kill flash