crimsonland 0.1.0.dev5__py3-none-any.whl

crimson/persistence/__init__.py

@@ -0,0 +1 @@
+from __future__ import annotations

crimson/persistence/highscores.py

@@ -0,0 +1,385 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+import datetime as dt
+from pathlib import Path
+import struct
+
+from grim.config import CrimsonConfig
+
+
+RECORD_SIZE = 0x48
+RECORD_WIRE_SIZE = RECORD_SIZE + 4  # record + checksum
+TABLE_MAX = 100
+
+NAME_SIZE = 0x20
+NAME_MAX_EDIT = 0x14  # game_over_screen_update sets ui_text_input maxlen=0x14
+
+
+def _clamp_u32(value: int) -> int:
+    return int(value) & 0xFFFFFFFF
+
+
+def _score_checksum(data: bytes) -> int:
+    if len(data) != RECORD_SIZE:
+        raise ValueError(f"expected {RECORD_SIZE:#x} bytes, got {len(data):#x}")
+    checksum = 0
+    for idx, b in enumerate(data):
+        checksum = _clamp_u32(checksum + (idx + 3) * int(b) * 7)
+    return checksum
+
+
+def _encode_byte(value: int, idx: int) -> int:
+    # highscore_write_record: b += ((idx * 5 + 1) * idx + 6)
+    return (int(value) + (idx * 5 + 1) * idx + 6) & 0xFF
+
+
+def _decode_byte(value: int, idx: int) -> int:
+    # highscore_read_record: b += (-6 - ((idx * 5 + 1) * idx))
+    return (int(value) - ((idx * 5 + 1) * idx + 6)) & 0xFF
+
+
+def highscore_date_checksum(year: int, month: int, day: int) -> int:
+    """Port of `highscore_date_checksum` (0x0043a950)."""
+    i_var1 = (0x0E - int(month)) // 0x0C
+    i_var2 = (int(year) - i_var1) + 0x12C0
+    i_var1 = (
+        ((i_var2 + ((i_var2 >> 31) & 3)) >> 2)
+        - 0x7D2D
+        + int(day)
+        + ((i_var2 // 400 + (((int(month) + i_var1 * 0x0C) * 0x99 - 0x1C9) // 5 + i_var2 * 0x16D)) - i_var2 // 100)
+    )
+    i_var2 = ((((i_var1 - i_var1 % 7) + 0x7BFD) % 0x23AB1) % 0x8EAC) % 0x5B5
+    i_var1 = i_var2 // 0x5B4
+    return ((i_var2 - i_var1) % 0x16D + i_var1) // 7 + 1
+
+
+@dataclass(slots=True)
+class HighScoreRecord:
+    data: bytearray
+
+    @classmethod
+    def blank(cls) -> HighScoreRecord:
+        data = bytearray(RECORD_SIZE)
+        data[0x46] = 0x7C
+        data[0x47] = 0xFF
+        return cls(data=data)
+
+    @classmethod
+    def from_bytes(cls, data: bytes) -> HighScoreRecord:
+        if len(data) != RECORD_SIZE:
+            raise ValueError(f"expected {RECORD_SIZE:#x} bytes, got {len(data):#x}")
+        return cls(data=bytearray(data))
+
+    def copy(self) -> HighScoreRecord:
+        return HighScoreRecord(data=bytearray(self.data))
+
+    def name(self) -> str:
+        raw = bytes(self.data[:NAME_SIZE])
+        return raw.split(b"\x00", 1)[0].decode("latin-1", errors="ignore")
+
+    def set_name(self, value: str) -> None:
+        encoded = value.encode("latin-1", errors="ignore")[: NAME_SIZE - 1]
+        self.data[:NAME_SIZE] = b"\x00" * NAME_SIZE
+        self.data[: len(encoded)] = encoded
+        self.data[min(len(encoded), NAME_SIZE - 1)] = 0
+
+    def trim_trailing_spaces(self) -> None:
+        # highscore_save_record: strips trailing spaces (0x20) in-place before saving.
+        raw = self.data[:NAME_SIZE]
+        end = raw.find(0)
+        if end < 0:
+            end = NAME_SIZE
+        i = end - 1
+        while i > 0 and raw[i] == 0x20:
+            raw[i] = 0
+            i -= 1
+
+    @property
+    def survival_elapsed_ms(self) -> int:
+        return int(struct.unpack_from("<I", self.data, 0x20)[0])
+
+    @survival_elapsed_ms.setter
+    def survival_elapsed_ms(self, value: int) -> None:
+        struct.pack_into("<I", self.data, 0x20, int(value) & 0xFFFFFFFF)
+
+    @property
+    def score_xp(self) -> int:
+        return int(struct.unpack_from("<I", self.data, 0x24)[0])
+
+    @score_xp.setter
+    def score_xp(self, value: int) -> None:
+        struct.pack_into("<I", self.data, 0x24, int(value) & 0xFFFFFFFF)
+
+    @property
+    def game_mode_id(self) -> int:
+        return int(self.data[0x28])
+
+    @game_mode_id.setter
+    def game_mode_id(self, value: int) -> None:
+        self.data[0x28] = int(value) & 0xFF
+
+    @property
+    def quest_stage_major(self) -> int:
+        return int(self.data[0x29])
+
+    @quest_stage_major.setter
+    def quest_stage_major(self, value: int) -> None:
+        self.data[0x29] = int(value) & 0xFF
+
+    @property
+    def quest_stage_minor(self) -> int:
+        return int(self.data[0x2A])
+
+    @quest_stage_minor.setter
+    def quest_stage_minor(self, value: int) -> None:
+        self.data[0x2A] = int(value) & 0xFF
+
+    @property
+    def most_used_weapon_id(self) -> int:
+        return int(self.data[0x2B])
+
+    @most_used_weapon_id.setter
+    def most_used_weapon_id(self, value: int) -> None:
+        self.data[0x2B] = int(value) & 0xFF
+
+    @property
+    def shots_fired(self) -> int:
+        return int(struct.unpack_from("<I", self.data, 0x2C)[0])
+
+    @shots_fired.setter
+    def shots_fired(self, value: int) -> None:
+        struct.pack_into("<I", self.data, 0x2C, int(value) & 0xFFFFFFFF)
+
+    @property
+    def shots_hit(self) -> int:
+        return int(struct.unpack_from("<I", self.data, 0x30)[0])
+
+    @shots_hit.setter
+    def shots_hit(self, value: int) -> None:
+        struct.pack_into("<I", self.data, 0x30, int(value) & 0xFFFFFFFF)
+
+    @property
+    def creature_kill_count(self) -> int:
+        return int(struct.unpack_from("<I", self.data, 0x34)[0])
+
+    @creature_kill_count.setter
+    def creature_kill_count(self, value: int) -> None:
+        struct.pack_into("<I", self.data, 0x34, int(value) & 0xFFFFFFFF)
+
+    @property
+    def reserved0(self) -> int:
+        return int(struct.unpack_from("<I", self.data, 0x38)[0])
+
+    @reserved0.setter
+    def reserved0(self, value: int) -> None:
+        struct.pack_into("<I", self.data, 0x38, int(value) & 0xFFFFFFFF)
+
+    @property
+    def day(self) -> int:
+        return int(self.data[0x40])
+
+    @property
+    def month(self) -> int:
+        return int(self.data[0x42])
+
+    @property
+    def year_offset(self) -> int:
+        return int(self.data[0x43])
+
+    @property
+    def flags(self) -> int:
+        return int(self.data[0x44])
+
+    @flags.setter
+    def flags(self, value: int) -> None:
+        self.data[0x44] = int(value) & 0xFF
+
+    @property
+    def full_version_marker(self) -> int:
+        return int(self.data[0x45])
+
+    @full_version_marker.setter
+    def full_version_marker(self, value: int) -> None:
+        self.data[0x45] = int(value) & 0xFF
+
+    def ensure_date_fields(self, now: dt.date | None = None) -> None:
+        if int(self.data[0x40]) != 0:
+            return
+        if now is None:
+            now = dt.date.today()
+        self.data[0x40] = int(now.day) & 0xFF
+        self.data[0x42] = int(now.month) & 0xFF
+        self.data[0x43] = int(now.year - 2000) & 0xFF
+        self.data[0x41] = int(highscore_date_checksum(now.year, now.month, now.day)) & 0xFF
+
+
+def scores_dir_for_base_dir(base_dir: Path) -> Path:
+    # Original uses CreateDirectoryA("scores5") relative to cwd.
+    return base_dir / "scores5"
+
+
+def scores_path_for_mode(
+    base_dir: Path,
+    game_mode_id: int,
+    *,
+    hardcore: bool = False,
+    quest_stage_major: int = 0,
+    quest_stage_minor: int = 0,
+) -> Path:
+    root = scores_dir_for_base_dir(base_dir)
+    mode = int(game_mode_id)
+    if mode == 1:
+        return root / "survival.hi"
+    if mode == 2:
+        return root / "rush.hi"
+    if mode == 4:
+        return root / "typo.hi"
+    if mode == 3:
+        # Native `highscore_build_path` uses `questhc*.hi` when hardcore is OFF,
+        # and `quest*.hi` when hardcore is ON.
+        prefix = "quest" if hardcore else "questhc"
+        return root / f"{prefix}{int(quest_stage_major)}_{int(quest_stage_minor)}.hi"
+    return root / "unknown.hi"
+
+
+def scores_path_for_config(base_dir: Path, config: CrimsonConfig, *, quest_stage_major: int = 0, quest_stage_minor: int = 0) -> Path:
+    mode = int(config.data.get("game_mode", 1))
+    root = scores_dir_for_base_dir(base_dir)
+    if mode == 1:
+        return root / "survival.hi"
+    if mode == 2:
+        return root / "rush.hi"
+    if mode == 4:
+        return root / "typo.hi"
+    if mode == 3:
+        hardcore = bool(int(config.data.get("hardcore_flag", 0) or 0))
+        if int(quest_stage_major) == 0 and int(quest_stage_minor) == 0:
+            major = int(config.data.get("quest_stage_major", 0) or 0)
+            minor = int(config.data.get("quest_stage_minor", 0) or 0)
+            if major == 0 and minor == 0:
+                level = config.data.get("quest_level")
+                if isinstance(level, str):
+                    try:
+                        major_text, minor_text = level.split(".", 1)
+                        major = int(major_text)
+                        minor = int(minor_text)
+                    except Exception:
+                        major = 0
+                        minor = 0
+            quest_stage_major = major
+            quest_stage_minor = minor
+        # Native `highscore_build_path` uses `questhc*.hi` when hardcore is OFF,
+        # and `quest*.hi` when hardcore is ON.
+        prefix = "quest" if hardcore else "questhc"
+        return root / f"{prefix}{int(quest_stage_major)}_{int(quest_stage_minor)}.hi"
+    return root / "unknown.hi"
+
+
+def decode_record_payload(encoded: bytes) -> bytes:
+    if len(encoded) != RECORD_SIZE:
+        raise ValueError(f"expected {RECORD_SIZE:#x} bytes, got {len(encoded):#x}")
+    out = bytearray(encoded)
+    for idx in range(RECORD_SIZE):
+        out[idx] = _decode_byte(out[idx], idx)
+    return bytes(out)
+
+
+def encode_record_payload(decoded: bytes) -> bytes:
+    if len(decoded) != RECORD_SIZE:
+        raise ValueError(f"expected {RECORD_SIZE:#x} bytes, got {len(decoded):#x}")
+    out = bytearray(decoded)
+    for idx in range(RECORD_SIZE):
+        out[idx] = _encode_byte(out[idx], idx)
+    return bytes(out)
+
+
+def read_highscore_records(path: Path) -> list[HighScoreRecord]:
+    if not path.is_file():
+        return []
+    records: list[HighScoreRecord] = []
+    with path.open("rb") as fp:
+        while True:
+            blob = fp.read(RECORD_WIRE_SIZE)
+            if not blob:
+                break
+            if len(blob) != RECORD_WIRE_SIZE:
+                break
+            payload = blob[:RECORD_SIZE]
+            stored_checksum = int(struct.unpack_from("<I", blob, RECORD_SIZE)[0])
+            decoded = decode_record_payload(payload)
+            computed = _score_checksum(decoded)
+            if computed != stored_checksum:
+                continue
+            records.append(HighScoreRecord.from_bytes(decoded))
+    return records
+
+
+def write_highscore_records(path: Path, records: list[HighScoreRecord]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("wb") as fp:
+        for record in records:
+            record = record.copy()
+            record.trim_trailing_spaces()
+            record.ensure_date_fields()
+            encoded = encode_record_payload(bytes(record.data))
+            checksum = _score_checksum(bytes(record.data))
+            fp.write(encoded)
+            fp.write(struct.pack("<I", checksum))
+
+
+def read_highscore_table(path: Path, *, game_mode_id: int) -> list[HighScoreRecord]:
+    records = read_highscore_records(path)
+    records = [r for r in records if int(r.game_mode_id) == int(game_mode_id)]
+    return sort_highscores(records, game_mode_id=game_mode_id)[:TABLE_MAX]
+
+
+def sort_highscores(records: list[HighScoreRecord], *, game_mode_id: int) -> list[HighScoreRecord]:
+    mode = int(game_mode_id)
+    if mode == 2:
+        return sorted(records, key=lambda r: int(r.survival_elapsed_ms), reverse=True)
+    if mode == 3:
+        def _quest_key(r: HighScoreRecord) -> tuple[int, int]:
+            value = int(r.survival_elapsed_ms)
+            if value == 0:
+                return (1, 0)
+            return (0, value)
+        return sorted(records, key=_quest_key)
+    return sorted(records, key=lambda r: int(r.score_xp), reverse=True)
+
+
+def rank_index(records_sorted: list[HighScoreRecord], record: HighScoreRecord) -> int:
+    mode = int(record.game_mode_id)
+    if mode == 2:
+        score = int(record.survival_elapsed_ms)
+        for idx, entry in enumerate(records_sorted):
+            if score > int(entry.survival_elapsed_ms):
+                return idx
+        return len(records_sorted)
+    if mode == 3:
+        score = int(record.survival_elapsed_ms)
+        for idx, entry in enumerate(records_sorted):
+            other = int(entry.survival_elapsed_ms)
+            if other == 0:
+                return idx
+            if score < other:
+                return idx
+        return len(records_sorted)
+    score = int(record.score_xp)
+    for idx, entry in enumerate(records_sorted):
+        if score > int(entry.score_xp):
+            return idx
+    return len(records_sorted)
+
+
+def upsert_highscore_record(path: Path, record: HighScoreRecord) -> tuple[list[HighScoreRecord], int]:
+    """Save `record` into the mode table, returning (sorted_records, rank_index)."""
+    records_sorted = read_highscore_table(path, game_mode_id=record.game_mode_id)
+    idx = rank_index(records_sorted, record)
+    if idx >= TABLE_MAX:
+        return records_sorted, idx
+    updated = list(records_sorted)
+    updated.insert(idx, record.copy())
+    updated = updated[:TABLE_MAX]
+    write_highscore_records(path, updated)
+    return updated, idx

crimson/persistence/save_status.py

@@ -0,0 +1,245 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from construct import Array, Bytes, Int16ul, Int32ul, Struct
+
+GAME_CFG_NAME = "game.cfg"
+
+BLOB_SIZE = 0x268
+FILE_SIZE = BLOB_SIZE + 4
+
+WEAPON_USAGE_COUNT = 53
+
+# Quest play count length inferred from known trailing fields in the blob (0xD8..0x244).
+QUEST_PLAY_COUNT = 91
+
+MODE_COUNT_ORDER = (
+    ("survival", "mode_play_survival"),
+    ("rush", "mode_play_rush"),
+    ("typo", "mode_play_typo"),
+    ("other", "mode_play_other"),
+)
+
+UNKNOWN_TAIL_SIZE = 0x10
+
+GAME_STATUS_STRUCT = Struct(
+    "quest_unlock_index" / Int16ul,
+    "quest_unlock_index_full" / Int16ul,
+    "weapon_usage_counts" / Array(WEAPON_USAGE_COUNT, Int32ul),
+    "quest_play_counts" / Array(QUEST_PLAY_COUNT, Int32ul),
+    "mode_play_survival" / Int32ul,
+    "mode_play_rush" / Int32ul,
+    "mode_play_typo" / Int32ul,
+    "mode_play_other" / Int32ul,
+    "game_sequence_id" / Int32ul,
+    "unknown_tail" / Bytes(UNKNOWN_TAIL_SIZE),
+)
+
+GAME_CFG_STRUCT = Struct(
+    "encoded" / Bytes(BLOB_SIZE),
+    "checksum" / Int32ul,
+)
+
+
+@dataclass(slots=True)
+class StatusBlob:
+    decoded: bytes
+    checksum: int
+    checksum_expected: int
+
+    @property
+    def checksum_valid(self) -> bool:
+        return (self.checksum & 0xFFFFFFFF) == (self.checksum_expected & 0xFFFFFFFF)
+
+
+@dataclass(slots=True)
+class GameStatus:
+    path: Path
+    data: dict
+    dirty: bool = False
+
+    @property
+    def quest_unlock_index(self) -> int:
+        return int(self.data["quest_unlock_index"])
+
+    @quest_unlock_index.setter
+    def quest_unlock_index(self, value: int) -> None:
+        self.data["quest_unlock_index"] = int(value) & 0xFFFF
+        self.dirty = True
+
+    @property
+    def quest_unlock_index_full(self) -> int:
+        return int(self.data["quest_unlock_index_full"])
+
+    @quest_unlock_index_full.setter
+    def quest_unlock_index_full(self, value: int) -> None:
+        self.data["quest_unlock_index_full"] = int(value) & 0xFFFF
+        self.dirty = True
+
+    @property
+    def game_sequence_id(self) -> int:
+        return int(self.data["game_sequence_id"])
+
+    @game_sequence_id.setter
+    def game_sequence_id(self, value: int) -> None:
+        self.data["game_sequence_id"] = int(value) & 0xFFFFFFFF
+        self.dirty = True
+
+    def mode_play_count(self, name: str) -> int:
+        for mode_name, field in MODE_COUNT_ORDER:
+            if mode_name == name:
+                return int(self.data[field])
+        raise KeyError(f"unknown mode: {name}")
+
+    def increment_mode_play_count(self, name: str, delta: int = 1) -> int:
+        for mode_name, field in MODE_COUNT_ORDER:
+            if mode_name == name:
+                value = (int(self.data[field]) + int(delta)) & 0xFFFFFFFF
+                self.data[field] = value
+                self.dirty = True
+                return value
+        raise KeyError(f"unknown mode: {name}")
+
+    def weapon_usage_count(self, weapon_id: int) -> int:
+        weapon_id = int(weapon_id)
+        if not (0 <= weapon_id < WEAPON_USAGE_COUNT):
+            raise IndexError(f"weapon_id out of range: {weapon_id}")
+        return int(self.data["weapon_usage_counts"][weapon_id])
+
+    def increment_weapon_usage(self, weapon_id: int, delta: int = 1) -> int:
+        weapon_id = int(weapon_id)
+        if not (0 <= weapon_id < WEAPON_USAGE_COUNT):
+            raise IndexError(f"weapon_id out of range: {weapon_id}")
+        counts = self.data["weapon_usage_counts"]
+        value = (int(counts[weapon_id]) + int(delta)) & 0xFFFFFFFF
+        counts[weapon_id] = value
+        self.dirty = True
+        return value
+
+    def quest_play_count(self, index: int) -> int:
+        index = int(index)
+        if not (0 <= index < QUEST_PLAY_COUNT):
+            raise IndexError(f"quest index out of range: {index}")
+        return int(self.data["quest_play_counts"][index])
+
+    def increment_quest_play_count(self, index: int, delta: int = 1) -> int:
+        index = int(index)
+        if not (0 <= index < QUEST_PLAY_COUNT):
+            raise IndexError(f"quest index out of range: {index}")
+        counts = self.data["quest_play_counts"]
+        value = (int(counts[index]) + int(delta)) & 0xFFFFFFFF
+        counts[index] = value
+        self.dirty = True
+        return value
+
+    def unknown_tail(self) -> bytes:
+        return bytes(self.data["unknown_tail"])
+
+    def save(self) -> None:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        decoded = build_status_blob(self.data)
+        save_status(self.path, decoded)
+        self.dirty = False
+
+    def save_if_dirty(self) -> None:
+        if self.dirty:
+            self.save()
+
+
+def to_s8(value: int) -> int:
+    value &= 0xFF
+    return value - 0x100 if value & 0x80 else value
+
+
+def index_poly(idx: int) -> int:
+    i = to_s8(idx)
+    return ((i * 7 + 0x0F) * i + 0x03) * i
+
+
+def decode_blob(encoded: bytes) -> bytes:
+    if len(encoded) != BLOB_SIZE:
+        raise ValueError(f"decoded blob must be {BLOB_SIZE:#x} bytes, got {len(encoded):#x}")
+    decoded = bytearray(encoded)
+    for i in range(BLOB_SIZE):
+        decoded[i] = (decoded[i] - 0x6F - index_poly(i)) & 0xFF
+    return bytes(decoded)
+
+
+def encode_blob(decoded: bytes) -> bytes:
+    if len(decoded) != BLOB_SIZE:
+        raise ValueError(f"decoded blob must be {BLOB_SIZE:#x} bytes, got {len(decoded):#x}")
+    encoded = bytearray(decoded)
+    for i in range(BLOB_SIZE):
+        encoded[i] = (encoded[i] + 0x6F + index_poly(i)) & 0xFF
+    return bytes(encoded)
+
+
+def compute_checksum(decoded: bytes) -> int:
+    acc = 0
+    u = 0
+    for i, b in enumerate(decoded):
+        c = to_s8(b)
+        i_var5 = (c * 7 + i) * c + u
+        acc = (acc + 0x0D + i_var5) & 0xFFFFFFFF
+        u += 0x6F
+    return acc
+
+
+def load_status(path: Path) -> StatusBlob:
+    raw = path.read_bytes()
+    if len(raw) != FILE_SIZE:
+        raise ValueError(f"expected {FILE_SIZE:#x} bytes, got {len(raw):#x}")
+    parsed = GAME_CFG_STRUCT.parse(raw)
+    encoded = bytes(parsed["encoded"])
+    stored_checksum = int(parsed["checksum"])
+    decoded = decode_blob(encoded)
+    computed = compute_checksum(decoded)
+    return StatusBlob(decoded=decoded, checksum=stored_checksum, checksum_expected=computed)
+
+
+def save_status(path: Path, decoded: bytes) -> None:
+    checksum = compute_checksum(decoded)
+    encoded = encode_blob(decoded)
+    path.write_bytes(GAME_CFG_STRUCT.build({"encoded": encoded, "checksum": checksum}))
+
+
+def parse_status_blob(decoded: bytes) -> dict:
+    if len(decoded) != BLOB_SIZE:
+        raise ValueError(f"expected decoded blob of {BLOB_SIZE:#x} bytes, got {len(decoded):#x}")
+    return GAME_STATUS_STRUCT.parse(decoded)
+
+
+def build_status_blob(data: dict) -> bytes:
+    decoded = GAME_STATUS_STRUCT.build(data)
+    if len(decoded) != BLOB_SIZE:
+        raise ValueError(f"expected decoded blob of {BLOB_SIZE:#x} bytes, got {len(decoded):#x}")
+    return decoded
+
+
+def default_status_data() -> dict:
+    return parse_status_blob(bytes(BLOB_SIZE))
+
+
+def default_status_blob() -> bytes:
+    return bytes(BLOB_SIZE)
+
+
+def ensure_game_status(base_dir: Path) -> GameStatus:
+    path = base_dir / GAME_CFG_NAME
+    if path.exists():
+        try:
+            blob = load_status(path)
+            if not blob.checksum_valid:
+                raise ValueError("checksum mismatch")
+            data = parse_status_blob(blob.decoded)
+        except Exception:
+            data = default_status_data()
+            decoded = build_status_blob(data)
+            save_status(path, decoded)
+        return GameStatus(path=path, data=data, dirty=False)
+    data = default_status_data()
+    decoded = build_status_blob(data)
+    save_status(path, decoded)
+    return GameStatus(path=path, data=data, dirty=False)

crimson/player_damage.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+"""Player damage intake helpers.
+
+This is a minimal, rewrite-focused port of `player_take_damage` (0x00425e50).
+See: `docs/crimsonland-exe/player-damage.md`.
+"""
+
+from typing import Callable
+
+from .gameplay import GameplayState, PlayerState, perk_active
+from .perks import PerkId
+
+__all__ = ["player_take_damage"]
+
+
+def player_take_damage(
+    state: GameplayState,
+    player: PlayerState,
+    damage: float,
+    *,
+    dt: float | None = None,
+    rand: Callable[[], int] | None = None,
+) -> float:
+    """Apply damage to a player, returning the actual damage applied.
+
+    Notes:
+    - This models only the must-have gates used by creature contact damage.
+    - Low-health warning timers are not yet ported.
+    """
+
+    dmg = float(damage)
+    if dmg <= 0.0:
+        return 0.0
+
+    # 1) Death Clock immunity.
+    if perk_active(player, PerkId.DEATH_CLOCK):
+        return 0.0
+
+    # 2) Tough Reloader mitigation while reloading.
+    if perk_active(player, PerkId.TOUGH_RELOADER) and bool(player.reload_active):
+        dmg *= 0.5
+
+    # 3) Shield immunity.
+    if float(player.shield_timer) > 0.0:
+        return 0.0
+
+    # Damage scaling perks.
+    if perk_active(player, PerkId.THICK_SKINNED):
+        dmg *= 2.0 / 3.0
+
+    rng = rand or state.rng.rand
+    if perk_active(player, PerkId.NINJA):
+        if (rng() % 3) == 0:
+            return 0.0
+    elif perk_active(player, PerkId.DODGER):
+        if (rng() % 5) == 0:
+            return 0.0
+
+    health_before = float(player.health)
+
+    if perk_active(player, PerkId.HIGHLANDER):
+        if (rng() % 10) == 0:
+            player.health = 0.0
+    else:
+        player.health -= dmg
+        if player.health < 0.0 and dt is not None and float(dt) > 0.0:
+            player.death_timer -= float(dt) * 28.0
+
+    if not perk_active(player, PerkId.UNSTOPPABLE):
+        # player_take_damage @ 0x00425e50: on-hit camera/spread disruption.
+        player.heading += float((rng() % 100) - 50) * 0.04
+        player.spread_heat = min(0.48, float(player.spread_heat) + dmg * 0.01)
+
+    if player.health <= 20.0 and (rng() & 7) == 3:
+        player.low_health_timer = 0.0
+    return max(0.0, health_before - float(player.health))