Echoes of Color - Balance Data

The files in this directory are editable tuning data for systems that used to
be hard-coded inside large Java classes. Runtime loaders keep code defaults as a
fallback, and smoke tests validate the editable files.

Editor:
- Run BalanceDataEditor from the compiled tools classpath to edit the first
  supported balance files, or use run_balance_editor.ps1 / run_balance_editor.bat.
- The editor can open, validate, save, and restore built-in defaults for each
  supported balance table.

map_modifier_balance.txt
Format:
type|labelKey|compactLabel|hexColor|devGrantRarity|devGrantCount|standardDropAllowed|bossDropAllowed|riskWeight|rewardWeight|lowMood|highMood|place

Notes:
- type must be a MapItemType that is registered in MapModifierCatalog.
- standardDropAllowed controls normal map modifier drops.
- bossDropAllowed controls boss reward modifier drops.
- Chromatic Siphons use MINIBOSS_SIGIL and should stay false for standard and
  boss drops unless the reward model intentionally changes.
- lowMood, highMood, and place drive generated portal names.

Good next candidates:
- combat_scaling.txt: level/depth damage, health, XP, and reward curves.

miniboss_balance.txt
Format:
scope|id|key|value

Notes:
- GLOBAL rows use id "all" and tune shared miniboss scaling.
- KIND rows use a MinibossKind id such as HEXAGONE or TRAP_A_ZOID.
- Runtime-backed values include health scaling, spawn identity,
  damage/XP/drop multipliers, and wake delay.
- Miniboss skill payloads and player-impacting effect tuning live in
  miniboss_action_balance.txt.

miniboss_action_balance.txt
Format:
minibossKind|action|key|value

Notes:
- Rows tune specific miniboss actions such as HEXAGONE COLLAPSE,
  HEXAGONE PULL_VOLLEY, and TRAP_A_ZOID MINES.
- Runtime-backed values include action cooldowns, selection chance/range,
  projectile counts, field radius/duration/damage, pull strength, hit cadence,
  trap caps/spacing, blink distance, sparks, and effect colors.

boss_balance.txt
Format:
scope|id|key|value

Notes:
- KIND rows use a BossKind id such as PRISM_WARDEN or STAR_REAVER.
- Runtime-backed values include title text key, size, health and damage depth
  scaling, color, phase threshold, attack cadence, active telegraph limits, and
  incoming damage mitigation/soft-cap behavior.
- Boss attack payloads and fire-time projectile aftermath live in
  boss_action_balance.txt.

boss_action_balance.txt
Format:
bossKind|action|key|value

Notes:
- Boss kind uses PRISM_WARDEN or STAR_REAVER.
- Action ids such as PRISM_LINE, STAR_SUNBEAM_SWEEP, and STAR_TRIANGLE_SLAM
  are stable runtime ids, not localized display names.
- Runtime-backed values include telegraph type, width, length, radius, windup,
  damage multipliers, counts, angle spacing, sweep width, delay cadence,
  placement rings, movement locks, particles, sound urgency, fire-time
  projectile payloads, spin knockback, and blocked-placement fallback tuning.
- The editor normalizes partial files against built-in defaults and will save a
  full table after edits.

active_skill_balance.txt
Format:
shape|actionId|key|value

Notes:
- Shape uses SQUARE, CIRCLE, or TRIANGLE. Action ids are stable semantic action
  ids such as SQUARE_BLOCK_RAM or TRIANGLE_PRISM_DAGGERS.
- Runtime-backed values include color cost, base cooldown, damage multiplier,
  unlock level, cooldown reduction cap, and cooldown floor.
- This file tunes the skill loadout and runtime cooldown envelope. Action
  payloads, statuses, surfaces, summons, fields, and follow-up triggers live in
  action_component_balance.txt and the compiled semantic action catalog.

passive_effect_balance.txt
Format:
scope|effectId|key|value

Notes:
- Scope is PASSIVE_EFFECT.
- Passive action components reference these records with passiveEffect=<id>.
- Runtime-backed values include aura path, mote primitive, primary/secondary
  colors, radius, pulse and spin rates, mote count, mote size, and draw alphas.
- This keeps passive action presentation data-driven without adding
  shape-specific rendering branches to ShapeRPG.

action_component_balance.txt
Format:
ownerType|ownerId|actionId|order|componentType|componentId|parameters

Semantic schema:
- Base components are nouns. They should own only the fields needed to function
  as that noun: a PROJECTILE_EMITTER flies, a FIELD occupies an area, a
  TELEGRAPH warns, a SUMMON creates a temporary body, and a MELEE_STRIKE makes
  an immediate contact hitbox.
- Payload parameters describe consequences, such as damage, guard, heal, pull,
  knockback, leech, status effects, shields, or stacks. Long term these should
  increasingly move into payload/status/state components instead of bloating
  projectile and field rows.
- Modifier components describe transformation or repetition. REPEAT_PATTERN
  owns count/formation/spread/spacing. REPEAT_DELAY owns staggered timing.
  Placement patterns own site generation. Chain, pierce, fork, ricochet,
  homing, attach-to-source, and on-hit/on-expire style hooks belong in this
  modifier lane rather than in every base noun.
- Visual descriptors are renderer hooks: visualPrimitive, material, visual,
  motion, particles, and colors. They should not be required for gameplay.
- Trigger and site routing connect components together with trigger,
  triggerFrom, siteSet, siteRef, source, and target.

Minimal component intent:
- TELEGRAPH: shape/source/target/timing/size.
- PROJECTILE_EMITTER: one projectile with shape/source/target/aim/speed/body
  size/lifetime or range. Use REPEAT_PATTERN for volleys.
- FIELD: shape/source/target/size/duration/tick cadence.
- MELEE_STRIKE: contact geometry, placement, and duration.
- SUMMON: spawned body geometry, placement, attachment, and lifetime.
- MOVEMENT: moved actor, destination/heading, distance, speed, and duration.
- STATE or STATUS_EFFECT: target, identity, duration, stacks or limits.
- PLACEMENT_PATTERN: named generated sites for later components to consume.
- REPEAT_PATTERN and REPEAT_DELAY: modifiers for the next compatible component.

enemy_kit_balance.txt
Format:
rowType|role|shapeKit|skill|minNormal|maxNormal|minElite|maxElite|priority|weight|enabled

Notes:
- PREFERRED rows assign the default ranged skill for a role + shape kit.
- SELECT rows choose active skills by role, shape kit, elite state, and distance
  to the player. The lowest matching priority wins; if several matching rows
  share that priority, weight controls random choice among them.
- Set enabled to false or weight to 0 to leave a kit rule documented but unused.
- shapeKit accepts SQUARE, CIRCLE, TRIANGLE, PENTAGON, and SELECT rows may use
  ANY for fallback rules.
- This file controls which existing enemy skills a kit can access. Skill cast
  ranges, windups, cooldowns, and telegraph payloads live in
  enemy_skill_balance.txt.

enemy_skill_balance.txt
Format:
scope|id|key|value

Notes:
- SKILL rows use an enemy skill id such as LUNGE, RAY, or CIRCLE_SPORE.
- Skill ids are validated against EnemyActionId. The editor's Enemy Actions tab
  lists selectable cast skills and non-selectable projectile variants.
- Runtime-backed values include cast ranges, line-of-sight requirements,
  cooldown bases/random ranges, windups, telegraph type, telegraph dimensions,
  target clamp distance, and damage multiplier.
- Enemy bolt, volley, follow-up, and lingering field payloads are authored in
  action_component_balance.txt and executed by the semantic action runtime.

enemy_projectile_balance.txt
Format:
scope|id|key|value

Notes:
- Retired editor snapshot. Runtime code does not load this file.
- Current projectile profiles and payloads live in action_component_balance.txt.
- It remains readable by the balance editor only while old tuning sheets are
  being compared or manually migrated.

enemy_followup_balance.txt
Format:
scope|id|key|value

Notes:
- Retired editor snapshot. Runtime code does not load this file.
- Current follow-up fields, projectiles, statuses, and presentation live in
  action_component_balance.txt.
- It remains readable by the balance editor only while old tuning sheets are
  being compared or manually migrated.

enemy action ids
Notes:
- Selectable cast skills, such as LUNGE and CIRCLE_SPORE, can be referenced by
  enemy_kit_balance.txt and enemy_skill_balance.txt.
- Spark behavior is currently an affix-driven projectile variant, represented by
  SPARK_BOLT and SPARK_VOLLEY. Those ids document the action but are not valid
  kit-selectable skills until Spark becomes a true cast skill.
