PHAYRIOSIS REBORN CONTINUED
INTERNAL MAINTAINER / DEVELOPMENT HISTORY
Last consolidated: 2026-10-03

Purpose
-------
This file records the repair history, failed approaches, compatibility decisions,
testing results, version progression, and continuation notes for Phayriosis Reborn
Continued. Keep a copy of this file inside future source packages / development
archives so later maintenance does not repeat already-discovered mistakes.

Project owner / author metadata:
    leo_san

Primary environment used during this work:
    Minecraft 1.20.1
    Forge 47.4.x
    Java 17

General maintenance rules
-------------------------
1. Preserve existing fixes when working on a new issue. Prefer a narrow patch over
   replacing a large shared procedure unless the shared procedure is proven to be
   the source of the problem.
2. Before replacing a class, compare the new and old JAR entry-by-entry.
3. Be especially careful with:
       EntitybasicunittickingProcedure
       EntityadvancedunittickingProcedure
       ConversionProcedure
       CarrierEntity
       CarrierMultiplierFlightProcedure
4. Do not revive the broad "safe target" helper approach described below.
5. After every patch, verify:
       - ZIP/JAR integrity
       - no unexpected missing entries
       - no unexpected added entries
       - exact list of changed classes
       - version in META-INF/mods.toml
       - author remains leo_san
6. Normal quick gameplay testing is usually done in a SUPERFLAT test world.
   For terrain generation / worldgen features, ALSO test in a normal terrain world.
7. When a player reports a bug, inspect the actual class/procedure before changing
   behavior. Several legitimate reports in this project came from shared MCreator
   procedures whose conditions were technically valid Java but logically broken.


======================================================================
1. ORIGINAL TICKING CRASHES / NULL TARGET BUGS
======================================================================

Initial affected upstream build:
    phayriosisreborn-CLASH_OF_THE_TITANS-0.3.2.3-forge-1.20.1.jar

First confirmed crash:
    java.lang.NullPointerException
    EntityadvancedunittickingProcedure.lambda$execute$9
    around source line 467 in the generated procedure.

Root cause:
    A Mob target was read with Mob.getTarget() and its position was immediately
    accessed. getTarget() is nullable. If the mob had no current target, the code
    dereferenced null and crashed the server tick.

Working repair:
    Add a narrow guard at the beginning of the failing lambda:
        - return if the entity is not a Mob
        - return if Mob.getTarget() is null
        - otherwise run the original body

Result:
    Previously-disabled entities could be enabled/spawned without reproducing the
    original advanced-ticking crash.

Important conclusion:
    This was a general unsafe-null-target pattern, not evidence that one particular
    entity type was inherently broken.


Second confirmed ticking crash
------------------------------
Affected later base:
    phayriosis reborn continued-0.0.1.jar

Crash:
    java.lang.NullPointerException
    EntitybasicunittickingProcedure.lambda$execute$4
    around source line 99.

Root cause:
    Same unsafe Mob.getTarget() pattern, this time in the BASIC ticking procedure.

Important verification:
    The earlier advanced-ticking lambda guard was still present in this JAR, proving
    this was a second occurrence of the same class of bug rather than the original
    fix disappearing.

Correct repair:
    Narrow method-level null guard in lambda$execute$4.
    No new helper method.
    No mass rewrite of unrelated target reads.

Known good build from this stage:
    phayriosis-reborn-continued-0.0.1-TARGETED-FIX.jar


FAILED APPROACH - DO NOT REPEAT
-------------------------------
A broad experimental patch rewrote roughly 289 Mob.getTarget() usages to call a new
helper:
    PhayriosisrebornMod.safePhayTarget(Mob)

The helper attempted to return the real target when non-null and otherwise return
the Mob itself.

This was a mistake.

Observed failure:
    NoSuchMethodError involving PhayriosisrebornMod.safePhayTarget(Mob)

Symptoms:
    Crash immediately when spawning / ticking affected entities, including a
    Patroller in testing.

Why this approach is forbidden:
    - It changed hundreds of unrelated call sites.
    - It introduced a new linkage dependency across many generated classes.
    - Returning the mob itself as a fake target also changes semantics.
    - It was much riskier than patching the actual null-unsafe lambda.

Bad build:
    phayriosis-reborn-continued-0.0.1-FIXED.jar
    (the broad helper build; do not use as a base)

Preferred rule:
    Patch the exact failing generated method or condition only.


======================================================================
2. CARRIER FLIGHT BUG / FLIGHT EXPERIMENT HISTORY
======================================================================

Entity:
    phayriosisreborn:carrier

Original player report:
    Carrier is supposed to fly, but drags/slithers slowly along the ground and
    presents little threat.

Initial inspection:
    CarrierEntity extended Monster rather than a dedicated flying entity class.
    Its model/animation still used a flying animation, but its movement setup did
    not behave as a real aerial attacker.

A long sequence of experiments followed. Keep this history because several of the
failed approaches caused crashes or bad movement.


Attempt A - FlyingMoveControl + FlyingPathNavigation
----------------------------------------------------
Goal:
    Give Carrier conventional vanilla flying navigation.

Problem 1:
    First build produced:
        ClassFormatError
        Method "<init>" in CarrierEntity has illegal signature "(Mob;Level)V"

A corrected class-format build was then made.

Problem 2:
    Runtime crash:
        java.lang.IllegalArgumentException:
        Can't find attribute minecraft:generic.flying_speed

Cause:
    FlyingMoveControl reads generic.flying_speed, but Carrier did not register the
    attribute.

A follow-up added:
    minecraft:generic.flying_speed = 0.3

Decision:
    Abandon this route for Carrier. It required changing the entity's movement
    infrastructure in a way that was less compatible with the mod's existing
    generated behavior.

Do not reintroduce FlyingMoveControl unless the entire Carrier movement design is
being intentionally rewritten and tested.


Attempt B - Copy Immaculate Multiplier flight behavior
------------------------------------------------------
Reference entity:
    phayriosisreborn:immaculate_multiplier

The Multiplier uses an existing flight-related procedure:
    SlooooooowwwwwingdagravityProcedure

This style was preferred because the user liked the Multiplier's existing flight
behavior and speed.

Important design requirement:
    Carrier is MUCH smaller than the Immaculate Multiplier.
    Carrier must actually get into melee range and HIT the enemy.
    It must not simply hover high above the target as a large entity can.

A dedicated CarrierMultiplierFlightProcedure was eventually used to keep the
Multiplier-style motion while adapting attack height / approach for the smaller
Carrier.

Desired behavior:
    - airborne rather than ground-dragging
    - approaches a valid target
    - reaches melee distance
    - does not sit several blocks over a target
    - normal/aggressive speed but not absurdly fast
    - preserve Carrier's own attacks/animations/target logic


Attempt C - old 0.3.2.2 behavior carry-over
-------------------------------------------
Reference supplied:
    phayriosisreborn-0.3.2.2-forge-1.20.1.jar

Discovery:
    Old CarrierEntity.class was byte-for-byte identical to the newer Carrier class.
    Therefore the historic flying difference was not simply a different
    CarrierEntity implementation.

An isolated legacy basic tick helper was tried for Carrier only.

Result:
    Did not solve the flight issue.

Lesson:
    Do not assume older CarrierEntity.class contains a missing flight controller.
    The behavior depended on surrounding/shared procedures.


Attempt D - custom standalone Carrier flight
--------------------------------------------
A custom controller was tried with:
    - gravity disabled
    - small takeoff/hover height
    - direct target pursuit
    - target-height compensation
    - smoothed acceleration

This was later discarded because the preferred direction became:
    use the Immaculate Multiplier's existing flight style as the base.


Working direction - Multiplier-style melee flight
-------------------------------------------------
Carrier was made to use the Multiplier-style airborne procedure while receiving
Carrier-specific vertical pursuit so it can descend/ascend into melee range.

Important values / observations from this stage:
    - Carrier melee reach squared remained around 2.56 rather than copying the
      Multiplier's much larger reach.
    - Multiplier-style movement was intentionally retained.
    - Smaller Carrier should aim near the target body, not hover high above it.


Carrier speed tuning history
----------------------------

At one point players observed roughly:
    ~10 blocks travelled per ~1.5 seconds

This was considered far too fast.

0.0.5:
    Carrier movement-speed attribute was approximately 0.085.

0.0.6 FAILED SPEED ATTEMPT:
    Generic movement speed was changed:
        0.085 -> 0.0425

Result:
    User reported that apparent flight speed DID NOT meaningfully change.

Reason:
    Generic movement_speed was not the correct control point for the actual
    Multiplier-style flight motion.

Lesson:
    Do not assume generic movement_speed alone controls this flight procedure.


0.0.7 FAILED SPEED ATTEMPT:
    Carrier's post-flight X/Z velocity was multiplied by 0.5.

This did reduce motion but BROKE behavior.

User-observed regression:
    - Carrier moved in strange directions.
    - Carrier did not properly face targets.
    - Carrier hovered over enemies.
    - Carrier stopped directly committing to melee attacks.

Cause:
    Horizontal velocity was being modified AFTER the flight procedure / AI steering
    had already calculated movement. This fought navigation and facing.

DO NOT REPEAT:
    Do not globally scale Carrier's X/Z velocity after the flight procedure.


0.0.8 correction:
    - Restored CarrierMultiplierFlightProcedure EXACTLY to the previously working
      0.0.5 behavior.
    - Removed the artificial X/Z velocity scaling.
    - Reduced Carrier melee chase/navigation speed modifier:
          0.8 -> 0.4
    - Fish conversion fix remained intact.

Intent:
    Preserve correct facing, pursuit, vertical movement, and attacking while
    reducing how aggressively the melee goal pushes the Carrier.

Testing note:
    Always spawn a FRESH Carrier after installing a movement change rather than
    relying on an already-loaded entity.


======================================================================
3. BULB -> DOME -> NUCLEUS EVOLUTION
======================================================================

Player report:
    "From phase 4, bulbs are supposed to evolve into domes.
     Domes don't evolve into nuclei but they should."

This report was valid.


Bulb -> Dome
------------
Existing intended logic:
    Once Phase 4 is reached, a sufficiently-grown Bulb should evolve into Dome.

Bulb growth:
    - starts around 20 max health
    - ConversionProcedure can feed/increase nearby Bulbs
    - roughly +5 max health per relevant feeding event
    - intended evolution threshold found at 100 max health

Bug:
    The evolution logic lived in EntityperennialbasicunittickingProcedure, but
    phayriosisreborn:bulb was actually using EntitybasicunittickingProcedure.

Effect:
    Bulb never reached/executed the intended evolution block even when all gameplay
    conditions were satisfied.

Fix:
    Isolated evolution helper attached to Bulb without replacing the current shared
    ticking fixes.

Working condition:
    Phase >= 4
    Bulb max health >= 100
    normal evolution roll / cadence


Dome -> Nucleus
---------------
Existing intended growth:
    Dome starts around 100 max health.
    Conversion logic can add roughly +2 max health.
    Intended evolved threshold: 150 max health.

Bug:
    Existing Dome evolution was hidden behind stacked random gates (approximately
    a 0.1% gate and then another ~1% gate in relevant paths), making evolution so
    rare that players reasonably believed it never happened.

Fix:
    Once the Dome meets the growth requirement, use the intended evolution cadence
    instead of the compounded near-impossible roll.

Target behavior:
    max health >= 150
    approximately 0.1% chance per tick once eligible
    average around 50 seconds, though RNG varies

Preserved restrictions:
    Dome -> Nucleus remains blocked in the original restricted Phayriosis biomes:
        primordial_hellscape
        rotting_forest
        blooming_grove

Preserved behavior:
    Nucleus world counter / progression bookkeeping
    Bulb evolution progression credit

Known working build:
    phayriosis-reborn-continued-0.0.3-EVOLUTION-FIX.jar

User test result:
    Evolution fix reported working.


Fast evolution testing
----------------------
Bulb:
    /phayriosis_phase_set 4
    /summon phayriosisreborn:bulb ~ ~ ~
    /execute as @e[type=phayriosisreborn:bulb,sort=nearest,limit=1] run attribute @s minecraft:generic.max_health base set 100

Dome:
    /summon phayriosisreborn:dome ~ ~ ~
    /execute as @e[type=phayriosisreborn:dome,sort=nearest,limit=1] run attribute @s minecraft:generic.max_health base set 150

Spawning multiple eligible entities speeds up RNG testing.


======================================================================
4. PATROLLER LEAP SPAM
======================================================================

Player report:
    "Patroller constantly jumps."
    "Patrollers leap at targets ignoring the cooldown."

Report verified as correct.

Root cause:
    Patroller leap condition inside EntitybasicunittickingProcedure effectively used:
        Math.random() < 0.98

When grounded with a valid target, this meant a 98% chance EACH eligible tick to
start another leap.

At 20 ticks/second this behaves like no meaningful cooldown at all.

Fix:
    Change the Patroller-specific probability:
        0.98 -> 0.02

Intended effect:
    Approximately one leap every ~2.5 seconds on average while grounded and actively
    pursuing, while still keeping the mob aggressive.

Known build:
    phayriosis-reborn-continued-0.0.3-EVOLUTION-PATROLLER-FIX.jar

User test:
    Reported looking good.


======================================================================
5. PRIMAL HUNTER LEAP SPAM
======================================================================

Player report:
    Hunter also spam-leaps everywhere.

Report verified.

Root cause:
    Same class of logic bug as Patroller, but in EntityadvancedunittickingProcedure:
        Math.random() < 0.98

Fix:
        0.98 -> 0.02

Intent:
    Keep leaping as a combat move without instant re-launch every time it touches
    the ground.

Known build:
    phayriosis-reborn-continued-0.0.3-EVOLUTION-PATROLLER-HUNTER-FIX.jar


======================================================================
6. VANILLA FISH CONVERSION BUG
======================================================================

Player report:
    Fish infected with Phayriosis, especially while dying out of water, repeatedly
    play the conversion effect many times and then despawn instead of becoming a
    converted fish.

Report verified.

Relevant vanilla entities:
    minecraft:cod
    minecraft:salmon
    minecraft:tropical_fish

Important tag:
    These fish are included in the mod's phayriosis:convertable entity tag.

Expected replacement:
    phayriosisreborn:converted_fish

Root cause:
    ConversionProcedure had conversion eligibility/effects for the vanilla fish but
    did not contain a valid replacement branch producing converted_fish.

Result:
    The dying fish could repeatedly trigger conversion sound/particles over
    consecutive ticks, then disappear through normal death/despawn handling without
    producing the converted entity.

Note:
    Player described "20+ times every tick." More precisely, the conversion path was
    repeatedly triggered across consecutive ticks; visually it can look like extreme
    same-tick spam.


0.0.5 first fish fix
--------------------
Added fish conversion handling and metadata cleanup:
    - cod -> converted_fish
    - salmon -> converted_fish
    - tropical_fish -> converted_fish
    - pufferfish intentionally NOT added because it was not in the original
      convertable tag
    - replacement should be created before discarding original fish

User initially confirmed this worked.


Fish regression / weak implementation discovered
-------------------------------------------------
After later Carrier work, user reported fish bug had returned.

Binary comparison showed the fish helper and ConversionProcedure had not actually
been deleted between 0.0.5 and 0.0.6.

The weakness was in the implementation:
    Reflection-based spawning could fail and swallow the failure, allowing the old
    repeated-conversion symptom to return without an obvious crash.

0.0.7 stronger fix:
    Replace reflection with direct Minecraft/Forge spawning calls using the same
    style as the mod's working conversion branches.

Direct replacement logic:
    Spawn phayriosisreborn:converted_fish directly on the server.
    Confirm/create the replacement.
    Remove original vanilla fish after successful conversion.
    No silent reflection failure path.

User result:
    "great the fish fix works"

IMPORTANT:
    Preserve the 0.0.7+ direct fish conversion path in future versions.
    Do not revert to the reflection-based helper.


======================================================================
7. ARMOR STAND TARGETING
======================================================================

Player report:
    Parasites and infected attack armor stands.

Report verified as a systemic targeting problem.

Inspection:
    Roughly 75 Phayriosis entity classes used broad NearestAttackableTargetGoal
    targeting against LivingEntity.

The shared AttackconditionProcedure had a large exclusion list, but ArmorStand was
not excluded.

Because ArmorStand participates as a living-target type for these goals, Phayriosis
mobs could select armor stands as combat targets.

Fix:
    Add a global Phayriosis-only target-change guard:
        ArmorStandTargetFix

Behavior:
    When a Phayriosis entity attempts to change its target to an ArmorStand, clear /
    reject that target.

Scope:
    Phayriosis entities only.
    Vanilla and unrelated mod mobs are not globally changed.

Known build:
    phayriosis-reborn-continued-0.0.9.jar

Regression checks at build time:
    Fish conversion helper unchanged.
    ConversionProcedure unchanged.
    Basic ticking unchanged.
    Advanced ticking unchanged.
    CarrierEntity unchanged.
    Carrier flight helper unchanged.

Version:
    0.0.9

Author:
    leo_san


======================================================================
8. VERSIONING / AUTHOR METADATA
======================================================================

Problem observed in early continued builds:
    JAR filenames could say 0.0.x while META-INF/mods.toml still reported the old
    upstream version (for example 0.3.2.3).

Project rule established:
    The internal mod version must follow the continued-mod release number.

Important progression:
    0.0.3  evolution work
    0.0.4  user baseline before fish/speed/metadata pass
    0.0.5  fish conversion + Carrier tuning + metadata cleanup
    0.0.6  failed generic-speed attempt
    0.0.7  robust direct fish fix + failed post-flight velocity speed attempt
    0.0.8  corrected Carrier steering / chase-speed approach
    0.0.9  armor stand targeting fix

Metadata:
    authors="leo_san"

Do not let future repacks silently restore upstream version metadata.


======================================================================
9. JAR SIZE / REPACKAGING NOTE
======================================================================

At one stage a patched Carrier JAR was approximately 127 KiB smaller than the source
JAR.

This raised a valid concern.

Full entry comparison showed:
    - same number of entries
    - no missing files
    - no added files in that specific build
    - only CarrierEntity.class content differed
    - uncompressed data was not reduced

Reason:
    ZIP/JAR recompression produced a different compressed size.

Lesson:
    File size difference alone does not prove data loss.
    Always compare entry lists and content hashes before declaring a repack safe.


======================================================================
10. POST-0.0.9 METEOR / CONFIG REDESIGN WORK (OCTOBER 2026)
======================================================================

This work began after the earlier gameplay bug-fix line.

Reference findings:
    Existing Phayriosis meteor generation included static worldgen-style meteor
    placement with very low/random generation values.
    A reference parasite implementation used periodic live checks around every
    3,600 ticks, a chance gate, and distant placement around the player/world
    instead of only static terrain generation.

Design direction chosen:
    - move toward much larger live meteor events
    - disable/replace static meteor generation
    - replace unreliable in-game config-screen behavior with a cleaner
      world-creation / per-world settings design
    - implement in phases rather than rewriting everything at once


Phase 1 / 0.0.10
----------------
Goal:
    Begin config/command cleanup.

User decision:
    Two admin commands should remain, but should not have "config" in their names
    since the old in-game config screen was being removed.

Final command names:
    /phayriosis_set_block-spread-speed
    /phayriosis_set_max-infectable-hardness

Old config-open path:
    /phayriosis_config_open
    removed from the intended flow.

FAILED Phase-1 technique:
    An initial bytecode NOP-style patch caused a JVM bytecode verification failure.

Correction:
    Use a conservative approach:
        keep required registration structures intact
        remove only the unwanted OpenConfigCommand behavior/path
        avoid destructive NOP replacement of generated registration bytecode

User test:
    Commands visible and functional.
    World launch behavior worked after correction.


Phase 2 / 0.0.11
----------------
Goal:
    Add persistent per-world Phayriosis settings infrastructure.

Added concept:
    PhayriosisWorldSettings

First Phase-2 build FAILED during world/server startup/login.

Crash:
    java.lang.NoClassDefFoundError:
    net/minecraft/server/level/ServerLevelAccessor

Failure location:
    PhayriosisWorldSettings.mirrorLegacy(...)
    PhayriosisWorldSettings.ensureInitialized(...)
    triggered from mod-variable/player-login handling.

Cause:
    Wrong ServerLevelAccessor class/package assumption in the new code.

Corrected build:
    0.0.11-PHASE2-FIXED

User test result after correction:
    - world creation worked
    - entering/leaving world worked
    - commands were visible with correct names
    - reload/start/end behavior was acceptable

Testing note from user:
    Superflat is normally used for quick validation.


Phase 3 / Phase 4
-----------------
User reported the staged builds as working and approved moving from Phase 3 to
Phase 4, then from Phase 4 to Phase 5.

The exact code-level implementation details of these two stages are not fully
reconstructed in this consolidated record. Before editing those systems, inspect
the relevant Phase-3/Phase-4 build/source rather than guessing.

Known test status:
    world creation and exiting remained functional
    command visibility remained correct


Phase 5 scheduler issue
-----------------------
Observed during testing:
    Advancing the world time did not cause a meteor to appear when expected.

Important diagnosis:
    Minimum-day eligibility was checking monotonic GAME TIME, while the test used
    /time set, which changes DAY TIME.

Therefore:
    /time set could visually move the world to a later day without satisfying a
    minimum-day condition based on gameTime.

Correction strategy:
    - use world DAY TIME for minimum-day eligibility
    - use monotonic GAME TIME for the periodic ~3,600-tick scheduler interval
    - include migration/handling for test worlds whose old scheduler state became
      stuck under the previous logic

Do not combine these two clocks casually:
    dayTime = calendar/day progression and is affected by /time set
    gameTime = monotonic tick counter and is appropriate for repeat intervals


======================================================================
11. TESTING PRACTICES / QUICK REGRESSION CHECKLIST
======================================================================

User commonly validates builds in a SUPERFLAT world.

For general entity fixes, superflat is fine.

For terrain/worldgen features:
    Test BOTH:
        1. superflat for fast startup / commands / crashes
        2. normal terrain world for actual generation behavior

After changing shared ticking:
    - spawn entities that previously crashed
    - test mobs both WITH and WITHOUT a target
    - let world run for several minutes
    - watch server log for ticking exceptions

After Carrier changes:
    - spawn a NEW Carrier
    - test idle flight
    - test acquisition of a nearby target
    - test facing while approaching
    - verify it descends/ascends enough to make melee contact
    - verify it does not hover uselessly above the target
    - verify pursuit speed is not excessive
    - verify no generic.flying_speed crash

After fish changes:
    - test cod
    - test salmon
    - test tropical fish
    - infect with Phayriosis
    - let fish die out of water
    - confirm one clean conversion into converted_fish
    - confirm no repeated conversion effect spam

After evolution changes:
    - Phase 4
    - Bulb at 100 max health
    - Dome at 150 max health
    - test outside restricted Phayriosis biomes

After leap changes:
    - Patroller vs survival target for 20-30 seconds
    - Primal Hunter vs survival target for 20-30 seconds
    - confirm leaps still happen
    - confirm they no longer relaunch every landing

After armor-stand changes:
    - spawn multiple Phayriosis parasites/converted mobs near armor stands
    - no valid player target nearby
    - verify armor stands are ignored


======================================================================
12. IMPORTANT "DO NOT REPEAT" LIST
======================================================================

Do NOT:
    1. Rewrite hundreds of Mob.getTarget() calls to a new helper.
    2. Return the mob itself as a fake target when getTarget() is null.
    3. Reintroduce safePhayTarget.
    4. Use FlyingMoveControl on Carrier without correctly redesigning all required
       attributes/navigation and testing the resulting behavior.
    5. Forget that FlyingMoveControl requires generic.flying_speed.
    6. Scale Carrier X/Z velocity after its flight AI to reduce speed.
       This caused wrong facing, strange directions, and hovering instead of attack.
    7. Assume generic movement_speed alone controls the Multiplier-style Carrier
       flight speed.
    8. Replace current fish conversion with the old reflection-based helper.
    9. Replace current shared ticking procedures merely to fix one entity.
    10. Use destructive bytecode NOP patches in command registration without JVM
        verifier testing.
    11. Use the wrong ServerLevelAccessor package/class in world-settings code.
    12. Use gameTime as a substitute for dayTime when testing minimum world-day
        eligibility through /time set.
    13. Assume a smaller/larger JAR means content was added/removed without doing an
        entry/hash comparison.
    14. Let mods.toml revert to upstream 0.3.2.3 version numbering.


======================================================================
13. KNOWN GOOD / IMPORTANT HISTORICAL BUILDS
======================================================================

Older upstream reference:
    phayriosisreborn-0.3.2.2-forge-1.20.1.jar

Upstream 0.3.2.3 reference:
    phayriosisreborn-CLASH_OF_THE_TITANS-0.3.2.3-forge-1.20.1.jar

First targeted crash repairs:
    phayriosisreborn-CLASH_OF_THE_TITANS-0.3.2.3-forge-1.20.1-FIXED.jar
    phayriosis-reborn-continued-0.0.1-TARGETED-FIX.jar

Bad broad helper build:
    phayriosis-reborn-continued-0.0.1-FIXED.jar
    DO NOT USE AS A MAINTENANCE BASE

Carrier experiment builds:
    0.0.2-CARRIER-FLY-FIX
    0.0.2-CARRIER-FLY-FIX-v2
    0.0.2-CARRIER-FLY-FIX-v3
    0.0.2-CARRIER-MULTIPLIER-FLIGHT
    0.0.2-CARRIER-0322-FLIGHT
    0.0.2-CARRIER-CUSTOM-FLIGHT
    0.0.2-CARRIER-MULTIPLIER-MELEE-FLIGHT

Evolution line:
    0.0.3-EVOLUTION-FIX
    0.0.3-EVOLUTION-PATROLLER-FIX
    0.0.3-EVOLUTION-PATROLLER-HUNTER-FIX

Main continued releases:
    0.0.5 - fish conversion / metadata stage
    0.0.6 - generic Carrier speed attempt; ineffective
    0.0.7 - robust fish conversion + bad post-flight X/Z scaling
    0.0.8 - restore good Carrier flight, reduce chase modifier
    0.0.9 - armor-stand targeting fix

Config/meteor staged work:
    0.0.10 - Phase 1 config/command cleanup
    0.0.11-PHASE2-FIXED - corrected persistent world-settings foundation
    later Phase 3 / Phase 4 / Phase 5 work continued from this line


======================================================================
14. CURRENT MAINTENANCE PRIORITIES
======================================================================

When continuing from a newer Phayriosis build:

A. Preserve the proven crash guards in both basic and advanced ticking.

B. Preserve direct fish conversion for cod/salmon/tropical_fish.

C. Preserve:
       Bulb -> Dome evolution fix
       Dome -> Nucleus evolution fix
       Patroller leap-rate fix
       Hunter leap-rate fix
       armor-stand target exclusion

D. Carrier:
       Do not disturb facing/steering while tuning speed.
       Do not post-scale horizontal velocity.
       Verify actual melee contact after every movement adjustment.

E. World settings / meteor system:
       Keep world-state persistence stable.
       Keep config-screen removal/command naming decisions.
       Treat gameTime and dayTime as different concepts.
       Test generation in normal terrain, not only superflat.

F. Maintain version number and authorship:
       authors="leo_san"
       continued release number should match the JAR/build being shipped.



======================================================================
15. PHASE 5.2 METEOR VISIBILITY / DETERMINISTIC TESTING (2026-10-03)
======================================================================

Observed test result:
    0.0.14.1-PHASE5-CLOCK-FIX loaded and normal world/command behavior worked,
    but the player still did not visibly observe a meteor.

Log timing clarification:
    - Phase was set to 1 at approximately 18:22:05.
    - /time set 168000 was executed at approximately 18:22:18.
    - The game was paused around 18:22:57.
    - With a 50% eligible roll and a 3,600 GAME-TIME-tick retry interval, this test
      provided only one guaranteed eligible roll window before pausing. A failed RNG
      roll therefore looks identical to a renderer failure from the player's point of
      view. Do not diagnose visibility from chance-based testing alone.

EntityCulling 1.9.4 inspection:
    The mod's EntityRendererMixin treats Minecraft Entity field f_19811_ as an
    explicit ignore-culling flag. The live Phayriosis meteor now sets that field true
    in its constructor. This makes the meteor opt out of EntityCulling's entity
    occlusion path and removes EntityCulling as a source of false-negative visibility
    tests.

Phase 5.2 diagnostic additions:
    /phayriosis_meteor_test
        - operator/admin command
        - bypasses minimum day, phase, chance, and scheduler timing
        - still uses the real Phase-5 launch/entity/renderer path
        - clears stale experimental active-state before forcing one launch
        - reports registry readiness and whether addFreshEntity succeeded

    /phayriosis_meteor_status
        - reports registry readiness, current scheduler eligibility, dayTime/gameTime,
          roll/success/pending/active/launch/impact counters, next check, and last target

    Console diagnostics now print:
        - each eligible RNG roll and result
        - successful launch coordinates
        - impact acknowledgement

Temporary visibility aid:
    Thrown-item meteor render scale increased from 6x to 10x for Phase-5 validation.
    This is still not the final meteor model/size.

Continuation gate:
    DO NOT begin destructive Phase 6 crater generation until /phayriosis_meteor_test
    visibly produces a falling meteor and /phayriosis_meteor_status confirms a
    successful launch/impact path.

Permanent documentation rule:
    Every future Phayriosis Reborn Continued build delivered for this project must
    include an updated copy of:
        PHAYRIOSIS_REBORN_CONTINUED_MAINTAINER_HISTORY.txt
    inside the JAR/source package. Append new failures, decisions, validation results,
    compatibility constraints, and continuation notes rather than replacing this
    history with a shorter summary.


======================================================================
16. PHASE 5.3 DIAGNOSTIC COMMAND LINKAGE CRASH (2026-10-03)
======================================================================

Affected build:
    0.0.14.2-PHASE5-DIAGNOSTIC

Observed failure:
    Opening the world-selection/create-world path crashed while server resources were
    preparing, before a test world could be entered.

Crash:
    java.lang.NoSuchMethodError:
    com.mojang.brigadier.builder.LiteralArgumentBuilder.requires(Predicate)
    returning LiteralArgumentBuilder

Failure location:
    PhayriosisMeteorDebugCommand.registerCommand(...)

Root cause:
    The temporary local Brigadier compile stub incorrectly declared inherited builder
    methods with covariant runtime descriptors returning LiteralArgumentBuilder.
    Forge/Minecraft 1.20.1's Brigadier runtime exposes the inherited erased descriptor
    returning ArgumentBuilder; normal Phayriosis commands compile a CHECKCAST back to
    LiteralArgumentBuilder after requires()/executes().

This was a BUILD-STUB / linkage error, not evidence of a meteor scheduler, renderer,
EntityCulling, worldgen, or terrain-generation failure.

Correction in 0.0.14.3-PHASE5-DIAGNOSTIC-FIXED:
    - Recompiled PhayriosisMeteorDebugCommand with the same Brigadier erased method
      descriptors used by Phayriosis's existing working commands.
    - requires(Predicate) now links as returning ArgumentBuilder, followed by CHECKCAST.
    - executes(Command) now links as returning ArgumentBuilder, followed by CHECKCAST.
    - No meteor scheduling, launch, renderer, culling bypass, or impact behavior was
      changed by this correction.

Validation performed before packaging:
    - Compared javap bytecode for the fixed diagnostic command against the existing
      working PhayriosisGetStatusCommand registration pattern.
    - Confirmed both use the runtime-compatible ArgumentBuilder descriptors.
    - Preserved /phayriosis_meteor_test and /phayriosis_meteor_status names.
    - Preserved EntityCulling ignore-culling flag on the meteor.

DO NOT REPEAT:
    When compiling new Brigadier command classes from local stubs, do not model
    LiteralArgumentBuilder.requires()/executes() as runtime methods returning
    LiteralArgumentBuilder. Match the erased ArgumentBuilder return descriptor used by
    Minecraft 1.20.1's actual Brigadier classes. Compare against an existing working
    command class before shipping.

Continuation:
    Phase 5 is still gated on deterministic testing. Enter a world successfully first,
    then run /phayriosis_meteor_status and /phayriosis_meteor_test. Do not begin Phase 6
    crater destruction until the meteor visibly launches and the diagnostic counters
    confirm the launch/impact path.

======================================================================
17. PHASE 5.4 VISUAL / FLIGHT TUNING AFTER SUCCESSFUL TEST (2026-10-03)
======================================================================

Validated build:
    0.0.14.3-PHASE5-DIAGNOSTIC-FIXED

User test result:
    The deterministic /phayriosis_meteor_test path WORKED correctly and the falling
    meteor was visible in the user's normal SUPERFLAT test world.

Log confirmation:
    Multiple forced tests reported:
        launched=true
        registryReady=true
    Each successful launch was followed by an impact acknowledgement several seconds
    later. This confirms the Phase-5 entity registration, server spawn, network spawn,
    client renderer, trajectory ticking, culling bypass, and impact acknowledgement
    path are operational.

Visual feedback from user:
    - 10x thrown-item render scale still looked only around player-sized.
    - Meteor should be dramatically larger, roughly 20x-30x visual scale.
    - Meteor starts much too close to the ground.
    - Current fall reaches the surface in roughly 3-4 seconds.
    - Speed should only be reduced slightly; the main change should come from starting
      much higher in the sky.

0.0.14.4 tuning decision:
    Renderer scale:
        10.0F -> 30.0F

    Vertical launch approach above target:
        118 blocks -> 240 blocks

    Player-relative minimum launch height used by the trajectory calculation:
        player Y + 96 -> player Y + 200

    Flight speed:
        1.80 blocks/tick -> 1.65 blocks/tick

    Horizontal approach:
        remains 92 blocks

Rationale:
    The meteor should read as a major celestial object rather than a player-sized
    projectile. Raising the launch point provides most of the extra visible flight time
    while preserving a forceful descent. Only a modest speed reduction is used so the
    event does not become floaty or slow.

Important:
    This is still Phase 5. No crater, explosion, infection spread, fragments, terrain
    carving, or damage are added by this tuning pass.

Continuation gate:
    Validate 30x visual size, higher sky entry, and longer flight using
    /phayriosis_meteor_test before beginning destructive Phase 6 work. If 30x is too
    large, tune renderer scale only; do not disturb the now-working launch/network path.

Permanent documentation rule remains active:
    Every future Phayriosis Reborn Continued JAR/source delivery must contain an updated
    PHAYRIOSIS_REBORN_CONTINUED_MAINTAINER_HISTORY.txt at the JAR root and internal
    maintainer location.

======================================================================
18. PHASE 5.5 ATMOSPHERIC ENTRY / SCALE / DISTANCE POLISH (2026-10-03)
======================================================================

Validated input build:
    0.0.14.4-PHASE5-TUNED

User visual test:
    The live meteor remained fully functional and visible, but screenshots showed the
    30x thrown-item renderer still read too small for the intended catastrophic-event
    presentation. The user also reported the 1.65 blocks/tick descent looked too slow,
    almost like the meteor was levitating downward.

User-requested direction:
    - restore the original faster flight feel
    - keep the much higher sky entry from 0.0.14.4
    - make the visible meteor about twice the current size
    - move the impact farther from the player
    - add a red-hot atmospheric-friction look on the leading side
    - add visible fire/smoke behind the meteor

0.0.14.5 implementation:
    Renderer scale:
        30.0F -> 60.0F

    Flight speed:
        1.65 blocks/tick -> 1.80 blocks/tick
        This restores the original Phase-5 flight speed while retaining the higher
        launch altitude, so the meteor should feel forceful rather than floaty.

    Launch altitude:
        retained from 0.0.14.4
        target Y + 240 blocks
        player Y + 200 minimum candidate
        clamped below the dimension maximum build height

    Impact distance:
        old untouched Phase-2 defaults: 80-120 blocks
        new cinematic defaults/effective migration: 140-200 blocks

        Existing worlds that are NOT yet world-creation-configured and still carry
        exactly the old 80/120 defaults are migrated to 140/200 the first time the
        live meteor launch path runs. Explicit future world-creation values are not
        overwritten by this migration condition.

    Atmospheric-entry visuals:
        Implemented as a directional particle envelope tied to the meteor's actual
        travel vector rather than as a static texture swap.

        Leading/travel-facing side:
            - dense vanilla FLAME particles
            - LAVA particles for intermittent red/orange hot spots

        Wake/trail:
            - FLAME immediately behind the meteor
            - LARGE_SMOKE close behind
            - normal SMOKE farther down the wake

        Particle emission occurs every other server tick. The effect uses the
        per-player forced ServerLevel particle path for players within 512 blocks,
        because the normal server particle broadcast can be culled at short range and
        the meteor now deliberately lands 140-200 blocks away. Only one meteor is
        allowed active by the scheduler, so this remains bounded and avoids turning
        the effect into an unbounded per-entity particle cost.

    EntityCulling compatibility:
        Preserve Entity.f_19811_ = true ignore-culling behavior from the prior Phase-5
        diagnostics. Do not remove this when changing meteor visuals.

Important implementation note:
    The "red-hot leading face" in this pass is represented by a directional hot-particle
    envelope in front of the meteoric-rock render. It does NOT yet replace the meteor
    with a bespoke animated 3D model/material shader. A dedicated final meteor model
    can be added later if the particle/scale result is still visually insufficient.

Still intentionally NOT implemented:
    - crater carving
    - destructive explosion
    - infection conversion/spread at impact
    - fragments/ejecta
    - terrain scorching
    - impact damage

Testing:
    Use /phayriosis_meteor_test in the normal SUPERFLAT quick-test world. Verify:
        - 60x scale feels suitably massive
        - 1.80 speed no longer reads as levitation
        - high launch altitude still gives enough time to observe the event
        - impact is noticeably farther away than the previous 80-120 block range
        - front flame/lava envelope is visible during descent
        - fire/smoke trail follows behind the meteor rather than appearing ahead
        - /phayriosis_meteor_status still records launch and impact normally

Continuation gate:
    If this visual pass is acceptable, Phase 5 can be locked and Phase 6 can begin the
    actual crater / meteoric mass / ejecta / infection impact generator. Preserve this
    exact working entity, network, scheduler, diagnostic, and culling path while doing
    so.

Permanent documentation rule remains active:
    Every future Phayriosis Reborn Continued JAR/source delivery must contain an updated
    PHAYRIOSIS_REBORN_CONTINUED_MAINTAINER_HISTORY.txt at the JAR root and internal
    maintainer location.


======================================================================
19. PHASE 5.6 WIDE ATMOSPHERIC WAKE + POSITIONAL SOUND PASS (2026-10-03)
======================================================================

Validated input build:
    0.0.14.5-PHASE5-ATMOSPHERIC

User visual test:
    The 60x meteor body size was reported as roughly acceptable. Screenshots showed
    that the atmospheric particles were still concentrated in a tiny narrow line
    through the center of the meteor instead of filling the apparent rear face.

User-requested direction:
    - preserve the current body size and restored 1.80 blocks/tick flight speed
    - make the fire/smoke wake much wider, more turbulent, and more threatening
    - add a positional falling/entry sound
    - add a realistic impact sound/rumble
    - preserve compatibility with Sound Physics Remastered and Explosion Overhaul

0.0.14.6 implementation:
    Meteor body / trajectory:
        - renderer remains 60.0F
        - flight speed remains 1.80 blocks/tick
        - high launch altitude and 140-200 block witness distance remain unchanged

    Atmospheric wake redesign:
        - leading hot envelope spread increased to cover the apparent meteor face
        - rear flame/smoke spread expanded to several blocks instead of ~1 block
        - a perpendicular basis is calculated from the real travel vector
        - two offset side plumes are emitted across the rear face so the wake billows
          rather than forming a single centerline
        - mid and far smoke layers expand farther behind the meteor
        - particle emission remains every other server tick and only one meteor may be
          active, keeping the cost bounded despite the more dramatic effect
        - forced per-player particle packets remain limited to players within 512 blocks

    Falling sound:
        Normal server-side SoundEvent playback is used at the moving meteor position.
        Current layers:
            minecraft:item.elytra.flying  (low-pitched rushing/air movement)
            minecraft:block.fire.ambient (low-pitched atmospheric fire/crackle)
        These are emitted periodically rather than every tick.

    Impact sound:
        A separate non-explosion ground-impact rumble uses:
            phayriosisreborn:rumbling
        It is emitted server-side from the actual impact position.

Sound Physics Remastered compatibility finding:
    sound-physics-remastered-forge-1.20.1-1.4.10 hooks the normal client sound system.
    Therefore meteor sounds must remain ordinary positional SoundEvents sent through
    the standard server Level play-sound path. Do NOT replace them with direct OpenAL,
    direct client-only playback, or a custom bypass if sound-physics compatibility is
    desired.

Explosion Overhaul compatibility finding:
    Explosion-Overhaul-0.2.3.0 injects into vanilla Minecraft Explosion construction /
    finalizeExplosion and routes real Explosion instances through its own server handler,
    including replacement/suppression of explosion sound and its additional effects.

    IMPORTANT FOR PHASE 6:
        The final destructive meteor blast must be produced through a real vanilla/Forge
        Explosion / Level.explode path (or an equivalently hookable standard explosion
        path). Do NOT hard-code the final explosion as only a custom sound + manual block
        deletion, because Explosion Overhaul would not see that as an explosion.

        The 0.0.14.6 phayriosisreborn:rumbling sound is intentionally only an impact /
        ground-shock layer. It is NOT the final explosion bang. This avoids baking in a
        competing explosion sound before Phase 6 and leaves explosion-audio replacement
        to compatible explosion mods when the real blast is added.

Preserved:
    - Phase-4 scheduler and pending-event persistence
    - corrected dayTime/gameTime split
    - /phayriosis_meteor_test and /phayriosis_meteor_status diagnostics
    - EntityCulling ignore-culling flag
    - synchronized server-authoritative meteor entity
    - harmless Phase-5 impact (no terrain damage yet)
    - static meteor worldgen remains disabled

Testing gate:
    Use /phayriosis_meteor_test and verify:
        - wake is broad across/behind the meteor instead of a tiny center line
        - smoke visibly expands farther back from the body
        - falling sound follows the meteor spatially
        - impact rumble comes from the landing position
        - Sound Physics Remastered can still spatialize/occlude the sounds normally
        - no duplicate or broken sound behavior occurs with Explosion Overhaul installed

Permanent documentation rule remains active:
    Every future Phayriosis Reborn Continued JAR/source delivery must contain an updated
    PHAYRIOSIS_REBORN_CONTINUED_MAINTAINER_HISTORY.txt at the JAR root and internal
    maintainer location.

======================================================================
20. PHASE 5.7 MOVING-AUDIO + IMPACT-DISTANCE CORRECTION (2026-10-03)
======================================================================

Validated input build:
    0.0.14.6-PHASE5-WAKE-SOUND

User test feedback:
    - meteor still landed too close to the player
    - the Elytra-based air layer continued for far too long after the meteor impacted
    - the air sound felt player-centered / ambient instead of attached to the moving meteor
    - its character resembled mountain wind rather than a massive projectile passing overhead
    - impact was acceptable, but the final blast must remain compatible with both
      Sound Physics Remastered and Explosion Overhaul

0.0.14.7 correction:
    Impact distance:
        - new per-world default range: 240-320 blocks from the selected player
        - existing non-world-creation-configured worlds carrying the immediately previous
          140-200 range are migrated once to 240-320
        - the player-relative +200 launch-height fallback is intentionally unchanged
        - 1.80 blocks/tick flight speed remains unchanged

    Moving flight audio:
        - REMOVE the old minecraft:item.elytra.flying layer from meteor flight
        - reason: it is a relatively long looping/continuous-style sample and repeated
          emissions overlap, which made the sound linger after impact and read as ambient wind
        - replacement one-shot: minecraft:entity.firework_rocket.launch
        - emitted every 8 meteor ticks from the meteor's CURRENT server position
        - volume 7.0, pitch 0.42
        - atmospheric fire remains minecraft:block.fire.ambient, now every 5 ticks,
          volume 4.5, pitch 0.72
        - both sounds are ordinary positional SoundEvents, so Sound Physics Remastered can
          still perform occlusion/reverb/environmental processing
        - because both are short one-shots tied to repeated CURRENT positions, audio stops
          promptly when the meteor entity impacts/discards instead of continuing as an old
          overlapping Elytra loop

    Phase-5 impact cue:
        - phayriosisreborn:rumbling was replaced by minecraft:entity.generic.explode
        - volume 8.0, pitch 0.78, emitted from the actual target position
        - this makes the temporary impact cue a normal vanilla explosion SoundEvent, which
          Sound Physics can process in the standard sound-engine path

    Explosion Overhaul limitation / Phase-6 requirement:
        - Explosion Overhaul 0.2.3.0 does NOT scale arbitrary custom impact sounds merely
          because they sound like an explosion
        - inspection confirmed its main compatibility hook is injected into
          net.minecraft.world.level.Explosion.finalizeExplosion, where it reads real
          Explosion power/source/center and sends its own distance/environment effects
        - therefore 0.0.14.7 must NOT claim full Explosion Overhaul blast scaling yet
        - Phase 6 MUST create the meteor's real destructive blast through an actual standard
          Minecraft/Forge Explosion path and then REMOVE this temporary manual generic-explode
          cue to prevent duplicate explosion audio
        - do not call Explosion Overhaul internals directly and do not make it a hard dependency;
          the correct compatibility mechanism is to expose a normal Explosion for it to hook

Preserved:
    - 60x visual body size
    - 1.80 blocks/tick flight speed
    - high-altitude approach
    - broad atmospheric particle wake
    - EntityCulling ignore-culling flag
    - /phayriosis_meteor_test and /phayriosis_meteor_status
    - Phase-4 scheduler and dayTime/gameTime clock fix
    - harmless Phase-5 terrain behavior (no crater/block destruction yet)
    - static meteor worldgen remains disabled

Testing:
    Use /phayriosis_meteor_test and verify:
        1. meteor now lands noticeably farther away (240-320 blocks)
        2. projectile whoosh clearly moves through space with the meteor
        3. no long wind/air layer remains after impact
        4. fire crackle follows the meteor instead of the player
        5. impact explosion cue originates at the target location
        6. Sound Physics Remastered still spatializes/occludes the sounds

Permanent documentation rule remains active:
    Every future Phayriosis Reborn Continued JAR/source delivery must contain an updated
    PHAYRIOSIS_REBORN_CONTINUED_MAINTAINER_HISTORY.txt at the JAR root and internal
    maintainer location.

======================================================================
15. PHASE 5 / 0.0.14.8 - PROJECTILE AUDIO + DISTANCE REBALANCE
======================================================================

User result on 0.0.14.7:
    - firework launch sounds were unrealistic for a massive meteor
    - flight audio could not be heard unless very close to the entity
    - 240-320 block impact range was much too far
    - at that distance the meteor approached the edge of normal ticking/tracking and
      visibly rubberbanded/lagged through the air

0.0.14.8 correction:
    Distance / tracking:
        - impact target range rebalanced to 165-185 blocks from selected player
        - legacy non-world-creation-configured 240-320 values migrate to 165-185
        - meteor EntityType tracking range increased from 192 to 384 blocks
        - update interval remains 1 tick
        - high-altitude +240 vertical approach and 1.80 blocks/tick flight speed preserved

    Flight audio:
        - REMOVE minecraft:entity.firework_rocket.launch from meteor flight
        - add original short asset: assets/phayriosisreborn/sounds/meteor_flight.ogg
        - register phayriosisreborn:meteor_flight as fixed-range 256-block SoundEvent
        - play it every 5 ticks from the meteor's CURRENT world position
        - sample is approximately 0.34 seconds long, so it follows the entity through repeated
          positional emissions but cannot linger for many seconds after impact
        - redundant fire ambient audio is disabled; fire/smoke remains visual

    Impact audio:
        - temporary Phase-5 minecraft:entity.generic.explode cue remains
        - volume 16.0, pitch 0.68 so it is audible around the 165-185 block target range
        - stays on normal Minecraft SoundEvent playback so Sound Physics Remastered can process it

    Explosion Overhaul:
        - still do NOT claim full scaling from a standalone sound event
        - inspection confirmed Explosion Overhaul hooks real Explosion.finalizeExplosion and
          can also perform crater/deformation work from explosion power
        - therefore a real Explosion must be introduced with the actual destructive Phase-6
          impact, not prematurely in Phase 5
        - remove the temporary manual generic-explode cue when Phase 6 owns the blast, avoiding
          duplicate audio and allowing Explosion Overhaul to scale the real explosion naturally

Permanent history rule remains active.

======================================================================
16. PHASE 5 / 0.0.14.9 - USER FLYBY AUDIO + DENSER ATMOSPHERIC WAKE
======================================================================

User result on 0.0.14.8:
    - the synthetic/original meteor_flight pulse sounded tonal/alarm-like
    - the meteor body size was acceptable, but the fire/smoke envelope still left too much
      exposed rock and looked visually "naked"
    - user supplied freesound_community-meteor-flyby-14766.mp3 as the preferred sound character
      and requested that it be adapted rather than replaced with another synthetic alarm sound

0.0.14.9 correction:
    Flight audio:
        - REMOVE the prior synthetic meteor_flight.ogg
        - use the user-supplied flyby recording as source material
        - do NOT use the full ~18 second sample as one positional one-shot; that would recreate
          the old post-impact lingering problem
        - extract four short high-energy turbulent sections from the middle of the supplied clip
        - convert each to MONO so Minecraft/OpenAL positional attenuation and Sound Physics
          spatialization can locate the sound at the meteor instead of treating stereo ambience
          as player-centered
        - high-pass near 45 Hz and low-pass near 6.5 kHz to keep pressure/body while removing
          unnecessary extremes
        - slow/pitch the grains slightly downward (~7%) for a heavier projectile character
        - light dynamic compression + normalization + short fades prevent hard looping clicks
        - resulting assets:
              meteor_flight_1.ogg
              meteor_flight_2.ogg
              meteor_flight_3.ogg
              meteor_flight_4.ogg
        - phayriosisreborn:meteor_flight randomly selects one variant per emission
        - each grain is ~0.8 seconds; emission cadence changed from every 5 ticks to every 8 ticks
        - fixed attenuation distance remains 256 blocks
        - this deliberately overlaps short moving positional grains while limiting worst-case
          post-impact residual audio to under about one second

    Atmospheric wake:
        - keep the 60x meteor body size
        - broaden leading hot bow offset/spread from ~3.2/5.5 to ~4.8/9 blocks
        - front flame density 18 -> 36; lava density 4 -> 5
        - rear core moved farther behind (5 -> 7.5 blocks)
        - rear fire density 14 -> 28 with ~10.5-block spread
        - rear smoke density 10 -> 24 with ~12-block spread
        - side plume separation 5.5 -> 9 blocks
        - side flame density 7 -> 16 and smoke density 6 -> 14 per side
        - mid-wake distance 13 -> 17 blocks; mid smoke density 10 -> 24
        - far tail distance 24 -> 31 blocks; tail smoke density 12 -> 28 with ~15-block spread
        - emission remains every other tick to bound packet/particle cost despite the denser look

Preserved:
    - impact target range 165-185 blocks
    - tracking range 384 blocks / update interval 1 tick
    - 1.80 blocks/tick flight speed
    - +240-block high-altitude approach
    - 60x meteor render size
    - temporary vanilla generic explosion cue remains until the real Phase-6 Explosion replaces it
    - EntityCulling bypass
    - debug meteor test/status commands
    - Phase-4 scheduler behavior and Phase-3 static-worldgen removal

Audio provenance note:
    The source audio for these four derived grains was supplied directly by the project owner
    during development. Preserve this fact in maintenance history. If the mod is distributed
    publicly, verify the source clip's redistribution/license requirements separately.

Permanent history rule remains active.



======================================================================
14. PHASE 6 - REAL IMPACT FOUNDATION / 0.0.15
======================================================================

Phase 5 acceptance:
    User confirmed 0.0.14.9 flight visuals/audio now work fine and approved moving on.

Phase 6 foundation decision:
    Preserve the known-good Phase 5 meteor flight exactly and make the landing a genuine
    Minecraft/Forge explosion rather than a manually faked sound/effect.

Implementation:
    - Standard Level explosion, power 12.0, BLOCK interaction.
    - Explosion source is the Phayriosis meteor entity.
    - Phase-5 manual generic explosion sound is silenced to avoid double playback.
    - Real explosion owns damage/sound/explosion-mod hooks.
    - Phayriosis terrain deposition is delayed 40 ticks after impact so asynchronous
      explosion/crater overhaul mods have time to finish before the infected meteor
      material is deposited.
    - Buried meteor ellipsoid: radius 8 horizontal / 5 vertical.
      Outer shell: meteoric_rock.
      Dense inner mass: burrowed_meteoric_rock.
    - Infection scar radius: 20 blocks.
      Surface mix: phayrilesh / burrowed_phayrilesh.
      Sparse active seeds: infestationactive.
    - Infection deposition respects meteorInfectionEnabled.

Compatibility intent:
    Sound Physics Remastered should receive the ordinary positional explosion sound path.
    Explosion Overhaul should see a real Explosion object and its real meteor entity source,
    instead of a fake custom impact sound. No hard dependency on either compatibility mod.

Staging rule:
    Do not add fragments/ejecta/micro-craters until this foundation is tested. If the real
    blast or delayed terrain deposition has a problem, fix that narrowly first.

Testing:
    Superflat can validate launch/impact/crashes quickly, but normal terrain is mandatory
    for actual Phase-6 crater/heightmap/water/slope validation.

======================================================================
17. PHASE 6 / 0.0.16 - LARGE IMPACT + SELF-TICKING METEOR CHUNK LEASE
======================================================================

User test result on 0.0.15:
    - Phase-6 impact foundation successfully launched, impacted, exploded and deposited
      Phayriosis terrain. User described it as a solid foundation.
    - User screenshot/testing showed the landed meteor/crater still felt too small for the
      intended catastrophic event.
    - More importantly, when the player moved far enough away, the live meteor could stop
      mid-air / stop progressing until its chunk became player-ticking again. This caused
      visible freeze/rubberband behavior and made distant impacts unreliable.

0.0.16 design goals:
    1. Meteor flight/impact must not depend on player simulation distance.
    2. Move the target farther away again, but not back to the excessive 240-320 test range.
    3. Increase flying visual size moderately while increasing physical destruction much more.
    4. Keep chunk loading temporary and scoped; never leave permanent forced chunks after a
       normal impact.
    5. Spread large Phayriosis terrain deposition over multiple ticks to avoid one huge server
       tick spike.

Flight / distance changes:
    - Default impact range: 165-185 -> 210-250 blocks.
    - Legacy unconfigured worlds carrying exactly 165-185 migrate automatically to 210-250.
    - Meteor render scale: 60x -> 80x.
    - Flight speed remains 1.80 blocks/tick.
    - High-altitude approach remains +240 blocks.
    - Entity tracking range remains 384 blocks / 1-tick update interval.

Temporary ticking-chunk lease:
    Added PhayriosisMeteorChunkLoader.
    - Uses ForgeChunkManager.forceChunk with the meteor UUID and ticking=true.
    - Tickets are created BEFORE addFreshEntity, so the spawn/path can exist outside ordinary
      player ticking distance.
    - If addFreshEntity fails, all just-created tickets are immediately released.
    - Forced set is deliberately narrow rather than a huge target-centered square:
        * 7x7 impact square (3 chunks radius around target)
        * sampled flight corridor every 10 blocks
        * 3x3 chunk padding around each corridor sample
      For the current ~92-block horizontal approach this is normally far less than blindly
      forcing a 13x13 or 17x17 square.
    - leaseStartX / leaseStartZ are stored on the meteor entity and saved to NBT so the exact
      deterministic ticket set can be reconstructed after save/reload.
    - Chunk tickets are NOT released at the instant of impact. releaseFlightLater holds them
      for 90 additional ticks (~4.5 seconds) so the explosion and delayed/batched terrain work
      can finish even if no player is nearby, then removes the exact ticket set.
    - Normal save/reload during flight is therefore supported: Forge can reinstate the UUID
      tickets, the meteor retains target/start coordinates, and impact later releases them.

Large destructive impact:
    - Genuine Minecraft/Forge explosion power: 12.0 -> 20.0.
      This is the authoritative blast and remains the integration point for Explosion Overhaul
      and Sound Physics rather than adding a second fake explosion.
    - Buried meteor ellipsoid: radius 8x5 -> 15 horizontal / 8 vertical.
    - Superflat/world-minimum correction: the core center is clamped upward so a low superflat
      surface no longer clips most of the meteor below Y=-64. This was one reason the 0.0.15
      landed mass looked much smaller than its configured radius.
    - Infection scar radius: 20 -> 42 blocks.
    - Large inert meteoric/flesh block placement uses update flag 2 to send client updates while
      avoiding a neighbor-update storm; sparse active infestation seeds still use flag 3.
    - Core deposition is split into 2-X-column slices over ~16 server ticks beginning 40 ticks
      after impact.
    - Infection is split into 4-X-column strips over ~22 server ticks beginning 48 ticks after
      impact.
    - The chunk lease remains active until tick +90, after all scheduled Phase-6 terrain strips.

Compatibility/performance notes:
    - Do NOT replace the real Level explosion with custom damage/sound logic; Explosion Overhaul
      compatibility depends on a genuine Explosion path.
    - Do NOT solve distant meteor freezing by permanently forcing a giant area. Keep temporary
      Forge tickets scoped to the flight corridor + impact zone and release them.
    - Do NOT collapse the batched post-impact terrain work back into a single thousands-of-block
      tick unless profiling proves it safe.
    - For terrain tests, use both superflat (quick regression) and normal terrain (real crater,
      heightmap, water/caves/slopes).

Additional stale-ticket cleanup safety:
    - Forge chunk tickets are persistent by design. If the player saves/exits during the short
      90-tick post-impact hold, the meteor entity is already gone and the queued release task
      cannot survive process shutdown.
    - Added PhayriosisMeteorChunkTicketValidation on the MOD event bus. During common setup it
      registers ForgeChunkManager loading validation.
    - On world reload: if PhayriosisMeteorEventData.activeMeteor is TRUE, UUID tickets are kept so
      an in-flight meteor can resume outside player distance. If activeMeteor is FALSE, any
      persisted Phayriosis entity tickets are stale post-impact leases and are removed before
      normal play.
    - This prevents normal save/quit timing from leaving permanent meteor-forced chunks behind.

Permanent history rule remains active.

======================================================================
18. PHASE 6 / 0.0.17 - CATASTROPHIC IMPACT, SHOCKWAVE, CHAMBER + GUARDIAN
======================================================================

User feedback on 0.0.16:
    - The self-ticking/chunk-loaded meteor foundation worked and the impact was good.
    - Physical/visual impact still needed to be roughly 50% larger and much more destructive.
    - Requested sparse magma on the ground, a nuclear-style radial shockwave, stronger audible
      impact behavior through Explosion Overhaul + Sound Physics, a small hollow upper chamber
      with rare ores, a controlled wave of stronger infected, and one Nucleus guardian inside.
    - Follow-up requirement: the chamber Nucleus must have 500 max/current HP.

0.0.17 scale/destruction changes:
    - Flying renderer scale: 80x -> 120x (50% larger).
    - One genuine Minecraft/Forge explosion remains authoritative; power: 20 -> 30.
      Do NOT add a second custom boom. Explosion Overhaul reads the real Explosion power and
      Sound Physics receives the normal positional sound path.
    - Buried meteor ellipsoid: horizontal radius 15 -> 23, vertical radius 8 -> 12.
    - Infection/scorch footprint: radius 42 -> 60.
    - Sparse magma footprint: radius 54, excluding the inner 10 blocks.
    - Impact ticking-chunk square: radius 3 chunks -> 4 chunks.
    - Post-impact ticket hold: 90 -> 120 ticks, long enough for chamber, mobs and guardian.

Shockwave:
    - Added a server-authoritative radial pressure wave 2 ticks after the blast.
    - Push radius: 72 blocks. All loaded entities in the wave are pushed outward; force decays
      with distance and includes a modest vertical lift.
    - Four expanding smoke/pressure rings visualize the wave without creating another explosion.

Meteor interior / loot restraint:
    - The meteor is NOT broadly hollow. A modest upper ellipsoid chamber (roughly 7x5 radius)
      is carved after the body finishes depositing, with a narrow 5-block-diameter-ish top entry.
    - Only 10-13 exposed single ore blocks are seeded on the chamber wall; no veins.
    - Weighted toward iron and biometal. Gold is uncommon; emerald/diamond/crimsonscale are rare;
      plutonium is very rare. This is intentionally not an ore-farm payout.

Post-impact infected wave:
    - Eight exterior infected are spawned after terrain settles: 3 converted humans, 2 patrollers,
      2 infesters, and 1 gory mass.
    - No end-game/immaculate tier entities are included in the exterior wave.

Nucleus chamber guardian:
    - Exactly one phayriosisreborn:nucleus is spawned inside the hollow chamber after carving.
    - Nucleus default max health is 80; this specific guardian receives max health 500 and
      current health 500. This does NOT modify the global Nucleus entity attributes.
    - Spawn occurs after the real blast and chamber carving so the guardian is not buried or
      killed by the meteor's initial explosion.

Compatibility/performance rules:
    - Keep the single real Level explosion as the compatibility point for Explosion Overhaul,
      Sound Physics and other explosion hooks. Do not manually delete a giant raw block cube.
    - Large meteor/infection/magma placement remains batched across ticks.
    - Temporary forced chunks are still released automatically; no permanent chunk loading.
    - Preserve the full PHAYRIOSIS_REBORN_CONTINUED_MAINTAINER_HISTORY.txt in every build.

======================================================================
19. 0.0.17 IMPACT CRASH REGRESSION / 0.0.17.1 LINKAGE FIX
======================================================================

Observed failure:
    - 0.0.17 launched and flew correctly, but crashed the server the instant the meteor reached
      its impact path.
    - Runtime exception: NoSuchMethodError for
        PhayriosisWorldSettings.get(net.minecraft.server.level.ServerLevel)
    - Failure site: PhayriosisMeteorImpactSystem.createImpact, before the new Phase-6 impact
      features could execute.

Root cause:
    - The real Phase-2 settings backend exposes:
        PhayriosisWorldSettings.get(net.minecraft.world.level.LevelAccessor)
      not a ServerLevel-specific overload.
    - 0.0.17's new impact class had been compiled against an incorrect ServerLevel stub signature.
      ServerLevel implements LevelAccessor, so no new overload was ever needed.

0.0.17.1 repair:
    - Retarget ONLY the impact class method reference from get(ServerLevel) to get(LevelAccessor).
    - Preserve the power-30 explosion, 120x renderer, shockwave, magma, expanded meteor body,
      hollow/ores, infected wave, 500-HP Nucleus, and temporary ticking-chunk system unchanged.
    - Update the impact source-note copy to show the LevelAccessor call explicitly.

DO NOT REPEAT:
    - Do not compile newly added classes against guessed convenience overloads. Before shipping,
      inspect the exact method descriptor from the real class in the target JAR with javap.
    - In particular, PhayriosisWorldSettings.get accepts LevelAccessor in this project line.

User test status for 0.0.17.1:
    - Pending. Verify /phayriosis_meteor_test reaches impact without a ticking-entity crash before
      evaluating the new shockwave/chamber/ore/Nucleus features.

======================================================================
20. 0.0.17.2 IMPACT-LINKAGE RETENTION + METEOR TEXTURE DETAIL PASS
======================================================================

Context:
    - 0.0.17 crashed exactly when the meteor reached impact because the new impact class
      linked against a nonexistent PhayriosisWorldSettings.get(ServerLevel) overload.
    - 0.0.17.1 corrected that descriptor to the real get(LevelAccessor) backend method.
    - Before retesting the corrected impact, the user also requested more visual detail
      because the giant meteor looked like a stretched low-resolution texture.

0.0.17.2 changes:
    - RETAIN the 0.0.17.1 impact linkage fix unchanged.
    - Upgrade meteoric rock surface texture from 16x16 to 64x64.
    - New texture remains Minecraft-styled but adds:
        * larger charred stone plates
        * darker fractures and pits
        * subtle rusty/heated mineral flecks
        * more local tonal variation so 120x rendering does not expose giant flat pixels
    - The existing ThrownItemRenderer path is intentionally unchanged in this pass.
      It continues to render meteoric_rock at the tested 120x scale, now using the higher-
      detail material.
    - Since placed meteoric_rock references the same texture, landed meteor blocks also use
      the improved material. This avoids a visual mismatch between flying and landed states.

Preserved without retuning:
    - power-30 genuine Minecraft/Forge explosion
    - Explosion Overhaul / Sound Physics compatibility strategy
    - 120x meteor renderer scale
    - expanded shockwave / magma / chamber / ore system
    - infected spawn wave and special 500-HP Nucleus guardian
    - temporary ticking chunk corridor/impact tickets
    - Phase-5 supplied flyby audio and dense atmospheric wake

Validation rule added:
    - Large rendered block-model entities must not be judged only by normal block-scale
      texture quality. Check the source texture resolution against the renderer multiplier.

User test status for 0.0.17.2:
    - Pending. Primary checks: impact no longer crashes; upgraded meteor material reads
      clearly in flight and after landing; then evaluate the new Phase-6 gameplay features.



======================================================================
21. 0.0.17.3 IMPACT AUDIO / EXPANDING SHOCKWAVE / CHAMBER ORE TUNE
======================================================================

User test after 0.0.17.2:
    - Meteor impact/terrain/chamber/Nucleus foundation works and looks good.
    - Remaining issues: no clearly audible impact sound with Explosion Overhaul installed,
      no meaningful shockwave reaching the observing player, and only ~1-3 ores visibly
      exposed inside the chamber.

Investigation:
    - Phayriosis's own Plutonium Bomb / thermonuclear procedures use very large affected
      radii and explicit loud blast handling, confirming that nuclear-scale effects in this
      mod are intentionally much broader than ordinary explosions.
    - Explosion Overhaul intercepts a real Minecraft Explosion during finalizeExplosion.
      It first classifies the explosion by source entity ID. DEFAULT mode supplies crater,
      concussion/camera effects, distance-aware replacement sounds and Sound Physics
      compatibility; VANILLA mode returns early.
    - The meteor previously passed phayriosisreborn:phayriosis_meteor as the explosion
      source. 0.0.17.3 uses a generic/null source for the authoritative power-30 explosion
      so Explosion Overhaul sees the normal generic DEFAULT path instead of any source-mode
      override. Do not add a second fake boom on top of this; let the real explosion own sound.

Shockwave correction:
    - Old custom push radius: 72 blocks. This could never reach a player observing from the
      normal 210-250 block meteor impact distance, so it appeared as if no shockwave existed.
    - New maximum shockwave radius: 252 blocks.
    - The wave expands in 36-block annuli every 2 ticks instead of pushing everything at once.
    - Each entity is pushed when the pressure front reaches its annulus. Push strength and
      vertical lift decay strongly with distance, leaving the outer edge as a modest shove.
    - Uses Entity.push/additive motion rather than replacing the entity's existing velocity.
    - Each annulus also emits a denser terrain-following particle ring for visual feedback.

Ore chamber correction:
    - Root cause of low visible ore count was not only weighting: the previous radial placer
      put many ore blocks behind the ellipsoidal chamber wall, so most were never exposed.
    - 0.0.17.3 calculates the actual wall radius from vertical position and places ores directly
      against the chamber's inner surface. Duplicate coordinates are rejected.
    - Visible target count raised from 10-13 to 20-25 single blocks.
    - Weighting remains conservative: iron and biometal dominate; copper/gold/crimsonscale are
      secondary; emerald, diamond and plutonium remain rare one-block finds.
    - These remain isolated blocks, never generated as rich veins.

Preserved unchanged:
    - 120x detailed flying meteor texture
    - power-30 destructive explosion
    - large buried meteor body / infection / magma
    - exterior infected wave
    - hollow upper chamber
    - one 500-HP Nucleus guardian
    - meteor chunk-loading/ticking system
    - Phase-5 supplied flyby audio and dense wake

Validation requirements:
    - With Explosion Overhaul installed, impact must produce its distance-aware explosion audio
      and concussion effects through the genuine explosion path.
    - Sound Physics should remain free to spatialize the replacement explosion audio.
    - A player roughly 210-250 blocks away should feel a mild delayed pressure-wave push.
    - Chamber should visibly expose approximately 20-25 single ores, mostly common types.


END OF MAINTAINER HISTORY

======================================================================
14. PHASE 6 FINAL BEHAVIOR PASS / 0.0.17.4
======================================================================
Date: 2026-10-04

User test result from 0.0.17.3:
    - impact sound still not audible at normal viewing distance
    - distant particle shockwave was not visibly readable
    - non-player entities received push but the player did not reliably feel it
    - shockwave should also deal damage with distance falloff
    - more infected defenders requested around the impact
    - chamber ore amount requested at roughly double the prior exposed count
    - meteor launch should immediately advance Phayriosis to Phase 4
    - impact should create a brief red/yellow bright blur/flash compatible with shaders

Reference inspection:
    Ballistix BlastNuclear was inspected. Its nuclear implementation explicitly sends
    high-volume explosion audio and applies entity damage in multiple stages instead of
    relying only on the basic vanilla visual. The Phayriosis implementation borrows the
    general staged-wave principle without introducing a Ballistix dependency.

Impact-audio correction:
    - Keep the real power-30 Minecraft/Forge explosion as the authoritative blast.
    - Add one long-range positional impact layer at the crater itself.
    - Prefer Explosion Overhaul's registered explode_far_power_7_* sound when available.
    - If absent, fall back to Ballistix nuclearexplosion when available, then vanilla
      entity.generic.explode.
    - Volume is intentionally high enough for ~512-block propagation while the sound
      origin remains at the impact, avoiding the earlier bad player-centered audio.
    - Because this is normal Minecraft positional sound playback, Sound Physics can still
      apply occlusion/reverb.

Shockwave redesign:
    - radius remains 252 blocks
    - wave step reduced 36 -> 18 blocks
    - timing changed to 3 ticks per step so the front is visually readable over ~2 sec
    - entity push now scales down continuously with distance
    - living entities also take explosion-type shockwave damage, about 34 damage very
      near the wave origin and about 4 damage at the outer edge
    - ServerPlayer gets a small synchronized positional displacement in addition to the
      velocity impulse so client movement cannot silently erase the effect
    - players receive a local cloud/poof/flash pressure burst when the wave reaches them
      so particle/entity culling cannot make the entire player-facing effect invisible
    - world wave rings now use cloud + poof + large_smoke particles fetched from the
      vanilla registry and sent with long-distance/forced packets

Impact flash / shader compatibility:
    - Immediate and short follow-up red/yellow-hot impact bloom made only from vanilla
      flash, explosion_emitter, flame, lava and large_smoke particles
    - no custom fullscreen shader or framebuffer effect
    - intended to remain visible with Oculus/shader packs and to naturally benefit from
      shader bloom where supported

Ore / defender tuning:
    - exposed chamber ores increased from 20-25 to 42-50
    - weighting heavily favors iron, biometal and copper
    - gold/crimsonscale remain mid-tier
    - emerald, diamond and plutonium each remain only one low-weight pool entry
    - exterior defender wave increased from 8 to 20 entities
    - mix: converted humans, patrollers, infesters, gory masses, assaulters, spitter(s),
      and one carrier; still avoids Immaculate/end-game entities
    - 500 HP Nucleus guardian remains unique inside the chamber

Phase progression:
    As soon as a meteor entity successfully spawns, WorldVariables is immediately set to
    at least 10,000 points and phase 4, then synced. This happens on launch, not impact.

Compatibility/culling note:
    EntityCulling itself primarily targets entities/block entities, not vanilla particles.
    The user's pack also includes particle optimizers, so the new shockwave does not depend
    on only one distant ring; the local forced player effect provides a second reliable
    visual cue.

DO NOT REPEAT:
    - Do not move the impact sound source to the player's coordinates merely to make it loud.
    - Do not rely on Entity.m_5997_ alone for ServerPlayer shockwave feedback.
    - Do not collapse the shockwave back into one instantaneous radius-wide push.



======================================================================
PHASE 6 ENTITY-ONLY METEOR TEXTURE SEPARATION / 0.0.17.5
======================================================================
User correction before testing 0.0.17.4:
    The original Phayriosis meteoric-rock block texture was fine. Only the giant
    airborne meteor entity needed a higher-detail texture.

Exact correction:
    - Restored the world/block meteoric-rock texture exactly from the pre-detail
      Phase-6 build.
    - Normal meteoric-rock blocks AND normal meteoric-rock inventory ItemStacks
      keep the original model/texture.
    - PhayriosisMeteorEntity now marks only its temporary renderer ItemStack with:
          CustomModelData = 170017
    - meteoric_rock item model has one CustomModelData override selecting:
          phayriosisreborn:item/meteor_entity
    - Dedicated flying meteor texture:
          assets/phayriosisreborn/textures/item/meteor_entity.png
    - The dedicated texture is the higher-detail 64x64 charred meteor art.
    - This preserves exact separation: flying meteor visuals can evolve without
      changing the Phayriosis meteoric-rock block or item appearance.

Important maintenance rule:
    Do NOT replace the meteoric-rock BLOCK texture merely to improve the flying
    meteor. Keep flying meteor presentation and world-block presentation separate.

No Phase-6 gameplay behavior, explosion, shockwave, ore, defender, Nucleus,
chunk-loading, flight, scheduler, or audio logic was changed in this pass.

PHASE 6 / 0.0.17.6 - ENTITY TEXTURE SEPARATION VERIFIER FIX
----------------------------------------------------------------
User test of 0.0.17.5 crashed during game initialization.

Crash:
    java.lang.VerifyError: Operand stack overflow
    PhayriosisMeteorEntity.m_7846_() ItemStack method

Cause:
    The 0.0.17.5 texture-separation patch injected CustomModelData bytecode
    into the meteor's ItemStack method but retained max_stack=4. The method
    requires max_stack=5 because the ResourceLocation constructor path can
    hold five operand-stack entries at once. Java 17 verification therefore
    rejected the class before the game finished loading.

Fix:
    - Keep the texture-separation design from 0.0.17.5.
    - Correct m_7846_ Code.max_stack from 4 to 5.
    - No instruction bytes, control flow, meteor mechanics, Phase 6 behavior,
      impact behavior, sound, shockwave, ore counts, defenders, phase switch,
      or chunk-loading logic changed.
    - Original meteoric-rock block texture remains restored byte-for-byte.
    - Normal meteoric-rock item remains normal.
    - Only the airborne meteor's temporary ItemStack uses CustomModelData
      170017 to select assets/phayriosisreborn/models/item/meteor_entity.json
      and the dedicated detailed meteor texture.

Permanent rule:
    Do not patch JVM method bytecode without also recomputing/verifying
    max_stack/max_locals and stack-map requirements. For straight-line patches
    where frames do not change, still calculate max_stack explicitly.


PHASE 6 / 0.0.17.7 - IMPACT PARTICLE RUNTIME LINK FIX
----------------------------------------------------------------
User test of 0.0.17.6 crashed when the meteor impacted over water.

Actual cause:
    The crash was NOT water-specific. The impact flash helper in
    PhayriosisMeteorImpactSystem called the 1.20.1 player-targeted
    ServerLevel particle method with a descriptor returning int:
        m_8624_(ServerPlayer, ParticleOptions, boolean, ..., double)I
    In the actual Forge/Minecraft 1.20.1 SRG runtime this overload
    returns boolean, so impact produced NoSuchMethodError as soon as
    the flash tried to send a targeted particle to a nearby player.

Fix:
    - Correct only the return descriptor from I to Z.
    - No impact/shockwave/bloom behavior was removed.
    - No meteor flight, chunk loading, audio, ores, defenders, Nucleus,
      progression, texture separation, or terrain parameters changed.
    - Water impacts remain supported.

Permanent rule:
    For Minecraft/Forge runtime calls compiled against local stubs, verify
    the exact SRG descriptor INCLUDING return type. A category-1 return
    value can compile and verify locally yet still fail with NoSuchMethodError
    if the runtime return descriptor differs.

===============================================================================
0.0.17.8 - PHASE 6 BALLISTIX NUCLEAR VISUAL / AUDIO REFERENCE PASS
===============================================================================
User test result from 0.0.17.7:
- Core impact / terrain / shockwave gameplay worked.
- Shockwave knockback existed but the visual front passed too quickly to read.
- Impact flash still was not visually apparent at normal meteor viewing distance.
- Impact sound still was not reliably audible.

Ballistix-1.20.1-1.1.1 nuclear implementation was inspected directly as the
reference requested by the maintainer. Important verified details:
- Ballistix nuclear ground shockwave advances at exactly 5 blocks per tick.
- Its damage/effect timing is tied to the same progressing blast lifecycle.
- Its visible ground front uses its custom ParticleOptionsShockwave with a
  ~15 tick particle lifetime, fading alpha, scale ~1.3, and ground-height sampling.
- Its initial nuclear flash is NOT merely Minecraft's vanilla FLASH particle.
  For the first ~10 ticks it renders an oversized white-hot star/core and also
  emits very large white blast-smoke particles.
- Ballistix registers its nuclear explosion SoundEvent with a large fixed range,
  plays it at high volume at the blast, and explicitly ensures nearby players
  receive the nuclear report during the blast process.

Changes in 0.0.17.8:
- SHOCKWAVE_STEP changed from 18 to 5 blocks.
- Shockwave scheduling changed from one 18-block annulus every 3 ticks to one
  5-block annulus every tick, starting 2 ticks after impact.
- Radius remains 252 blocks. The full wave therefore takes about 50 ticks
  (~2.5 seconds) to reach the outer edge, matching Ballistix's 5-block/tick
  propagation speed.
- Damage and knockback continue to be applied by the same annulus that renders
  the wave, so the physical hit now arrives with the visible front.
- Added PhayriosisMeteorBallistixVisualBridge. It is reflection-only and creates
  NO hard Ballistix dependency.
- When Ballistix is installed, the bridge uses Ballistix's registered nuclear
  shockwave and blast-smoke ParticleOptions for the meteor's visual effect.
- Without Ballistix, a forced vanilla cloud/poof/smoke ground ring follows the
  identical 5-block/tick timing, and a much larger shader-safe white/yellow/red
  impact bloom is emitted.
- Impact sound now mirrors the proven Ballistix delivery strategy: a high-volume
  sound at the crater plus a distant directional helper source toward the crater
  for players farther away. The helper source is placed along the direction to
  the impact instead of inside the player so Sound Physics retains direction.
- If Explosion Overhaul is installed, its power-7 CLOSE sound is preferred for
  the crater and its power-7 FAR sound is preferred for distant helper playback.
- If those sounds are absent, Ballistix nuclearexplosion is used when available,
  then Phayriosis largeexplosion, then vanilla generic explosion.
- The authoritative power-30 Minecraft/Forge Explosion remains unchanged, so
  Explosion Overhaul still receives the real Explosion object and may apply its
  own crater/concussion/sound pipeline in addition to this guaranteed report.

Do not regress this timing back to coarse 18-block steps. If shockwave radius is
changed later, preserve 5 blocks/tick by changing the number of scheduled steps,
not by speeding up each step.


===============================================================================
0.0.17.9 - PHASE 6 APOCALYPTIC WORLD-EVENT SCALE / CHUNK-TICK RESTORE
===============================================================================
User test result from 0.0.17.8:
- Ballistix-matched flash/shockwave/audio direction was accepted as a strong baseline.
- Regression found: the meteor again froze when it travelled outside normal player ticking range.
- User requested a somewhat larger meteor, a SUPER long-range shockwave with the existing
  distance-scaled damage/knockback, and a thicker mist-like Ballistix pressure front.

Runtime investigation:
- PhayriosisMeteorChunkLoader still existed in 0.0.17.8 and the meteor entity still called
  releaseFlightLater after impact, BUT PhayriosisMeteorLaunchSystem.tryLaunch no longer
  called PhayriosisMeteorChunkLoader.forceFlight before addFreshEntity.
- This meant no Forge ticking tickets were actually acquired during flight, so the entity
  stopped ticking when it left normal simulation distance.

Fix / tuning in 0.0.17.9:
- Restored PhayriosisMeteorChunkLoader.forceFlight(level, meteor, spawnX, spawnZ, targetX, targetZ)
  immediately before addFreshEntity.
- If addFreshEntity fails, releaseFlight is called immediately so no stale chunk tickets remain.
- Existing delayed post-impact ticket release remains unchanged.
- Flying meteor renderer scale increased modestly from 120x to 150x.
- Shockwave radius increased from 252 to 512 blocks.
- Ballistix-matched propagation speed remains EXACTLY 5 blocks per server tick. Do not speed
  the visual to cover the larger radius. The full pressure front now takes about 103 ticks
  (~5.15 s) to reach the outer edge.
- Existing shockwave damage and knockback still scale by distance, but now across 512 blocks:
  severe near the crater and progressively weaker at extreme range.
- Ballistix visual bridge now renders a thicker mist wall using three closely spaced radial
  bands around the authoritative wavefront. Ballistix shockwave particles use increased scale
  and lifetime, with shader-safe cloud/smoke haze layered around them.
- To keep a 512-block world-event wave from synchronously sampling/loading hundreds of remote
  chunks, detailed ground-ring particles are generated only for ring segments within 150 blocks
  of an actual player. Damage/knockback timing remains global; only unseen visual sampling is culled.
- Impact terrain/core/ores/defenders/Nucleus/explosion power remain unchanged from 0.0.17.8.

Permanent rules:
- Never remove forceFlight from the launch path while keeping releaseFlightLater in the entity.
  Validate the actual tryLaunch bytecode for forceFlight after future launch-system edits.
- Preserve the Ballistix reference speed at 5 blocks/tick even if shockwave radius changes.
- For very large visual shockwaves, avoid heightmap queries for ring sections nobody can see.

===============================================================================
0.0.17.10 - PHASE 6 BRIGHTER IMPACT FLASH / WATER-PATH VALIDATION
===============================================================================
User test result from 0.0.17.9:
- Apocalyptic-scale 150x meteor, restored chunk ticking, 512-block shockwave and
  thicker Ballistix-style mist front worked as intended.
- User requested a substantially brighter impact flash and asked whether water
  impacts are safe.

Changes:
- Ballistix-style white blast-smoke core scale increased from 12.5x to 22x with
  more particles, broader spread and slightly longer lifetime.
- Hot yellow/orange blast-smoke core increased from 8x to 13.5x and doubled in
  density.
- Vanilla/shader-safe flash origins increased from 18 to 42 points and spread
  across a much larger vertical/radial volume.
- Explosion-emitter, end-rod, flame and lava layers were significantly widened
  and increased in density.
- Added minecraft:glow particles as an additional shader-friendly luminous halo
  when that particle type is available.
- No shockwave timing, damage, knockback, chunk loading, crater, ores, defenders,
  Nucleus, flight, audio or progression values changed.

Water-path validation:
- The previous crash observed during a water impact was NOT caused by water. It
  was the incorrect SRG return descriptor for ServerLevel.m_8624_ in the impact
  flash path, fixed in 0.0.17.7.
- Current targeting uses MOTION_BLOCKING_NO_LEAVES, which treats water/fluid
  surfaces as the impact surface; the meteor then replaces fluid blocks normally
  when building the core/infection/magma footprint.
- Meteor body placement clamps Y to the safe world range, so an ocean impact does
  not produce below-world block positions.
- No land-only cast, solid-block-only assumption, or unsafe fluid access exists in
  the current impact path. Water can change the visual crater behavior (vanilla
  water dampens explosion terrain effects and later fluid updates can refill open
  spaces), but it should not inherently crash.
- Continue to test at least one ocean impact after impact-system changes. Do not
  assume a crash occurring over water is fluid-related until the stack trace proves it.

=== 0.0.18 / PHASE 7A - CREATE WORLD METEOR SETTINGS FOUNDATION ===
Phase 6 0.0.17.10 was accepted by the user as the working meteor baseline and is now frozen.
Added a new Forge ScreenEvent-based "Phayriosis Settings" button to vanilla Create World.
Added a separate PhayriosisWorldCreationScreen; do not revive the old MCreator ConfigScreen.
The first functional UI exposes only meteor settings that are already consumed by working runtime code:
meteor enabled, earliest day, minimum phase, chance, check interval, impact-distance preset, and impact infection.
Selections are stored in an ephemeral PhayriosisPendingWorldSettings draft and are armed only when Done is pressed.
On a fresh integrated world, ensureInitialized consumes the draft before legacy mirroring, writes it to
PhayriosisWorldSettings SavedData, sets worldCreationConfigured=true, and clears the draft.
Existing saves must never be overwritten by pending Create World settings. Cancel-to-world-selection/title clears drafts.
The initial Phase 7 screen is intentionally functional/plain; original pixel-art tabs and the Infection/Spawning/Advanced
pages should be layered on only after this plumbing passes startup/create/save/reload tests.


PHASE 7A SCREEN HOOK CORRECTION - 0.0.18.1
Date: 2026-10-04

Observed test result:
- Phase 7A settings backend/world creation flow remained functional.
- The expected Phayriosis Settings button did not appear on Minecraft Create World.

FancyMenu 3.9.3 Forge 1.20.1 was inspected strictly as a reference for robust screen lifecycle behavior.
Key reference lesson:
- Screen customizations must be attached through a lifecycle path that actually fires after screen initialization/reinitialization.
- Forge ScreenEvent.Init.Post is suitable for our small addition and naturally fires again after screen init/resize.

Root cause in 0.0.18:
- PhayriosisCreateWorldClient contains STATIC @SubscribeEvent methods.
- PhayriosisrebornModScreens.clientLoad registered NEW PhayriosisCreateWorldClient() as an INSTANCE on MinecraftForge.EVENT_BUS.
- Forge class-level/static subscribed handlers must be registered using the Class object.
- Therefore onScreenInit/onOpening never ran and no button could be injected.

Correction:
- Register PhayriosisCreateWorldClient.class with MinecraftForge.EVENT_BUS instead of constructing an instance.
- Keep the actual button insertion on ScreenEvent.Init.Post.
- Do not add a FancyMenu dependency or copy FancyMenu implementation code.
- Continue using an original Phayriosis world-creation screen.

Future rule:
- When using static @SubscribeEvent handlers with EVENT_BUS.register, register the Class object, not an instance.
- Validate event registration bytecode before assuming a screen injection failure is caused by screen layout.

PHASE 7A BUTTON LABEL / PLACEMENT - 0.0.18.2
Date: 2026-10-04

User requirement:
- The Create World entry must be a NEW button, not a replacement for any vanilla control.
- Button label must simply be: Phayriosis
- It should sit at the very bottom of the Create World screen, away from the normal centered Create/Cancel controls.

Implementation:
- Base is 0.0.18.1, which fixed the static ScreenEvent subscriber registration by registering PhayriosisCreateWorldClient.class.
- Screen hook remains Forge ScreenEvent.Init.Post so it is reapplied after CreateWorldScreen init/re-init/resize.
- Dedicated button label changed from "Phayriosis Settings" to "Phayriosis".
- Dedicated button remains right-aligned and is moved closer to the lower screen edge (bottom margin 4 px): x=max(8,width-162), y=max(8,height-24), size=154x20.
- No vanilla Create World button is replaced or repurposed.
- FancyMenu 3.9.3 was reference-only; no dependency or copied implementation code was introduced.
- Phase 6 meteor behavior remains frozen/unchanged from the accepted baseline.


===============================================================================
0.0.18.3 - PHASE 7A CREATE-WORLD BUTTON OVERLAP FIX
===============================================================================
Date: 2026-10-04

Observed test result from 0.0.18.2:
- The Phayriosis Create World button appeared successfully.
- At the user's GUI scale/resolution, the bottom-right placement overlapped Minecraft's Cancel button.

Correction:
- Keep the entry as a completely separate new button labelled exactly "Phayriosis".
- Move it from the bottom-right to the bottom-left screen edge, which is empty in vanilla Create World and safely outside the centered Create/Cancel footer controls.
- New placement: x=8, y=max(8,height-24), size=120x20.
- Continue using ScreenEvent.Init.Post so placement is recalculated after init/re-init/resize.
- Do not modify, replace, hide, move or repurpose the vanilla Create or Cancel buttons.
- FancyMenu remains reference-only; there is no runtime dependency.
- Phase 6 meteor/world-event behavior remains frozen and unchanged.

Permanent UI rule:
- Do not anchor Phayriosis over the vanilla centered footer row. Keep the Create World entry in a dedicated edge/corner slot with explicit spacing from vanilla controls.


[0.0.18.4 / Phase 7A] Create World Phayriosis button anchored beneath Allow Cheats
- User reported 0.0.18.3 bottom-left placement still overlapped another control.
- Placement is now discovered from the actual CreateWorldScreen listener widgets.
- Finds the Allow Cheats / Allow Commands AbstractWidget by its rendered label, copies its X/width, and places Phayriosis exactly 4 px below its bottom edge.
- Avoid fixed corner/footer placement in future builds.


=== 0.0.18.5 - Phase 7A Game-tab-only Phayriosis button ===
User test of 0.0.18.4 confirmed the Phayriosis button was positioned correctly beneath Allow Cheats on the Game tab, but it reappeared/followed when changing to World or More. Root cause: onScreenInit still had a generic fallback placement path whenever the Allow Cheats/Commands anchor was absent.

Fix: the fallback path was removed. The Phayriosis button is now injected only when the actual Allow Cheats / Allow Commands widget exists in the active Create World tab. If that anchor is absent, the handler returns without adding the button. Do not reintroduce a generic fallback position for this button.

No meteor, impact, shockwave, worldgen, entity, or Phase 6 gameplay code changed.


=== 0.0.18.6 - Phase 7A Game-tab verifier repair ===
Date: 2026-10-04

Observed failure in 0.0.18.5:
- Forge failed during sided/client setup before the title screen.
- Java 17 VerifyError in PhayriosisCreateWorldClient.onScreenInit: "Expecting a stack map frame" at bytecode offset 143.
- Root cause was an unsafe post-compile control-flow patch used to remove the generic fallback path. The branch bytes changed, but the old StackMapTable was left behind.

Correction:
- Recovered the exact Phase 7A Java source embedded in the jar.
- Recompiled PhayriosisCreateWorldClient cleanly for Java 17 instead of editing branch bytes.
- The intended behavior remains: the Phayriosis button is injected only when the actual Allow Cheats / Allow Commands widget is present, so it appears on the Game tab only and disappears on World/More.
- Recompiled class passes java -Xverify:all.
- Runtime method descriptors were matched against the last working 0.0.18.4 class, including Component being an interface and Component.m_237113_ returning MutableComponent.

Permanent rule:
- Do not alter control flow in Java 17 class files with raw byte/NOP edits unless stack-map frames are recomputed. Prefer recompiling from maintained source or ASM COMPUTE_FRAMES.
- Preserve the no-fallback Game-tab-only behavior for the Create World Phayriosis button.

No meteor, impact, shockwave, chunk-loading, worldgen, entity, or Phase 6 gameplay code changed.


=== 0.0.18.7 - Phase 7A tab lifecycle + button callback linkage fix ===
Date: 2026-10-04

Observed test result from 0.0.18.6:
- The Phayriosis button still remained visible when switching from Game to World/More.
- Clicking the Phayriosis button crashed with AbstractMethodError because the generated lambda did not implement the SRG runtime Button.OnPress method m_93750_(Button).

Root causes:
1. Vanilla CreateWorldScreen's TabManager keeps the Game-tab widgets alive and toggles their visible field. Merely checking for the existence of Allow Cheats during ScreenEvent.Init.Post is not enough; an injected external widget is not automatically managed by the vanilla TabManager.
2. The temporary compile stub declared Button.OnPress as onPress(Button), while the Forge 1.20.1 SRG runtime interface method is m_93750_(Button). Java lambdas encode the SAM method name, producing an incompatible callback class at runtime.

Corrections:
- Recompiled PhayriosisCreateWorldClient and PhayriosisWorldCreationScreen from maintained Java source with Button.OnPress stubbed using the exact SRG method m_93750_(Button).
- CreateWorld hook now remembers the real Allow Cheats widget and the injected Phayriosis button per CreateWorldScreen using WeakHashMap references.
- ScreenEvent.Render.Pre mirrors Allow Cheats' public visible field (f_93624_) onto the Phayriosis button every frame; active state is mirrored as well. Therefore Phayriosis appears only while the Game tab is visible and disappears before World/More render.
- Position remains directly under Allow Cheats with matching X/width and 4 px vertical spacing.
- No generic fallback placement exists.

Permanent UI maintenance rules:
- Do not infer active Create World tabs from widget existence alone; vanilla tab contents may remain in the listener list while hidden.
- For injected widgets outside vanilla TabManager, mirror the visibility of the anchor widget or integrate with the tab lifecycle explicitly.
- When compiling against SRG-name stubs, functional-interface SAM names must match runtime names exactly. For Button.OnPress on Forge/Minecraft 1.20.1, use m_93750_(Button).
- Recompile all Phayriosis world-creation button callbacks together when changing the Button.OnPress stub, not only the outer Create World button.

No meteor, impact, shockwave, chunk-loading, worldgen, entity, or Phase 6 gameplay code changed.


=== 0.0.18.8 - Phase 7A SRP-style Create World lifecycle port ===
Date: 2026-10-04

User clarification/reference:
- Reference implementation is Scape and Run: Parasites (SRP) 1.12.2, jar SRParasites-1.10.9.
- SRPWorldCreateButtons was inspected directly. SRP creates one dedicated world-settings button on GUI init, lays it out relative to a known vanilla Create World control, and updates that button after Create World page actions. It does NOT rely on a perpetual render-time position/visibility chase.

Observed failures before this build:
- 0.0.18.6: Phayriosis button still followed the World/More tabs and clicking it crashed.
- 0.0.18.7: opening Create World itself crashed with NoSuchMethodError because Component.m_237113_(String) had been compiled with return type Component instead of the real SRG descriptor return type MutableComponent.
- The previous Render.Pre visibility mirror was also the wrong architectural fit for Minecraft 1.20.1 tabs.

Corrections in 0.0.18.8:
- Port the SRP lifecycle concept to 1.20.1 rather than copying 1.12.2 code literally.
- Create/layout one Phayriosis button during ScreenEvent.Init.Post, directly under Allow Cheats / Allow Commands.
- Remove the per-frame ScreenEvent.Render.Pre visibility chase entirely.
- Track CreateWorldScreen's vanilla TabNavigationBar and react after mouse/keyboard tab actions, analogous to SRP's ActionPerformed post handling.
- Determine the selected vanilla tab through the public TabNavigationBar -> TabButton API by reflection on public method shapes, avoiding private CreateWorldScreen fields and mapping-sensitive method names.
- Show/enable Phayriosis only when the selected tab object is CreateWorldScreen.GameTab; hide/disable it on World and More; show it again when Game is selected.
- Component.m_237113_(String) is compiled with the correct runtime return descriptor MutableComponent.
- Button.OnPress lambdas are compiled against the exact 1.20.1 SRG SAM m_93750_(Button).
- Restore PhayriosisWorldCreationScreen.class from the last known correctly-linked 0.0.18.4 build so its Component.literal and OnPress descriptors are also known-good.
- Java 17 verification is required before shipping.

Permanent UI rules:
- Use SRP's event-driven ownership pattern as the conceptual reference: init/layout once, update after GUI actions/page changes.
- Do not reintroduce a Render.Pre per-frame visibility mirror for this button.
- Do not infer active tabs from Allow Cheats.visible; the injected widget is external to vanilla TabManager and tab ownership must be checked from the vanilla tab navigation state.
- Keep the button labelled exactly "Phayriosis" and positioned directly under Allow Cheats on the Game tab only.
- When manually compiling SRG-linked client classes, verify Component.m_237113_ returns MutableComponent and Button.OnPress uses m_93750_(Button).

No Phase 6 meteor, impact, shockwave, chunk-loading, worldgen, entity, audio, or terrain behavior changed.

=== 0.0.18.9 - Phase 7A meteor reward + distant impact-audio tune ===
Date: 2026-10-04

User-tested baseline:
- 0.0.18.8 Create World / SRP-style Phayriosis button lifecycle is confirmed working, including tab behavior and button opening.
- Treat the 0.0.18.8 Phase 7 UI integration as stable and do not alter it for this tuning release.

Changes:
- Preserve the exact accepted meteor impact sounds and sound-selection order.
- Increase only the long-range impact witness envelope from 512 blocks to 1024 blocks.
- Keep impact/flash/shockwave particle delivery capped at the existing 512-block visual range to avoid doubling particle/network load.
- Increase the hollow meteor chamber reward target from 42-50 to 70-80 unique exposed ore blocks.
- Increase rare-ore weighting while keeping common material dominant. New 49-entry weighting is approximately:
    13 iron, 10 biometal, 7 copper, 8 gold, 5 crimsonscale,
    2 emerald, 2 diamond, 2 plutonium.
- Ore placement remains individual exposed chamber-wall blocks with duplicate-position rejection; no veins were introduced.

Permanent rules:
- Do not change the accepted impact sound asset merely to increase hearing distance; extend delivery/range instead.
- Keep long-range sound scaling independent from the 512-block particle/flash visual range for performance.
- Meteor chamber loot may be generous because this is an apocalyptic world event, but rare ores should remain a minority and placement must remain finite/unique.
- Preserve the stable 0.0.18.8 Create World UI classes unless a later UI feature explicitly requires changes.

=== 0.0.18.10 - Phase 7A airborne meteor flight-audio range tune ===
Date: 2026-10-04

User-tested baseline:
- 0.0.18.9 is confirmed working.
- Preserve the accepted impact sound, shockwave, ores, Create World UI, meteor flight,
  chunk loading, and all Phase 6/7A behavior.

Change:
- Airborne meteor flight audio fixed range increased from 256 to 768 blocks.
- PhayriosisrebornModSounds registers phayriosisreborn:meteor_flight at 768.0F.
- meteor_flight_1 through meteor_flight_4 now use attenuation_distance 768 in sounds.json.
- Sound assets, 8-tick cadence, volume, pitch, mono positional behavior, and moving source at
  the meteor entity are unchanged.
- Impact audio remains on its separate accepted long-range path and is not altered here.

Reason:
- The apocalyptic meteor can be visible while still beyond the old 256-block flight-audio
  envelope, especially during the high-altitude approach.
- 768 blocks keeps the falling event audible much farther away while retaining directional
  spatial audio tied to the moving meteor.

Permanent maintenance rule:
- When changing meteor flight-audio range, update BOTH the registered SoundEvent fixed range
  and sounds.json attenuation_distance together.
- Do not replace the accepted user-supplied meteor-flight audio merely to extend range.



======================================================================
PHASE 7B - 0.0.19 - WORLD-CREATION SECTION EXPANSION
======================================================================

User-approved Phase 7A baseline:
- 0.0.18.10 is the stable Create World button / meteor-event baseline.
- Preserve the SRP-inspired lifecycle approach for the Create World button.
- Keep the meteor system itself isolated from Phase 7 UI refactors unless specifically requested.

User UI direction for Phase 7B:
- Meteor must remain its own dedicated section.
- Other settings are organized around the infection system, especially:
    * Infection Difficulty
    * Infection Config
- Do not collapse meteor controls into a generic gameplay page.

Implemented 0.0.19 functional sections:
1) Meteor
   - Meteor Event ON/OFF
   - Earliest Day
   - Minimum Phase
   - Event Chance
   - Check Interval
   - Impact Distance
   - Impact Infection ON/OFF
   - Reset Meteor Defaults

2) Infection Difficulty
   - Nightmare Mode ON/OFF
   - Infection Spread Speed 1..5
   - Maximum Infectable Hardness presets
   - Reset Difficulty

3) Infection Config
   - Block Infection ON/OFF
   - Mob Conversions ON/OFF
   - Player Conversion ON/OFF
   - Natural Infected Spawns ON/OFF
   - Dimensional Spawning ON/OFF
   - Reset Infection Config

4) Advanced
   - Phase Progression NORMAL/FROZEN
   - Reset All Defaults
   - Reserved as the future expert-settings page

Backend rule introduced in 0.0.19:
- Create World choices remain staged in PhayriosisPendingWorldSettings until Done is pressed.
- On a genuinely fresh world, the profile is consumed once into PhayriosisWorldSettings.
- Infection settings are also mirrored into PhayriosisrebornModVariables.MapVariables because the original generated Phayriosis infection procedures still read MapVariables directly.
- This bridge is intentional and must remain until those original procedures are migrated to PhayriosisWorldSettings.
- Existing worlds are not overwritten by the pending Create World profile.

Runtime defaults preserved from original Phayriosis:
- block spread = ON
- player conversion = ON
- conversions = ON
- nightmare mode = OFF
- natural parasite spawning = OFF
- dimensional parasite spawning = OFF
- max infectable hardness = 2.9
- block spread speed = 3
- phase freeze = OFF

UI implementation note:
- This is still the functional Phase 7B screen, not the final custom pixel-art skin.
- Tab/page switching is internal to the Phayriosis settings screen and does not alter the proven CreateWorldScreen hook.


======================================================================
PHASE 7C — 0.0.20 — WORLD DIFFICULTY PRESETS
======================================================================

Added world-specific Easy / Normal / Advanced / Hard / Nightmare presets.
Exact multipliers:
- Easy: 0.50x infected health, 0.50x damage, 0.50x infection pace.
- Normal: 1.00x all (baseline behavior).
- Advanced: 1.40x health, 1.40x damage, 1.25x infection pace.
- Hard: 1.80x health, 1.70x damage, 1.35x infection pace.
- Nightmare: 2.20x health, 2.00x damage, 1.50x infection pace, plus legacy nightmaremode rules.

Difficulty entity modifiers use fixed UUIDs and must remain idempotent. Never apply
a fresh anonymous health/damage modifier every load/tick. Only Phayriosis LivingEntity
classes are targeted.

CRITICAL EVOLUTION RULE:
Bulb/Dome progression is health-gated. Difficulty must scale the required health with
the same health multiplier. Preserve Bulb threshold = 100 * multiplier (5x its normal
20 HP starting health) and Dome threshold = 150 * multiplier (1.5x its normal 100 HP).
Do not revert these to fixed 100/150 comparisons while difficulty modifiers exist.

Progression pace is implemented by scaling PhaseCalculator thresholds rather than every
point-award source: requiredPoints = normalThreshold / infectionPaceMultiplier. Physical
infection spread separately scales the main random spread-roll bounds. This avoids
double-scaling special point awards while still changing actual world infection speed.

Meteor Phase-4 forcing now uses the same difficulty-aware 10,000-point floor. The special
meteor Nucleus retains a 500 HP base and is healed to its final difficulty-adjusted max.

While building this release, the maintained Phase-2 source snapshot was found to be stale:
the runtime already consumed PhayriosisPendingWorldSettings inside ensureInitialized().
The maintained source was corrected; do not remove that pending-profile consumption or the
working Create World -> new-world settings handoff will regress.

======================================================================
0.0.20.7 — XAERO MAP BLOCK COMPATIBILITY
======================================================================
Most generated Phayriosis blocks had MapColor.NONE, causing Xaero World Map and Minimap
surface scans to discard them. Added an optional Xaero-presence-gated fallback map-color
hook for Phayriosis blocks whose original map color is zero. Existing non-zero map colors
remain untouched. Entity radar and gameplay are unchanged.


======================================================================
0.0.20.8 — XAERO MAP COMPATIBILITY DIRECT PATH
======================================================================
0.0.20.7 did not make Phayriosis terrain visible in the user's Xaero World Map/Minimap test.
The first implementation gated the fallback behind ClassLoader.getResource checks for Xaero classes.
That is not a reliable cross-mod presence test under the Forge/ModLauncher module layout and can cause
an otherwise-valid map-color hook to remain inactive.

0.0.20.8 removes that gate. Phayriosis BlockState map colors are repaired whenever the original color
is NONE/zero, independent of whether Xaero is installed. An optional @Pseudo XaeroLib texture-color
hook also repairs a zero result from Xaero's baked-texture sampler for Phayriosis blocks. This covers
both Xaero's vanilla-map-color eligibility path and its texture-color rendering path without altering
Xaero jars or adding a hard Xaero dependency.

0.0.20.9: Death-spawned corpse/remains/blood surface placement now clears compatible vegetation/crops (with drops) in the existing placement footprint and converts farmland beneath successfully placed infestation surface blocks to dirt. No background polling.

0.0.20.11 — COMPATIBILITY HOOK RETENTION FIX
- Corrected Sponge Mixin annotation retention so Xaero and surface-preparation hooks actually load.

0.0.20.12: Fixed surface foliage/crop break linkage for Forge 1.20.1 (m_46961_); preserves drops and leaves working Xaero compatibility unchanged.

======================================================================
0.0.20.16 — SMALL METEOR FALLBACK + EVENT METEOR ORE REWARD
======================================================================
- Restored only legacy small-meteor overworld biome attachment.
- Small meteor feature is gated by the same meteor-event world/config setting:
  event ON = legacy small meteor disabled; event OFF = legacy small meteor enabled.
- Legacy large meteor worldgen remains disabled.
- Event meteor chamber ore target increased from 70-80 to 127-173 (average ~150).
- Rare ore weighting increased to 30/49 (~61%) across crimsonscale, plutonium,
  diamond and emerald while retaining biometal/iron/copper/gold in the pool.
- Do not reintroduce a separate small-meteor toggle unless explicitly requested; the
  intended behavior is mutually exclusive with the live meteor event.


0.1.2 — Forge server configuration and admin command usability
Baseline: 0.1.1 (meteor stability), after the failed infected-container work was discarded. Dimensional spawning was re-tested and confirmed functional; no spawning code was changed.

Problem: phayriosisreborn-common.toml was a manually parsed global NEW-WORLD template, not a registered Forge ModConfig. Generic Forge config GUIs such as Configured could not discover it. World gameplay settings were persisted in a SavedData .dat and old commands exposed only a subset of fields. On restart, the optional old common-file override flag could overwrite saved settings, adding confusion about what was authoritative.

Change:
- Added ForgeConfigSpec registered as ModConfig.Type.SERVER from PhayriosisrebornMod constructor, file name phayriosisreborn-server.toml in each world's serverconfig directory.
- Added a one-time migration marker in Overworld SavedData: phayriosisreborn_server_config_migration. On the first server start after upgrade, the existing world settings or the Create World draft are copied into the server config. This preserves existing settings. Later starts apply the world's Forge server config to SavedData.
- Added a Forge config-reload subscriber so editing the server TOML with a supported GUI or through config reload updates the active world, with execution marshalled to the MinecraftServer thread.
- Added operator Brigadier command /phayconfig list, /phayconfig get <key>, /phayconfig set <key> <value> (permission level 2). Changes save the server config and immediately mirror onto SavedData and old MapVariables.
- Kept the global phayriosisreborn-common.toml loader for backwards-compatible new-world templates and older modpack defaults; it is NOT a registered Forge config, and should not be edited as the authoritative setting for an already migrated world. The old override_existing_world_settings flag should remain false.
- Dangerous starting-state operations (phase points, max-power initialization) remain as New World settings / existing admin commands, and are not repeatedly applied by the new server config.
- No changes to block infection, dimensional spawning, meteor systems, visual assets, sound or general world generation.

Compatibility and limitations:
- Forge 1.20.1 47.4.x and Java 17 only.
- Configured is optional. A supported version must be installed to view/edit the registered Forge SERVER config through its UI. Access on dedicated servers depends on the GUI's support for remote server configs and permissions.
- Existing worlds' prior SavedData options take precedence the first time version 0.1.2 starts; if an admin manually creates the new server config in an old world before first run, the migration will replace those custom values once. Run the world once before editing its new server config.
- Previously existing commands that change infection settings outside /phayconfig may still update SavedData without updating server TOML. Prefer /phayconfig for persistent settings that survive the next restart. Existing phase/points commands operate on progression state, not this configuration file.

Validation: Java 17 compiled code, runtime method signatures validated against Forge 1.20.1 API documentation and SRG mappings, original 0.1.1 jar comparison, ZIP validation, bytecode verification and constructor call integrity. In-game Forge/Configured integrated and dedicated runtime testing still required. No full mod source project shipped; patch sources and preserved maintainer references are included separately.

PHAYRIOSIS REBORN CONTINUED — METEOR / IN CONTROL COMPATIBILITY
Author: leo_san
Build: existing mod metadata version 0.1.2 preserved at user request
Minecraft: 1.20.1; Forge 47.4.x; Java runtime: 17
2026-10-11 — Meteor-only In Control spawn exemption patch

BASELINE / REFERENCE
- Input: phayriosis-reborn-continued-0.1.2(5).jar (the user-confirmed latest Phayriosis build).
- Reference: Spore-Meteor-Compat-0.1.8-TEST(1).jar, which carries the known meteor-origin gating approach.
- Target In Control: incontrol-1.20-9.4.6(3).jar. Exact method names/descriptors inspected.
- User spawn.json has day gates in ONJOIN and changes in FINALIZE, plus possible POSITION rules.

IMPLEMENTATION
1. Target only the private PhayriosisMeteorImpactSystem.spawnEntity helper, which both the
   meteor's impact infected wave and nucleus chamber guardian use. Replace its sole
   EntityType.spawn invocation with MeteorSpawnScope.spawn preserving exact arguments.
2. Adapt Spore's MeteorSpawnScope mechanism: push the expected EntityType onto
   thread-local ArrayDeque; register HIGHEST-priority Forge spawn observers that
   apply the persistent Boolean 'phayriosisreborn:meteor_spawned_v1' to the expected
   entity during PositionCheck, FinalizeSpawn, and EntityJoinLevelEvent, BEFORE
   In Control can evaluate its restrictive handlers. The temporary scope is popped
   in finally behavior; the successful spawned entity is marked as fallback.
3. Inject a narrow, optional Mixin targeting only the In Control class
   mcjty.incontrol.ForgeEventHandlers with remap=false. If marked, return EARLY
   from onEntityJoinWorld(EntityJoinLevelEvent),
   onEntitySpawnEvent(MobSpawnEvent.FinalizeSpawn), and
   onPositionCheck(MobSpawnEvent.PositionCheck).
   Do NOT cancel the underlying Forge event; cancel only In Control's handler method.
   No global suppression of In Control's other rules, bookkeeping, despawn events, etc.
4. Register the scope observer in PhayriosisrebornMod's existing initialization;
   enable only the new optional Mixin configuration via manifest MixinConfigs.
   In Control is NOT declared as a required mod dependency. Existing mixin config
   resources are preserved unmodified.
5. Do not stamp the meteor projectile, worldgen meteors, natural Phayriosis mobs,
   conversion-generated infected, or manual /summon entities. Other Phayriosis
   spawn paths are NOT wrapped or exempted.

CHANGED JAR MEMBERS
- net/mcreator/phayriosisreborn/PhayriosisrebornMod.class
- net/mcreator/phayriosisreborn/meteor/PhayriosisMeteorImpactSystem.class
- META-INF/MANIFEST.MF
- Added net/mcreator/phayriosisreborn/meteor/MeteorSpawnScope.class
- Added net/mcreator/phayriosisreborn/mixin/InControlMeteorBypassMixin.class
- Added phayriosisreborn.meteor-incontrol.mixins.json
- Updated PHAYRIOSIS_REBORN_CONTINUED_MAINTAINER_HISTORY.txt (append-only)
- Added this text file

CHECKS / STATUS
- Checked exact In Control 9.4.6 method descriptors and @SubscribeEvent event priorities.
- Ensured In Control's onEntityJoinWorldLast bookkeeping is untouched.
- Offline checks: compare unchanged JAR entry SHA256s, Java 17 bytecode major version,
  class annotation visibility, Mixin config + manifest registration, ZIP integrity.
- NOT YET validated inside running Forge: optional absence of In Control, full meteor
  event, world save/reload, gameplay interaction, and other mods' spawn hooks.
- If any MixinApplyError occurs, review actual exception, Mixin @Mixin annotation
  visibility (must be RuntimeInvisibleAnnotations), target names and Method descriptors
  before making further modifications. Keep previous successful features intact.

KNOWN CONSTRAINTS
- Marker is a normal persistent entity Boolean, not cryptographic authentication.
- A nested same-type spawn triggered synchronously inside an active meteor spawn
  event could inherit the marker (same limitation as reference Spore implementation).
- Scope markers do not follow offspring or entities spawned later through independent
  parasite behavior, which is intentional: only direct meteor impact creations bypass.
- A rule from other mods (not In Control) may still deny spawns; these are not modified.


PHAYRIOSIS REBORN CONTINUED — 0.1.3 (CONFIG UI + METEOR DEFENDER HP)
Author: leo_san
Minecraft: 1.20.1; Forge: 47.4.x; Runtime: Java 17
Date: 2026-10-12

AUTHORITATIVE INPUT
- Phayriosis-Reborn-Continued-0.1.3.jar supplied by the user for this change.
- Version and prior six elite defenders retained unchanged.
- Previously tested meteor-only In Control exemption and all its Mixins are unchanged.

CHANGE 1: MODPACK CREATOR CREATE-WORLD UI HIDE
- New option is `hideWorldCreationConfig = false` under [general] in the global
  client/instance config/phayriosisreborn-common.toml.
- Set to true to omit the Phayriosis settings button from Minecraft's Create World
  Game tab. The button is removed during screen reinitialization before applying
  the hide gate so stale button instances are not retained.
- The separate per-world serverconfig/phayriosisreborn-server.toml remains authoritative
  for established worlds and is not replaced. The hide flag belongs to the global
  client config because a per-world server config is not available at Create World.
- Existing TOMLs gain this option only if absent. The upgrade preserves existing values,
  leaves true values unchanged, and is idempotent; new generated TOMLs include it.
- Original Phayriosis config UI functions as before with the default false setting.
- This hides the Create World button; it does not block operators from /phayconfig,
  does not prohibit manual config editing, and is not a server-side permissions mechanism.
- A restart of the client/instance is needed after editing the global option because
  PhayriosisFileConfig is loaded once and cached during the process.

CHANGE 2: MINIMUM 100 HP FOR OUTSIDE METEOR DEFENDERS ONLY
- In PhayriosisMeteorImpactSystem.spawnImpactInfected, take the returned Entity from
  each existing spawnEntity call and pass it to MeteorDefenderHealth.raiseIfBelow100.
- For LivingEntity defenders with effective maximum health less than 100, adjust the
  maximum-health attribute and set current health to 100 (or up to effective maximum).
- Preserve any entity with 100 or more maximum HP with no attribute or health changes.
- Existing spawnEntity method, MeteorSpawnScope, spawn position distribution, all
  exterior defender type entries, and optional In Control Mixins are unchanged.
- The Nucleus lives in spawnNucleusGuardian, which is left untouched and continues
  to receive its pre-existing 500 HP base health; it never calls the new helper.
- No ticking hooks, entity iteration, or background calculations are added. The
  helper runs only immediately following each exterior meteor spawn attempt.

CHANGED EXISTING CLASS FILES
- net/mcreator/phayriosisreborn/config/PhayriosisFileConfig.class
- net/mcreator/phayriosisreborn/client/PhayriosisCreateWorldClient.class
- net/mcreator/phayriosisreborn/meteor/PhayriosisMeteorImpactSystem.class
NEW CLASS FILES
- net/mcreator/phayriosisreborn/config/PhayriosisConfigUpgrade.class
- net/mcreator/phayriosisreborn/meteor/MeteorDefenderHealth.class
UPDATED DOCUMENTATION
- Root and META-INF/phayriosis-maintainer copies of the maintenance history.
- This release log and both new helper sources included under META-INF/phayriosis-maintainer.

IMPLEMENTATION / VERIFICATION
- Narrow JVM instruction patch via Java 21 JDK internal ASM API; output Java 17 class
  major version 61. The source archive contains the patcher and the new helper classes.
- FileConfig.read uses its existing boolean parser on general.hideworldcreationconfig.
- Existing TOML upgrade runs in the existing ensureLoaded error-handled I/O path.
- Create World UI uses its existing allowCheats null gate after applying UI-only flag.
- Exterior defender hook consumes the returned Entity instead of its original POP.
- Verified config upgrade preserves values, skips duplicate insertion, and respects true.
- Verified mocked health cases: 20, 80, 100, 165, 500, and modified attribute values.
- Release JAR integrity, bytecode descriptors and all unchanged entry hashes verified.
- Full Minecraft Forge runtime testing remains to be performed by the user; if issues
  occur, collect latest.log and any crash report from the exact installed release JAR.

LIMITATIONS / HANDOFF
- The global hide option prevents access through this Create World UI; it is not a
  security boundary. Operators can still change server settings using existing tools.
- Other mods may subsequently modify a meteor defender's attributes after spawning.
- The original exterior registry IDs `assaulter` and `spitter` were preserved, even
  though older maintenance notes flagged them as possibly absent. This release does
  not attempt to fix those names to avoid unrelated alterations.
- Continue development from THIS jar as the authoritative user-selected 0.1.3 base.

=== 0.1.4 (hotfix) — release version and file naming ===
Date: 2026-10-12
Author: leo_san
Base: Phayriosis-Reborn-Continued-0.1.3-Modpack-Config-Meteor-HP.jar (latest user-approved build).
Changes: Updated Forge mods.toml mod version from 0.1.3 to 0.1.4; renamed distributed jar to phayriosis-reborn-continued-0.1.4(hotfix).jar.
Unchanged: All compiled classes, spawn behavior, meteor guards/100-HP floor, 500-HP nucleus, modpack UI visibility option, In Control spawn exemption, configuration, assets, and dependencies.
Validation: JAR integrity and exact binary identity of all class files and non-document metadata checked offline. No Minecraft gameplay launch test was run for this metadata-only release.
Maintainer handoff: Continue from 0.1.4 hotfix. For new functionality, avoid mutating other systems without request.


=== 0.1.5 — version metadata update from verified meteor-defender fix ===
Date: 2026-10-12
Author: leo_san
Baseline: phayriosis-reborn-continued-0.1.4(hotfix)-meteor-defender-fix.jar (user confirmed meteor spawning works in-game).
Changes: Set Forge mod version to 0.1.5; release filename Phayriosis-Reborn-Continued-0.1.5.jar; append release documentation.
Unchanged: All compiled classes and gameplay behavior, including valid Phayriosis-only meteor defenders, bounded retries and persistence, the meteor-only In Control compatibility marker, min-100-HP exterior guards, the separate 500-HP Nucleus, world creation config visibility option, and all existing configs/assets.
Verification: Inspected JAR entry names, hashes, version and author; ZIP integrity passed. No new runtime test was performed for this metadata-only update.
Handoff: Use this 0.1.5 JAR as the authoritative next baseline; do not revert the verified 0.1.4 defender reliability fixes.


=== 0.1.5 METEOR ENTITY FACTORY COMPATIBILITY HOTFIX ===
Date: 2026-10-18
Author: leo_san
Baseline: Phayriosis-Reborn-Continued-0.1.5.jar, confirmed working in-game for meteor defenders.
Reported failure: Easy Mob Spawn Control 1.6.2 GUI enumerated all EntityTypes, invoked EntityType.create(clientLevel) to determine whether types are living mobs, and triggered AbstractMethodError in the Phayriosis custom meteor EntityFactory lambda.
Evidence: crash.txt dated 2026-10-15 17:36:56, opening Easy Mob Spawn Control's config screen. Stack trace: EntityType.m_20615_ -> EasyMobSpawnControl.EntityUtil.isLivingEntity -> MobListManager -> SpawnControlScreen; missing EntityFactory.m_20721_(EntityType,Level).
Root cause: The custom PhayriosisMeteorEntityRegistry class's invokedynamic LambdaMetafactory call site used the development-mapping SAM name create instead of the Forge 1.20.1 SRG runtime SAM m_20721_. The existing generated PhayriosisrebornModEntities registry already uses m_20721_ correctly; only the custom meteor factory was wrong.
Fix: Replace exactly one UTF8 constant-pool entry for the meteor registry lambda SAM name, create -> m_20721_, preserving bootstrap method, functional signature, constructor target, and all other classes. No changes to Easy Mob Spawn Control, Forge mod version (remains 0.1.5), or any meteor logic.
Unchanged: Nucleus 500-HP behavior; exterior defender composition, persistence and minimum 100-HP floor; optional In Control compatibility, persistent spawn markers, world creation visibility configuration, chunk handling, and all remaining code/resources.
Validation: JAR ZIP CRC integrity; javap post-patch InvokeDynamic verification; exact SHA-256 identity for all 2,816 unrelated class files; mod metadata and unchanged resource verification. No live Forge game test has been performed for this hotfix.
Recommended test: Start the modpack with Easy Mob Spawn Control 1.6.2 and Phayriosis 0.1.5 hotfix, open Mods > Easy Mob Spawn Control > Config and use its entity list/search. Then spawn a Phayriosis meteor and confirm all existing behavior remains intact.
Outstanding limitation: Another mod can still mishandle instantiation of unusual entities during GUI scanning. Report any new crash separately; do not assume it is this resolved AbstractMethodError.
Handoff: Continue from the hotfix jar. Preserve existing meteor logic and the Forge runtime-mapped lambda name when rebuilding or remapping custom registry classes.
