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