kirby-world 0.1.0__tar.gz

kirby_world-0.1.0/LICENSE

@@ -0,0 +1,149 @@
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree
+to them as both strict obligations and conditions to all
+your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the
+software to do everything you might do with the software
+that would otherwise infringe the licensor's copyright
+in it for any permitted purpose.  However, you may
+only distribute the software according to [Distribution
+License](#distribution-license) and make changes or new works
+based on the software according to [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license
+to distribute copies of the software.  Your license
+to distribute covers distributing the software with
+changes and new works permitted by [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of
+the software from you also gets a copy of these terms or the
+URL for them above, as well as copies of any plain-text lines
+beginning with `Required Notice:` that the licensor provided
+with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to
+make changes and new works based on the software for any
+permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that
+covers patent claims the licensor can license, or becomes able
+to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for
+the benefit of public knowledge, personal study, private
+entertainment, hobby projects, amateur pursuits, or religious
+observance, without any anticipated commercial application,
+is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution,
+public research organization, public safety or health
+organization, environmental protection organization,
+or government institution is use for a permitted purpose
+regardless of the source of funding or obligations resulting
+from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the
+law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of
+your licenses to anyone else, or prevent the licensor from
+granting licenses to anyone else.  These terms do not imply
+any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or
+contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If
+your company makes such a claim, your patent license ends
+immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have
+violated any of these terms, or done anything with the software
+not covered by your licenses, your licenses can nonetheless
+continue if you come into full compliance with these terms,
+and take practical steps to correct past violations, within
+32 days of receiving notice.  Otherwise, all your licenses
+end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without
+any warranty or condition, and the licensor will not be liable
+to you for any damages arising out of these terms or the use
+or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these
+terms, and the **software** is the software the licensor makes
+available under these terms.
+
+**You** refers to the individual or entity agreeing to these
+terms.
+
+**Your company** is any legal entity, sole proprietorship,
+or other kind of organization that you work for, plus all
+organizations that have control over, are under the control of,
+or are under common control with that organization.  **Control**
+means ownership of substantially all the assets of an entity,
+or the power to direct its management and policies by vote,
+contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the
+software under these terms.
+
+**Use** means anything you do with the software requiring one
+of your licenses.
+
+
+================================================================================
+NOTES SPECIFIC TO kirby-terrain
+================================================================================
+
+Required Notice: Copyright (c) 2026 Peter D Bethke
+
+(The line above begins with `Required Notice:` deliberately -- see the
+Notices section of the licence. It must travel with any copy of this
+software or any part of it.)
+
+This package reproduces no rules text or prose from the HERO System rulebook.
+The PD, ED and BODY values in `durability.py` are bare game statistics —
+numbers, not the rule or the writing around them — transcribed for use by
+this platform's engines.
+
+HERO System and HERO Designer are the property of their respective owners.

kirby_world-0.1.0/PKG-INFO

@@ -0,0 +1,56 @@
+Metadata-Version: 2.4
+Name: kirby-world
+Version: 0.1.0
+Summary: Places for the Kirby HERO System platform: Worlds, Scenes and the geometry inside them
+Author: PeterB
+License: PolyForm Noncommercial License 1.0.0
+Project-URL: Repository, https://github.com/pdbethke/kirby-world
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: kirby-terrain>=0.1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Dynamic: license-file
+
+# kirby-world
+
+Places for the Kirby HERO System platform: a `World` of `Scene`s, and the
+geometry inside them — surfaces, walls, furnishings, hazards, constructs,
+cover, falling, line of sight and per-mode movement reachability.
+
+A place is not a fight. A house with five people doing chores, and what is
+reachable from the kitchen, needs nothing but this package:
+
+```python
+from kirby_world import AmbientConditions, Position, Scene, SceneBounds
+from kirby_world.movement_legality import movement_reach
+
+house = Scene(id="house", name="Safehouse", bounds=SceneBounds(0, 0, 0, 20, 20, 4),
+              surfaces=[], walls=[], hazards=[], ambient=AmbientConditions())
+house = house.place_combatant("ana", Position(1.0, 0.0, 0.0))
+movement_reach("flight", Position(0, 0, 1), Position(5, 0, 1), 10.0, house).reachable
+```
+
+## Where it sits
+
+```
+kirby-terrain   what a thing is made of     no deps
+kirby-world     places                      -> kirby-terrain
+kirby-combat    the fight                   -> kirby-world, kirby-cost, kirby-dice
+```
+
+Questions about the person moving rather than the place — is he Stunned,
+what has this building already absorbed — belong to the fight. They arrive
+here as plain values (`mover_can_move`, a `damage` ledger), never as the
+fight itself. `tests/test_a_place_without_a_fight.py` enforces that by
+making the fight engine unimportable and building a house anyway.
+
+Split out of kirby-combat at 0.20.0, where `kirby_combat.scene` remains as a
+re-export of this package.
+
+## License
+
+PolyForm Noncommercial 1.0.0. Not affiliated with or endorsed by Hero Games.

kirby_world-0.1.0/README.md

@@ -0,0 +1,39 @@
+# kirby-world
+
+Places for the Kirby HERO System platform: a `World` of `Scene`s, and the
+geometry inside them — surfaces, walls, furnishings, hazards, constructs,
+cover, falling, line of sight and per-mode movement reachability.
+
+A place is not a fight. A house with five people doing chores, and what is
+reachable from the kitchen, needs nothing but this package:
+
+```python
+from kirby_world import AmbientConditions, Position, Scene, SceneBounds
+from kirby_world.movement_legality import movement_reach
+
+house = Scene(id="house", name="Safehouse", bounds=SceneBounds(0, 0, 0, 20, 20, 4),
+              surfaces=[], walls=[], hazards=[], ambient=AmbientConditions())
+house = house.place_combatant("ana", Position(1.0, 0.0, 0.0))
+movement_reach("flight", Position(0, 0, 1), Position(5, 0, 1), 10.0, house).reachable
+```
+
+## Where it sits
+
+```
+kirby-terrain   what a thing is made of     no deps
+kirby-world     places                      -> kirby-terrain
+kirby-combat    the fight                   -> kirby-world, kirby-cost, kirby-dice
+```
+
+Questions about the person moving rather than the place — is he Stunned,
+what has this building already absorbed — belong to the fight. They arrive
+here as plain values (`mover_can_move`, a `damage` ledger), never as the
+fight itself. `tests/test_a_place_without_a_fight.py` enforces that by
+making the fight engine unimportable and building a house anyway.
+
+Split out of kirby-combat at 0.20.0, where `kirby_combat.scene` remains as a
+re-export of this package.
+
+## License
+
+PolyForm Noncommercial 1.0.0. Not affiliated with or endorsed by Hero Games.

kirby_world-0.1.0/kirby_world/__init__.py

@@ -0,0 +1,57 @@
+"""kirby-world — places: a World of Scenes, and the geometry inside them.
+
+Pure: no dice, no rulebook engine, no database. A house with five people in
+it, and what is reachable from the kitchen, needs nothing else installed.
+The fight that may happen in a place lives in kirby-combat, which depends
+on this package and never the other way round.
+"""
+from kirby_world.construct import (
+    Construct,
+    ConstructEffect,
+    construct_from_hazard,
+    construct_from_spawn_spec,
+    construct_from_wall,
+    constructs_containing,
+    constructs_in,
+)
+from kirby_world.movement_legality import mode_requires_support
+from kirby_world.occupancy import blocked_by_furnishing, position_of
+from kirby_world.scene import (
+    AmbientConditions,
+    Furnishing,
+    Hazard,
+    HazardEffect,
+    Position,
+    Scene,
+    SceneBounds,
+    Surface,
+    Wall,
+    is_climbable,
+    wall_top_surface,
+)
+from kirby_world.world import World
+
+__all__ = [
+    "AmbientConditions",
+    "Construct",
+    "ConstructEffect",
+    "Furnishing",
+    "Hazard",
+    "HazardEffect",
+    "Position",
+    "Scene",
+    "SceneBounds",
+    "Surface",
+    "Wall",
+    "World",
+    "blocked_by_furnishing",
+    "construct_from_hazard",
+    "construct_from_spawn_spec",
+    "construct_from_wall",
+    "constructs_containing",
+    "constructs_in",
+    "is_climbable",
+    "mode_requires_support",
+    "position_of",
+    "wall_top_surface",
+]

kirby_world-0.1.0/kirby_world/construct.py

@@ -0,0 +1,275 @@
+"""Unified placed-entity model. A Construct is a destructible/effect-bearing
+region of the scene — walls, hazard zones, force walls, (reserved) illusion
+zones are all Constructs. Spec 2026-06-09 §1.1.
+
+The engine reasons over Constructs for durability + effect resolution; the
+authored Wall/Hazard dataclasses (scene.py) remain the template source and
+project into Constructs via the helpers here. Frozen: a Construct's `body` is
+the CURRENT body for one resolution; damage flows out as events and back via
+driver hydration on the next step.
+"""
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass, replace
+from typing import Literal
+
+from kirby_world.geometry import point_in_polygon_xy
+from kirby_world.scene import Hazard, Position, Wall
+
+EffectKind = Literal["damage", "suffocation", "status", "mental"]  # "mental" reserved (v1: not resolved)
+EffectGating = Literal["physical_def", "breathing_swimming", "mental_disbelief", "none"]
+EffectTrigger = Literal["on_enter", "on_pass", "every_segment", "passive"]
+ConstructKind = Literal["wall", "hazard_zone", "force_wall", "illusion_zone", "darkness_zone"]  # illusion_zone reserved
+Permeability = Literal["porous", "impermeable"]
+
+
+@dataclass(frozen=True)
+class ConstructEffect:
+    """A defense-gated consequence for occupants/passers of a Construct."""
+    kind: EffectKind
+    gating: EffectGating = "none"
+    trigger: EffectTrigger = "passive"
+    damage_dice: int = 0
+    damage_type: str = "normal"
+    status_inflicted: str | None = None
+
+
+@dataclass(frozen=True)
+class Construct:
+    """An independently placed region with optional durability and effect."""
+    obj_id: str
+    kind: ConstructKind
+    # geometry: a segment (walls/barriers) OR a polygon (zones) — exactly one
+    segment: tuple[Position, Position] | None = None
+    polygon_xy: list[tuple[float, float]] | None = None
+    elevation_range_m: tuple[float, float] = (0.0, 0.0)
+    height_m: float = 0.0
+    # blocking / cover
+    blocks_los: bool = False
+    blocks_movement: bool = False
+    permeability: Permeability = "porous"
+    cover_level: int = 0
+    #: Levels of "Cannot Be Escaped With Teleportation" on the source
+    #: Barrier (6E1 p175): a teleport path may not pass this construct
+    #: unless the Teleportation carries at least as many levels of
+    #: Armor Piercing (movement_legality gates on it). 0 = no effect.
+    no_teleport_levels: int = 0
+    # durability (both None => indestructible). `body` is CURRENT body.
+    #: Can somebody strong enough pick this up and throw it?
+    #:
+    #: PORTABLE IS A PROPERTY OF THE OBJECT, not a kind of object. `pickup`
+    #: used to filter on `kind == "debris"` --- a kind that is not in
+    #: `ConstructKind` and that nothing in this engine has ever created, so
+    #: `pickup` and `throw_object` were two complete action kinds that
+    #: could never fire. A whiskey barrel is not rubble and never becomes
+    #: any; a wagon is not a special sort of wall. Both are simply things
+    #: light enough to lift, which is what the weight gate already asks.
+    portable: bool = False
+    def_value: int | None = None
+    ed_value: int | None = None             # ED, when it differs from PD (6E2 p173)
+    resistant: bool = True                  # False = Normal Defense, not applied vs Killing
+    body: int | None = None
+    #: The obj_id of the structure this is a FACE of. Rides across from
+    #: `Wall.part_of` --- and MUST, because the resolvers act on the
+    #: projected Construct, so a face that lost this on the way through
+    #: would be demolished as a building instead of breached as a wall.
+    part_of: str | None = None
+    # effect / provenance
+    effect: ConstructEffect | None = None
+    source_combatant_id: str | None = None
+    created_at_seq: int | None = None
+    # sense-affecting (darkness_zone): the Sense Group this zone occludes
+    # (e.g. "sight", "mental") and whether the creating combatant sees through it.
+    sense_group: str | None = None
+    creator_immune: bool = False
+
+    @property
+    def destructible(self) -> bool:
+        return self.def_value is not None and self.body is not None
+
+    @property
+    def pd(self) -> int | None:
+        """Physical defense. `def_value` has always meant PD; this names it."""
+        return self.def_value
+
+    @property
+    def ed(self) -> int | None:
+        """Energy defense, falling back to PD when the construct does not state
+        one. The fallback is what keeps every pre-existing construct -- here and
+        in kirby-api, which constructs these by keyword -- behaving exactly
+        as it did before PD and ED were separated."""
+        return self.def_value if self.ed_value is None else self.ed_value
+
+
+def construct_from_spawn_spec(
+    *,
+    obj_id: str,
+    kind: ConstructKind,
+    segment: tuple[Position, Position] | None = None,
+    polygon_xy: list[tuple[float, float]] | None = None,
+    elevation_range_m: tuple[float, float] = (0.0, 0.0),
+    height_m: float = 0.0,
+    def_value: int | None = None,
+    body: int | None = None,
+    effect: ConstructEffect | None = None,
+    permeability: Permeability | None = None,
+    source_combatant_id: str | None = None,
+    created_at_seq: int | None = None,
+    sense_group: str | None = None,
+    creator_immune: bool = False,
+) -> Construct:
+    """Build a spawned Construct (force wall / spawn-on-destroy hazard). A
+    force_wall defaults to a LoS+movement blocking impermeable barrier; a
+    hazard_zone defaults to porous. the driver computes def/body/geometry from the
+    casting power (Plan 2) and passes them here. Spec §1.7."""
+    if permeability is None:
+        permeability = "impermeable" if kind in ("wall", "force_wall") else "porous"
+    blocks = kind in ("wall", "force_wall")
+    return Construct(
+        obj_id=obj_id, kind=kind, segment=segment, polygon_xy=polygon_xy,
+        elevation_range_m=elevation_range_m, height_m=height_m,
+        blocks_los=blocks, blocks_movement=blocks, permeability=permeability,
+        cover_level=4 if blocks else 0,
+        def_value=def_value, body=body, effect=effect,
+        source_combatant_id=source_combatant_id, created_at_seq=created_at_seq,
+        sense_group=sense_group, creator_immune=creator_immune,
+    )
+
+
+def constructs_containing(pos: Position, constructs: Iterable[Construct]) -> list[Construct]:
+    """Return constructs whose polygon contains `pos` in xy within their elevation
+    range (segment constructs are never 'containing' a point)."""
+    out: list[Construct] = []
+    for c in constructs:
+        if c.polygon_xy is None:
+            continue
+        lo, hi = c.elevation_range_m
+        if not (lo <= pos.z <= hi):
+            continue
+        if point_in_polygon_xy((pos.x, pos.y), c.polygon_xy):
+            out.append(c)
+    return out
+
+
+def construct_from_wall(wall: Wall) -> Construct:
+    """Project an authored Wall into a Construct. `def_value` rides Wall.def_value
+    (None on legacy walls with no authored DEF)."""
+    return Construct(
+        obj_id=wall.id, kind="wall",
+        segment=wall.segment, height_m=wall.height_m,
+        blocks_los=wall.blocks_los, blocks_movement=wall.blocks_movement,
+        permeability="impermeable" if wall.blocks_movement else "porous",
+        cover_level=wall.cover_level,
+        def_value=wall.def_value, ed_value=wall.ed_value, resistant=wall.resistant,
+        body=wall.body, part_of=wall.part_of,
+    )
+
+
+def construct_from_hazard(hazard: Hazard) -> Construct:
+    """Project a legacy authored Hazard into a hazard_zone Construct (porous,
+    physical-DEF-gated damage or a status). Suffocation hazards are authored as
+    Constructs directly by the driver, not via the legacy Hazard model."""
+    eff = hazard.effect
+    if not eff.damage_dice and not eff.status_inflicted:
+        raise ValueError(
+            f"Hazard {hazard.id!r}: HazardEffect has neither damage_dice nor "
+            "status_inflicted — nothing to project into a Construct effect"
+        )
+    kind: EffectKind = "damage" if eff.damage_dice else "status"
+    return Construct(
+        obj_id=hazard.id, kind="hazard_zone",
+        polygon_xy=list(hazard.polygon_xy), elevation_range_m=hazard.elevation_range_m,
+        permeability="porous",
+        effect=ConstructEffect(
+            kind=kind,
+            gating="physical_def" if kind == "damage" else "none",
+            trigger=hazard.trigger,
+            damage_dice=eff.damage_dice, damage_type=eff.damage_type,
+            status_inflicted=eff.status_inflicted,
+        ),
+    )
+
+
+def constructs_in(scene, damage: Mapping[str, int] | None = None) -> list[Construct]:
+    """Everything in this scene that an attack can be aimed AT.
+
+    The authored constructs, plus every authored `Wall` projected through
+    `construct_from_wall`. THE PROJECTION EXISTED AND NOTHING CALLED IT:
+    `attack_construct` iterates constructs, so before this the O.K.
+    Corral's buildings, barrels and packing crates were not in the fight
+    at all, and `smash_cover` --- a tactic whose whole purpose is
+    destroying what somebody is hiding behind --- had nothing to smash.
+
+    Indestructible walls are left out. `def_value is None` is this
+    engine's word for "legacy / indestructible", and a target nothing can
+    hurt is an offer that wastes a Phase.
+
+    Walls stay in `scene.walls` as well: movement and line of sight read
+    them there, and this is a second VIEW of the same geometry rather than
+    a second copy of it.
+
+    `damage` is BODY already lost, by `obj_id`. A place does not know what
+    happened to it --- the fight that did the damage keeps that ledger
+    (kirby-combat folds it from its event log) and hands the totals in.
+    Without it these are the constructs as authored.
+    """
+    out = list(getattr(scene, "constructs", None) or [])
+    seen = {getattr(c, "obj_id", None) for c in out}
+    # FURNISHINGS ARE THINGS YOU CAN SHOOT. A wagon nobody can hit is a
+    # wagon nobody can shoot the cover out from under, which is precisely
+    # what `smash_cover` exists to do. Their durability comes from 6E2
+    # p.173's Objects Table via the material they name, so nobody types a
+    # BODY into a scene file by hand.
+    for f in (getattr(scene, "furnishings", None) or []):
+        if f.id in seen:
+            continue
+        seen.add(f.id)
+        out.append(Construct(
+            obj_id=f.id, kind="wall",
+            polygon_xy=list(f.polygon_xy),
+            elevation_range_m=(0.0, f.height_m),
+            body=f.body_value, def_value=f.pd_value,
+            ed_value=f.ed_value,
+            blocks_los=f.blocks_los,
+            blocks_movement=f.blocks_movement,
+            # A flag that stops at the projection is the same defect one
+            # layer down -- see `Furnishing.portable`.
+            portable=f.portable,
+        ))
+    for wall in (getattr(scene, "walls", None) or []):
+        if getattr(wall, "def_value", None) is None:
+            continue
+        if wall.id in seen:
+            continue
+        # A FURNISHING'S EDGES ARE THAT FURNISHING, which is already in
+        # this list. Without this a wagon is FIVE targets --- itself and
+        # its four sides, each a separate offer with the same DEF and
+        # BODY. Measured on the long street: 30 constructs from 5
+        # furnishings and 25 walls, 25 of them five objects repeated, and
+        # a menu where `attack_construct` and `rapid_fire` were about
+        # nine offers in ten.
+        if hasattr(scene, "is_furnishing_edge") and scene.is_furnishing_edge(wall):
+            continue
+        out.append(construct_from_wall(wall))
+
+    # HYDRATION. Without a damage ledger these are the buildings as
+    # authored, which is what every caller that has no fight wants.
+    if damage is not None:
+        hydrated = []
+        for c in out:
+            if c.body is None:
+                hydrated.append(c)
+                continue
+            left = max(0, c.body - int(damage.get(c.obj_id, 0)))
+            # RUBBLE IS NOT A BUILDING. A destroyed construct used to stay
+            # in the scene and be knocked over again --- the Harwood House
+            # came down on Tom McLaury, Frank McLaury and Billy Clanton,
+            # and then came down on them three more times. Once its BODY
+            # is gone it stops being a thing you can shoot, hide behind,
+            # or drop on somebody.
+            if left <= 0:
+                continue
+            hydrated.append(replace(c, body=left))
+        out = hydrated
+    return out