rom24-quickmud-python 2.9.14__tar.gz → 2.9.16__tar.gz

{rom24_quickmud_python-2.9.14 → rom24_quickmud_python-2.9.16}/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.9.16]
+
+### Added
+- **INV-019 POSITION-PROMOTION-ON-HEAL** filed as ✅ ENFORCED in `docs/parity/CROSS_FILE_INVARIANTS_TRACKER.md`. ROM `src/fight.c:1380-1387 update_pos` — when `victim->hit > 0`, if `position <= POS_STUNNED` the victim is **silently** promoted to `POS_STANDING` (no `act()` call, no self-line). This is the upward counterpart of INV-016 BCAST-ON-POSITION-TRANSITION (which fires only on the downward damage path). The contract spans three modules: heal handlers (`mud/skills/handlers.py` — `cure_light`, `cure_critical`, `cure_serious`, `heal`), the regen pipeline (`mud/game_loop.py:char_update` lines 713-716 — `_apply_regeneration` then `update_pos` only when STUNNED), and `update_pos` itself (`mud/combat/engine.py:677-697`, byte-for-byte ROM). All three currently agree by construction; the test pins three load-bearing properties: (1) cure_light on a STUNNED PC promotes to STANDING with no broadcast, (2) the regen tick promotes a STUNNED char whose hp lifts above 0, (3) `update_pos` does not promote positions above STUNNED (RESTING stays RESTING). `tests/integration/test_inv019_position_promotion_on_heal.py`. Tracker now at 19 of ~20 budget.
+
+## [2.9.15]
+
+### Fixed
+- **`group_gain` over-counted level-1 NPC contributions to `total_levels`** (`mud/groups/xp.py:104-105`): ROM `src/fight.c:1751` accumulates `group_levels += IS_NPC(gch) ? gch->level / 2 : gch->level;` — raw C integer division, so a level-1 NPC group member (e.g. a charmed pet) contributes 0, not 1. Python had `total_levels += max(1, level // 2)`, flooring NPC contributions at 1. Symptom: a level-10 PC grouped with a level-1 charmed pet killed a victim and received ~10% less XP than ROM would award, because the share-formula denominator (`max(1, total_levels - 1)`, `mud/groups/xp.py:253-254`) was inflated by 1. Fix: drop the `max(1, ...)` floor. Two enforcement tests in `tests/integration/test_group_xp_npc_level_floor.py`: (1) level-1 NPC pet contributes 0; (2) level-3 NPC pet contributes 1 (sanity check that the original behavior at level ≥ 2 is preserved).
+
 ## [2.9.14]
 
 ### Fixed

{rom24_quickmud_python-2.9.14/rom24_quickmud_python.egg-info → rom24_quickmud_python-2.9.16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rom24-quickmud-python
-Version: 2.9.14
+Version: 2.9.16
 Summary: A modern Python port of the ROM 2.4b6 MUD engine with full telnet server and JSON world loading
 Author-email: Mark Jedrzejczyk <mark.jedrzejczyk@gmail.com>
 Maintainer-email: Mark Jedrzejczyk <mark.jedrzejczyk@gmail.com>

{rom24_quickmud_python-2.9.14 → rom24_quickmud_python-2.9.16}/mud/groups/xp.py

@@ -102,7 +102,9 @@ def group_gain(ch: Character, victim: Character) -> None:
         if level <= 0:
             continue
         if getattr(gch, "is_npc", False):
-            total_levels += max(1, level // 2)
+            # mirroring ROM src/fight.c:1751 — `gch->level / 2` is raw C
+            # integer division, so a level-1 NPC contributes 0, not 1.
+            total_levels += level // 2
         else:
             total_levels += level
 

{rom24_quickmud_python-2.9.14 → rom24_quickmud_python-2.9.16}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "rom24-quickmud-python"
-version = "2.9.14"
+version = "2.9.16"
 description = "A modern Python port of the ROM 2.4b6 MUD engine with full telnet server and JSON world loading"
 readme = "README.md"
 license = "MIT"

{rom24_quickmud_python-2.9.14 → rom24_quickmud_python-2.9.16/rom24_quickmud_python.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rom24-quickmud-python
-Version: 2.9.14
+Version: 2.9.16
 Summary: A modern Python port of the ROM 2.4b6 MUD engine with full telnet server and JSON world loading
 Author-email: Mark Jedrzejczyk <mark.jedrzejczyk@gmail.com>
 Maintainer-email: Mark Jedrzejczyk <mark.jedrzejczyk@gmail.com>

{rom24_quickmud_python-2.9.14 → rom24_quickmud_python-2.9.16}/rom24_quickmud_python.egg-info/SOURCES.txt

@@ -692,6 +692,7 @@ tests/integration/test_furniture_occupancy.py
 tests/integration/test_get_room_messages.py
 tests/integration/test_give_command.py
 tests/integration/test_group_combat.py
+tests/integration/test_group_xp_npc_level_floor.py
 tests/integration/test_healer_command_parity.py
 tests/integration/test_hedit_parity.py
 tests/integration/test_hpcnt_once_per_pulse.py
@@ -713,6 +714,7 @@ tests/integration/test_inv014_object_registry_membership.py
 tests/integration/test_inv015_affect_tick_lifecycle.py
 tests/integration/test_inv016_position_transition_broadcast.py
 tests/integration/test_inv018_wear_off_message_for_raw_affect.py
+tests/integration/test_inv019_position_promotion_on_heal.py
 tests/integration/test_invisibility_combat.py
 tests/integration/test_json_loader_parity.py
 tests/integration/test_lookup_parity.py

rom24_quickmud_python-2.9.16/tests/integration/test_group_xp_npc_level_floor.py

@@ -0,0 +1,165 @@
+"""`group_gain` must not floor NPC level contributions at 1.
+
+ROM ``src/fight.c:1751`` accumulates ``group_levels``:
+
+    group_levels += IS_NPC (gch) ? gch->level / 2 : gch->level;
+
+For a level-1 NPC group member (e.g. a charmed pet, an NPC follower the
+player has grouped with), ROM contributes ``1 / 2 == 0`` to the denominator.
+Python's ``mud/groups/xp.py:104-105`` was:
+
+    if getattr(gch, "is_npc", False):
+        total_levels += max(1, level // 2)
+
+The ``max(1, ...)`` floor inflates the denominator by 1 at NPC level 1,
+making the PC's share-formula divisor larger than ROM's and reducing the
+XP awarded to the PC.  Symptom: a level-10 PC grouped with a level-1
+charmed pet kills a victim and receives ~10% less XP than ROM would
+award.
+
+This test pins the ROM-faithful arithmetic by exercising ``xp_compute``
+through ``group_gain`` end-to-end, asserting the awarded XP matches the
+ROM denominator (``max(1, total_levels - 1)`` where ``total_levels``
+omits the level-1 NPC's contribution).
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from mud.groups.xp import group_gain, xp_compute
+from mud.models.character import Character, character_registry
+from mud.models.constants import Position
+from mud.models.room import Room
+from mud.registry import room_registry
+from mud.utils import rng_mm
+
+
+@pytest.fixture(autouse=True)
+def _cleanup():
+    snapshot = list(character_registry)
+    character_registry.clear()
+    yield
+    character_registry.clear()
+    character_registry.extend(snapshot)
+    room_registry.pop(9200, None)
+
+
+def _make_room() -> Room:
+    room = Room(vnum=9200, name="Group XP", description="", room_flags=0, sector_type=0)
+    room.people = []
+    room.contents = []
+    room_registry[9200] = room
+    return room
+
+
+def _make_pc(room: Room, level: int) -> Character:
+    pc = Character(
+        name="Leader",
+        level=level,
+        room=room,
+        is_npc=False,
+        hit=100,
+        max_hit=100,
+        mana=100,
+        max_mana=100,
+        move=100,
+        max_move=100,
+        position=int(Position.STANDING),
+        exp=0,
+        alignment=0,
+    )
+    pc.leader = pc  # own group leader
+    pc.played = 0
+    pc.logon = 0
+    pc.messages = []
+    room.people.append(pc)
+    character_registry.append(pc)
+    return pc
+
+
+def _make_npc_pet(room: Room, level: int, master: Character) -> Character:
+    pet = Character(
+        name="Pet",
+        short_descr="a pet",
+        level=level,
+        room=room,
+        is_npc=True,
+        hit=20,
+        max_hit=20,
+        position=int(Position.STANDING),
+        alignment=0,
+    )
+    pet.master = master
+    pet.leader = master
+    room.people.append(pet)
+    character_registry.append(pet)
+    return pet
+
+
+def _make_victim(room: Room, level: int) -> Character:
+    victim = Character(
+        name="Victim",
+        short_descr="a victim",
+        level=level,
+        room=room,
+        is_npc=True,
+        hit=0,
+        max_hit=20,
+        position=int(Position.DEAD),
+        alignment=0,
+    )
+    room.people.append(victim)
+    character_registry.append(victim)
+    return victim
+
+
+def test_npc_level_one_contributes_zero_to_group_levels():
+    """Level-1 NPC pet must contribute 0 (ROM `gch->level / 2 == 0`),
+    not 1 (Python's pre-fix `max(1, level // 2)`)."""
+    room = _make_room()
+    pc = _make_pc(room, level=10)
+    pet = _make_npc_pet(room, level=1, master=pc)
+    victim = _make_victim(room, level=10)
+
+    # Expected: xp_compute called with total_levels = 10 (PC only).
+    # Python pre-fix: xp_compute called with total_levels = 11.
+    # We probe via the shared xp_compute formula at the share-divide step.
+    rng_mm.seed_mm(99)
+    rom_xp = xp_compute(pc, victim, total_levels=10)
+    rng_mm.seed_mm(99)
+    bug_xp = xp_compute(pc, victim, total_levels=11)
+    assert rom_xp != bug_xp, "test sanity: the two denominators must yield different XP"
+
+    # group_gain must use ROM's denominator.
+    rng_mm.seed_mm(99)
+    baseline_exp = 100_000  # well above exp_per_level floor
+    pc.exp = baseline_exp
+    pc.alignment = 0  # reset (xp_compute may mutate via alignment-change)
+    group_gain(pc, victim)
+    awarded = pc.exp - baseline_exp
+    assert awarded == rom_xp, (
+        f"group_gain awarded {awarded} but ROM would award {rom_xp} "
+        f"(Python pre-fix would award {bug_xp} via inflated denominator)"
+    )
+
+
+def test_npc_level_three_contributes_one_unchanged():
+    """Sanity: at NPC level 3, ROM (`3 / 2 == 1`) and Python (`max(1, 3 // 2) == 1`)
+    agree.  This test must keep passing after the floor is removed."""
+    room = _make_room()
+    pc = _make_pc(room, level=10)
+    pet = _make_npc_pet(room, level=3, master=pc)
+    victim = _make_victim(room, level=10)
+
+    # Expected: total_levels = 10 (PC) + 1 (level-3 NPC halved) = 11.
+    rng_mm.seed_mm(99)
+    expected = xp_compute(pc, victim, total_levels=11)
+
+    rng_mm.seed_mm(99)
+    baseline_exp = 100_000
+    pc.exp = baseline_exp
+    pc.alignment = 0
+    group_gain(pc, victim)
+    awarded = pc.exp - baseline_exp
+    assert awarded == expected

rom24_quickmud_python-2.9.16/tests/integration/test_inv019_position_promotion_on_heal.py

@@ -0,0 +1,159 @@
+"""INV-019 — POSITION-PROMOTION-ON-HEAL.
+
+ROM ``src/fight.c:1380-1387 update_pos`` promotes a victim upward whenever
+``hit > 0`` and ``position <= POS_STUNNED``:
+
+    if (victim->hit > 0)
+    {
+        if (victim->position <= POS_STUNNED)
+            victim->position = POS_STANDING;
+        return;
+    }
+
+The promotion is **silent** — no broadcast, no self-line.  It is called from:
+
+1. Every direct-heal spell handler (``spell_cure_light``, ``spell_heal``,
+   ``spell_cure_critical``, etc. — ``src/magic.c:1632, 1675, 1716, 3116``).
+2. The regen tick when a STUNNED char's ``hit_gain`` lifts hp back above 0
+   (``src/update.c:714-715``).
+3. ``stop_fighting`` after a fight ends (``src/fight.c:1448``).
+
+This invariant pins the contract end-to-end:
+
+* A STUNNED PC who casts/receives cure_light and gains hp must end STANDING.
+* A STUNNED PC who passively regens above 0 hp during the regen tick must
+  end STANDING.
+* The upward promotion must NOT emit a broadcast (ROM is silent — this is
+  the symmetric counterpart to INV-016 BCAST-ON-POSITION-TRANSITION, which
+  fires only on the *downward* transitions through damage()).
+
+Python equivalence: ``mud/combat/engine.py:update_pos``,
+``mud/game_loop.py:char_update`` regen tick, healing handlers in
+``mud/skills/handlers.py`` (all call ``update_pos`` immediately after
+modifying ``target.hit``).
+
+Status: ✅ ENFORCED at probe time (2.9.16).  Test added as a regression pin
+in the spirit of INV-017 TICK-ITERATION-SAFETY — the contract was correct
+by construction but lives across three modules and is easy to regress
+unnoticed.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from mud.combat.engine import update_pos
+from mud.game_loop import _apply_regeneration
+from mud.models.character import Character, character_registry
+from mud.models.constants import Position
+from mud.models.room import Room
+from mud.registry import room_registry
+from mud.skills.handlers import cure_light
+
+
+@pytest.fixture(autouse=True)
+def _cleanup():
+    snapshot = list(character_registry)
+    character_registry.clear()
+    yield
+    character_registry.clear()
+    character_registry.extend(snapshot)
+    room_registry.pop(9300, None)
+
+
+def _make_room() -> Room:
+    room = Room(vnum=9300, name="Promote", description="", room_flags=0, sector_type=0)
+    room.people = []
+    room.contents = []
+    room_registry[9300] = room
+    return room
+
+
+def _make_pc(room: Room, *, hit: int, position: Position) -> Character:
+    pc = Character(
+        name="Stunned",
+        level=20,
+        room=room,
+        is_npc=False,
+        hit=hit,
+        max_hit=200,
+        mana=100,
+        max_mana=100,
+        move=100,
+        max_move=100,
+        position=int(position),
+    )
+    pc.messages = []
+    pc.played = 0
+    pc.logon = 0
+    room.people.append(pc)
+    character_registry.append(pc)
+    return pc
+
+
+def test_heal_spell_promotes_stunned_to_standing_silently():
+    """cure_light on a STUNNED PC with hp<=0 must promote to STANDING.
+
+    ROM src/magic.c:1675 (spell_cure_light) calls update_pos(victim) after
+    adding heal dice.  The promotion is silent — no broadcast appears.
+    """
+    room = _make_room()
+    pc = _make_pc(room, hit=-1, position=Position.STUNNED)
+
+    cure_light(pc, pc)  # caster == target
+
+    assert pc.hit > 0, "test sanity: cure_light must restore positive hp"
+    assert pc.position == Position.STANDING, (
+        f"STUNNED PC with hp>0 must promote to STANDING (got {pc.position!r})"
+    )
+    # Silent promotion: only the self-line "You feel better!" is emitted,
+    # no position-transition broadcast like INV-016's downward lines.
+    broadcasts = [m for m in pc.messages if "stand" in m.lower() or "feet" in m.lower()]
+    assert broadcasts == [], (
+        f"Upward promotion must be silent (ROM update_pos is silent); "
+        f"saw broadcast-like messages: {broadcasts}"
+    )
+
+
+def test_regen_tick_promotes_stunned_to_standing():
+    """ROM src/update.c:714-715 — when a STUNNED char's regen tick lifts
+    hp above 0, update_pos must promote them to STANDING.
+
+    This pins the game_loop pipeline (_apply_regeneration → update_pos)
+    end-to-end against the load-bearing ROM order.
+    """
+    room = _make_room()
+    pc = _make_pc(room, hit=-2, position=Position.STUNNED)
+
+    # Simulate the STUNNED branch of char_update: regen first, then update_pos.
+    _apply_regeneration(pc)
+    if pc.position == Position.STUNNED:
+        update_pos(pc)
+
+    if pc.hit > 0:
+        assert pc.position == Position.STANDING, (
+            f"After regen tick lifted hp to {pc.hit}, STUNNED PC must promote "
+            f"to STANDING (got {pc.position!r})"
+        )
+    else:
+        # Regen wasn't enough this tick — must remain STUNNED, not demote.
+        assert pc.position == Position.STUNNED, (
+            f"hp still <= 0 ({pc.hit}); position must stay STUNNED "
+            f"(got {pc.position!r})"
+        )
+
+
+def test_update_pos_does_not_promote_above_stunned():
+    """ROM update_pos only acts on position <= POS_STUNNED.  A RESTING
+    PC with hp>0 must remain RESTING — update_pos must NOT force them
+    to STANDING.  Pins the `<= POS_STUNNED` guard.
+    """
+    room = _make_room()
+    pc = _make_pc(room, hit=100, position=Position.RESTING)
+
+    update_pos(pc)
+
+    assert pc.position == Position.RESTING, (
+        f"update_pos must not promote positions > STUNNED "
+        f"(RESTING PC ended up {pc.position!r})"
+    )