feat(cheats): add elephant feeding mode and charges

.plans/README.md

@@ -5,7 +5,7 @@
   menus, cheats, saves and music, including validation and compatibility limits.
 - [macOS runtime](macos-runtime.md): relocatable SDL libraries and clean-machine archive checks.
 - [Release automation](release-automation.md): Make targets, native CI and version-tag releases.
-- [Elephant cheat](elephant-cheat.md): embedded trunk art and elephant projectiles.
+- [Elephant cheat](elephant-cheat.md): embedded elephant art, food projectiles and sleeping enemies.
 
 The completed gameplay specifications moved from Elephc when DOOM became an independent
 project. Historical compiler and Code Journal references belong to Elephc.

.plans/elephant-cheat.md

@@ -41,3 +41,93 @@ and the native SDL executable was rebuilt with this revision.
 The weapon shows only the back of a rounded head and its ears. Its existing lump
 names and frame order are preserved so saved sprite references remain stable.
 The placement regression checks both ears and leaves the upper view clear.
+
+## Feeding mode
+
+- [x] Replace all monster families with walking and chewing elephant art.
+- [x] Replace the slot 2 elephant projectiles with leafy carrots and food crumbs.
+- [x] Animate full elephants tipping over and sleeping with breathing and `zZzZ`.
+- [x] Settle full flying elephants onto the floor and suppress pain/death sounds.
+- [x] Preserve drops, statistics, boss exits, Nightmare waking and reversible toggles.
+- [x] Keep the original actor and sprite indices in saves, appending new art last.
+- [x] Run feeding regressions and the complete suite, then inspect real-WAD frames.
+
+Feeding reuses the combat health budget as remaining appetite and the existing
+pain/death states as chewing/flopping/sleeping. Only displayed monster frames are
+substituted, so toggling the cheat restores original art immediately and legacy
+saves retain their definitions. The existing ELPH frames now contain carrots and
+crumbs. New ELEN frames are appended after all existing built-in patches. Sleep
+letters are part of the actor patch and share its wall clipping and lighting.
+Other weapons and difficulty rules retain their mechanics. The contact attack
+revision below replaces monster ranged attacks while the mode is active.
+
+Local validation with elephc 0.27.6 passed all 108 gameplay tests (910 assertions),
+including the five new feeding regressions, all 16 release-tooling tests and the
+native SDL build. Real shareware E1M1 standing, chewing and sleeping frames were
+rendered, and the standing/sleeping views and art sheet were visually inspected.
+This revision has not been run through the remote native CI matrix.
+
+## Human feeder
+
+- [x] Replace the rear head with a human hand gripping a carrot.
+- [x] Animate an empty-hand throwing pose and recovery with the next carrot.
+- [x] Replace the player portrait with an original human wearing an unmarked cap.
+- [x] Preserve expression priorities, health bands, portrait bounds and saved indices.
+- [x] Validate the revised silhouettes, portrait expressions and native real-WAD frames.
+
+ELTG and ELFACE patch names and ordering stay stable, while their pixels now show
+the human player. FeederFaces supplies all 32 portrait slots. The first-person
+hand uses the existing three animation frames and keeps the upper view clear.
+The palette adds skin, hair and clothing shades after the existing herd/food ramp.
+
+The revised gameplay suite passes locally with 109 tests and 913 assertions using
+elephc 0.27.6. The native SDL executable was rebuilt, and real shareware E1M1
+ready, throwing and recovery views plus the human portrait/hand sheet were
+rendered. The ready view and complete portrait/hand sheet were visually checked.
+
+## Contact attacks
+
+- [x] Make all elephant families chase and attack only at body contact.
+- [x] Check body radii, vertical overlap and line of sight before dealing damage.
+- [x] Cancel pending ranged windups and flying charges when the mode is active.
+- [x] Retire hostile projectiles before direct or splash damage, preserving food.
+- [x] Shorten the final chase step so large, fast actors can reach contact.
+- [x] Validate all families, escaped targets, walls, heights, toggles and native build.
+
+Contact attacks deal 4 to 12 damage after a short windup, followed by a cooldown.
+Nightmare retains its faster timing. Target positions are checked again when
+the hit lands, allowing the player to escape. The original monster attacks return
+when IDELEPHC is disabled, and the existing save schema is unchanged.
+
+Local validation passed all 115 gameplay tests (1001 assertions), including six
+new contact regressions, all 16 tooling tests and the native SDL build with
+elephc 0.27.6. Normal monster attacks and the existing feeding/portrait/save tests
+remain covered by the same complete suite.
+
+## Occasional charges
+
+- [x] Give each chasing elephant a staggered chance to charge occasionally.
+- [x] Show a 14-tic stationary warning with raised trunk art and a sound cue.
+- [x] Lock the dash direction, sweep movement in two-unit steps, and stop on obstacles.
+- [x] Deal one 16-point contact hit, then recover for three seconds.
+- [x] Interrupt charges when fed, when full, or when the mode is disabled.
+- [x] Reuse saved actor state, countdown, damage and velocity fields without a schema change.
+- [x] Validate warning timing, dodges, collision, damage, all families and save continuation.
+- [x] Inspect native warning/dash art and rebuild the SDL executable.
+
+Each eligible actor gets a 25% chance every 70 tics, staggered by object index,
+when its target is visible, outside contact range and within 640 map units.
+The windup lasts 14 tics; the locked dash lasts at most 24 tics at 24 units per
+tic. There is no steering during the windup or dash. Walls, actors and map
+openings use normal collision, while crossed monster specials still apply.
+Food cancels the charge through the existing pain/fullness transition.
+
+State 8 with hitDamage 16 distinguishes the feeding-mode dash from legacy lost
+soul charges. Existing saved velocity/countdown fields preserve both phases.
+New warning pictures follow the original nine ELEN frames, preserving saved
+sprite definitions. Original-mode lost soul charges retain their behavior.
+
+Local validation with elephc 0.27.6 passed all 122 gameplay tests (1092 assertions),
+including seven charge regressions, all 16 tooling tests and the native SDL build.
+Native real shareware E1M1 warning and dash frames and the complete herd art sheet
+were rendered and visually inspected. No remote native CI run was requested.

README.md

@@ -172,17 +172,32 @@ Type cheat codes during play, without a console, then release movement keys as n
 | `IDCLEVxy` | Warp to episode x, mission y, if present in the WAD |
 | `IDMUSxy` | Select an available episode/mission music track |
 | `IDMYPOS` | Toggle position display |
-| `IDELEPHC` | Toggle elephant mode in pistol slot 2; fires red/orange elephant projectiles |
-
-`IDELEPHC` selects the pistol slot and shows an elephant's head from behind,
-low in the view, with ears that flap when firing. The status-bar portrait becomes
-an elephant that glances around and reacts to health, damage, firing, pickups,
-invulnerability and death. The
-elephants travel through the level, hit monsters and stop at walls, using the
-pistol's bullets and firing cadence. Type the code again to restore the pistol
-and the marine portrait.
-Other weapons keep their behavior. The mode survives map changes and saves;
-starting a new game or restarting after death resets it. Its pixel art is built
+| `IDELEPHC` | Toggle feeding mode: elephant enemies, flying carrots in slot 2, and sleepy full bellies |
+
+`IDELEPHC` turns every monster family into a red/orange elephant and selects
+slot 2 to toss carrots. Food travels through the level and stops at walls, using
+the pistol's bullets and firing cadence. Elephants chase you and cause damage
+only at body contact, with no bullets or fireballs. Escaping before a contact
+attack lands avoids the hit; walls and vertical gaps also block it.
+Activating the mode retires hostile shots already in flight.
+Occasionally, an elephant raises its trunk and pauses before charging in a
+straight line. Sidestep during the warning to dodge it, or feed it to interrupt
+the charge. Charges stop at walls, solid objects or the first contact hit, then
+the elephant needs a short recovery before attacking again.
+Elephants chew when fed, then flop onto
+their side with an animated `zZzZ` when full. Flying elephants settle onto the
+floor for their nap. Sleeping elephants stop attacking and blocking movement;
+they still count toward level completion and unlock the original boss exits.
+Nightmare's respawn rules still apply, waking elephants for another meal.
+
+You play as a human feeder wearing a plain cap. A hand holds a leafy carrot low
+in the view, opens to toss it, and returns with the next carrot. The status-bar
+portrait has short brown hair and a beard, glances around, and reacts to health,
+damage, throwing food, pickups, invulnerability and death. Type the code again
+to restore the original monsters, pistol and marine portrait.
+Other weapons keep their behavior. The mode survives map changes, and saves
+preserve the mode, food in flight and sleeping actors. Starting a new game or
+restarting after death resets the mode. Its pixel art is built
 into the executable and uses the loaded WAD's palette, with no extra asset files.
 
 Saves live in `saves/slot0.json` through `slot5.json`, relative to the launch directory.
@@ -254,6 +269,7 @@ src/
     CombatTrace.php      Wall openings, sight and hitscan targeting
     Weapons.php          Weapon selection, ammo and firing cadence
     MonsterAI.php        Sight, chase, attacks, pain, death and respawning
+    ElephantCharge.php   Occasional feeding-mode charges, warning, collision and recovery
     MonsterRules.php     Monster stats, animation frames and sound profiles
     Projectiles.php      Swept projectiles, splash damage and BFG spray
   Data/                  packed classes: map records, Mobj, Mover, LightEffect, Button

src/Data/Mobj.php

@@ -22,7 +22,7 @@
     public int $height;
     public int $solid;
     // Combat state: 0 idle, 1 chase, 2 attack windup, 3 pain, 4 dying, 5 corpse,
-    // 6 flying projectile, 7 exploding. Noncombat decorations keep health at 0.
+    // 6 flying projectile, 7 exploding, 8 charging. Noncombat decorations keep health at 0.
     public int $health;
     public int $state;
     public int $stateTics;
@@ -36,7 +36,7 @@
     public int $fixedX;
     public int $fixedY;
     public int $fixedZ;
-    public int $hitDamage;
+    public int $hitDamage; // Projectile damage, or the active elephant charge marker/damage.
     public int $splashDamage;
     public int $spawnX;
     public int $spawnY;