crimsonland 0.1.0.dev1__py3-none-any.whl

crimson/ui/perk_menu.py

@@ -0,0 +1,388 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import pyray as rl
+
+from grim.assets import TextureLoader
+from grim.fonts.small import SmallFontData, draw_small_text, measure_small_text_width
+
+
+UI_BASE_WIDTH = 640.0
+UI_BASE_HEIGHT = 480.0
+
+
+MENU_PANEL_SLICE_Y1 = 130.0
+MENU_PANEL_SLICE_Y2 = 150.0
+
+# Layout offsets from the classic game (perk selection screen), derived from
+# `perk_selection_screen_update` (see analysis/ghidra + BN).
+MENU_PANEL_ANCHOR_X = 224.0
+MENU_PANEL_ANCHOR_Y = 40.0
+MENU_TITLE_X = 54.0
+MENU_TITLE_Y = 6.0
+MENU_TITLE_W = 128.0
+MENU_TITLE_H = 32.0
+MENU_SPONSOR_Y = -8.0
+MENU_SPONSOR_X_EXPERT = -26.0
+MENU_SPONSOR_X_MASTER = -28.0
+MENU_LIST_Y_NORMAL = 50.0
+MENU_LIST_Y_EXPERT = 40.0
+MENU_LIST_STEP_NORMAL = 19.0
+MENU_LIST_STEP_EXPERT = 18.0
+MENU_DESC_X = -12.0
+MENU_DESC_Y_AFTER_LIST = 32.0
+MENU_DESC_Y_EXTRA_TIGHTEN = 20.0
+MENU_BUTTON_X = 162.0
+MENU_BUTTON_Y = 276.0
+MENU_DESC_RIGHT_X = 480.0
+
+
+@dataclass(slots=True)
+class PerkMenuLayout:
+    # Coordinates live in the original 640x480 UI space.
+    # Matches the classic menu panel: pos (-45, 110) + offset (20, -82).
+    panel_x: float = -25.0
+    panel_y: float = 28.0
+    panel_w: float = 512.0
+    panel_h: float = 379.0
+
+
+@dataclass(slots=True)
+class PerkMenuComputedLayout:
+    panel: rl.Rectangle
+    title: rl.Rectangle
+    sponsor_x: float
+    sponsor_y: float
+    list_x: float
+    list_y: float
+    list_step_y: float
+    desc: rl.Rectangle
+    cancel_x: float
+    cancel_y: float
+
+
+def ui_scale(screen_w: float, screen_h: float) -> float:
+    # Classic UI renders in backbuffer pixels; keep menu scale fixed.
+    return 1.0
+
+
+def ui_origin(screen_w: float, screen_h: float, scale: float) -> tuple[float, float]:
+    return 0.0, 0.0
+
+
+def _menu_widescreen_y_shift(layout_w: float) -> float:
+    # ui_menu_layout_init: pos_y += (screen_width / 640.0) * 150.0 - 150.0
+    return (layout_w / UI_BASE_WIDTH) * 150.0 - 150.0
+
+
+def perk_menu_compute_layout(
+    layout: PerkMenuLayout,
+    *,
+    screen_w: float,
+    origin_x: float,
+    origin_y: float,
+    scale: float,
+    choice_count: int,
+    expert_owned: bool,
+    master_owned: bool,
+    panel_slide_x: float = 0.0,
+) -> PerkMenuComputedLayout:
+    layout_w = screen_w / scale if scale else screen_w
+    widescreen_shift_y = _menu_widescreen_y_shift(layout_w)
+    panel_x = layout.panel_x + panel_slide_x
+    panel_y = layout.panel_y + widescreen_shift_y
+    panel = rl.Rectangle(
+        origin_x + panel_x * scale,
+        origin_y + panel_y * scale,
+        layout.panel_w * scale,
+        layout.panel_h * scale,
+    )
+    anchor_x = panel.x + MENU_PANEL_ANCHOR_X * scale
+    anchor_y = panel.y + MENU_PANEL_ANCHOR_Y * scale
+
+    title = rl.Rectangle(
+        anchor_x + MENU_TITLE_X * scale,
+        anchor_y + MENU_TITLE_Y * scale,
+        MENU_TITLE_W * scale,
+        MENU_TITLE_H * scale,
+    )
+
+    sponsor_x = anchor_x + (MENU_SPONSOR_X_MASTER if master_owned else MENU_SPONSOR_X_EXPERT) * scale
+    sponsor_y = anchor_y + MENU_SPONSOR_Y * scale
+
+    list_step_y = MENU_LIST_STEP_EXPERT if expert_owned else MENU_LIST_STEP_NORMAL
+    list_x = anchor_x
+    list_y = anchor_y + (MENU_LIST_Y_EXPERT if expert_owned else MENU_LIST_Y_NORMAL) * scale
+
+    desc_x = anchor_x + MENU_DESC_X * scale
+    desc_y = list_y + float(choice_count) * list_step_y * scale + MENU_DESC_Y_AFTER_LIST * scale
+    if choice_count > 5:
+        desc_y -= MENU_DESC_Y_EXTRA_TIGHTEN * scale
+
+    # Keep the description within the monitor screen area and above the button.
+    desc_right = panel.x + MENU_DESC_RIGHT_X * scale
+    cancel_x = anchor_x + MENU_BUTTON_X * scale
+    cancel_y = anchor_y + MENU_BUTTON_Y * scale
+    desc_w = max(0.0, float(desc_right - desc_x))
+    desc_h = max(0.0, float(cancel_y - 12.0 * scale - desc_y))
+    desc = rl.Rectangle(float(desc_x), float(desc_y), float(desc_w), float(desc_h))
+
+    return PerkMenuComputedLayout(
+        panel=panel,
+        title=title,
+        sponsor_x=float(sponsor_x),
+        sponsor_y=float(sponsor_y),
+        list_x=float(list_x),
+        list_y=float(list_y),
+        list_step_y=float(list_step_y * scale),
+        desc=desc,
+        cancel_x=float(cancel_x),
+        cancel_y=float(cancel_y),
+    )
+
+
+def draw_menu_panel(texture: rl.Texture, *, dst: rl.Rectangle, tint: rl.Color = rl.WHITE) -> None:
+    scale = float(dst.width) / float(texture.width)
+    top_h = MENU_PANEL_SLICE_Y1 * scale
+    bottom_h = (float(texture.height) - MENU_PANEL_SLICE_Y2) * scale
+    mid_h = float(dst.height) - top_h - bottom_h
+    if mid_h < 0.0:
+        src = rl.Rectangle(0.0, 0.0, float(texture.width), float(texture.height))
+        rl.draw_texture_pro(texture, src, dst, rl.Vector2(0.0, 0.0), 0.0, tint)
+        return
+
+    src_w = float(texture.width)
+    src_h = float(texture.height)
+
+    src_top = rl.Rectangle(0.0, 0.0, src_w, MENU_PANEL_SLICE_Y1)
+    src_mid = rl.Rectangle(0.0, MENU_PANEL_SLICE_Y1, src_w, MENU_PANEL_SLICE_Y2 - MENU_PANEL_SLICE_Y1)
+    src_bot = rl.Rectangle(0.0, MENU_PANEL_SLICE_Y2, src_w, src_h - MENU_PANEL_SLICE_Y2)
+
+    dst_top = rl.Rectangle(float(dst.x), float(dst.y), float(dst.width), top_h)
+    dst_mid = rl.Rectangle(float(dst.x), float(dst.y) + top_h, float(dst.width), mid_h)
+    dst_bot = rl.Rectangle(float(dst.x), float(dst.y) + top_h + mid_h, float(dst.width), bottom_h)
+
+    origin = rl.Vector2(0.0, 0.0)
+    rl.draw_texture_pro(texture, src_top, dst_top, origin, 0.0, tint)
+    rl.draw_texture_pro(texture, src_mid, dst_mid, origin, 0.0, tint)
+    rl.draw_texture_pro(texture, src_bot, dst_bot, origin, 0.0, tint)
+
+
+@dataclass(slots=True)
+class PerkMenuAssets:
+    menu_panel: rl.Texture | None
+    title_pick_perk: rl.Texture | None
+    title_level_up: rl.Texture | None
+    menu_item: rl.Texture | None
+    button_sm: rl.Texture | None
+    button_md: rl.Texture | None
+    cursor: rl.Texture | None
+    aim: rl.Texture | None
+    missing: list[str] = field(default_factory=list)
+
+
+def load_perk_menu_assets(assets_root: Path) -> PerkMenuAssets:
+    loader = TextureLoader.from_assets_root(assets_root)
+    return PerkMenuAssets(
+        menu_panel=loader.get(name="ui_menuPanel", paq_rel="ui/ui_menuPanel.jaz", fs_rel="ui/ui_menuPanel.png"),
+        title_pick_perk=loader.get(
+            name="ui_textPickAPerk",
+            paq_rel="ui/ui_textPickAPerk.jaz",
+            fs_rel="ui/ui_textPickAPerk.png",
+        ),
+        title_level_up=loader.get(
+            name="ui_textLevelUp",
+            paq_rel="ui/ui_textLevelUp.jaz",
+            fs_rel="ui/ui_textLevelUp.png",
+        ),
+        menu_item=loader.get(name="ui_menuItem", paq_rel="ui/ui_menuItem.jaz", fs_rel="ui/ui_menuItem.png"),
+        button_sm=loader.get(name="ui_buttonSm", paq_rel="ui/ui_button_82x32.jaz", fs_rel="ui/ui_button_82x32.png"),
+        button_md=loader.get(
+            name="ui_buttonMd",
+            paq_rel="ui/ui_button_145x32.jaz",
+            fs_rel="ui/ui_button_145x32.png",
+        ),
+        cursor=loader.get(name="ui_cursor", paq_rel="ui/ui_cursor.jaz", fs_rel="ui/ui_cursor.png"),
+        aim=loader.get(name="ui_aim", paq_rel="ui/ui_aim.jaz", fs_rel="ui/ui_aim.png"),
+        missing=loader.missing,
+    )
+
+
+def _ui_text_width(font: SmallFontData | None, text: str, scale: float) -> float:
+    if font is None:
+        return float(rl.measure_text(text, int(20 * scale)))
+    return float(measure_small_text_width(font, text, scale))
+
+
+def draw_ui_text(
+    font: SmallFontData | None,
+    text: str,
+    x: float,
+    y: float,
+    *,
+    scale: float,
+    color: rl.Color,
+) -> None:
+    if font is not None:
+        draw_small_text(font, text, x, y, scale, color)
+    else:
+        rl.draw_text(text, int(x), int(y), int(20 * scale), color)
+
+
+def wrap_ui_text(font: SmallFontData | None, text: str, *, max_width: float, scale: float) -> list[str]:
+    lines: list[str] = []
+    for raw in text.splitlines() or [""]:
+        para = raw.strip()
+        if not para:
+            lines.append("")
+            continue
+        current = ""
+        for word in para.split():
+            candidate = word if not current else f"{current} {word}"
+            if current and _ui_text_width(font, candidate, scale) > max_width:
+                lines.append(current)
+                current = word
+            else:
+                current = candidate
+        if current:
+            lines.append(current)
+    return lines
+
+
+MENU_ITEM_RGB = (0x46, 0xB4, 0xF0)  # from ui_menu_item_update: rgb(70, 180, 240)
+MENU_ITEM_ALPHA_IDLE = 0.6
+MENU_ITEM_ALPHA_HOVER = 1.0
+
+
+def menu_item_hit_rect(font: SmallFontData | None, label: str, *, x: float, y: float, scale: float) -> rl.Rectangle:
+    width = _ui_text_width(font, label, scale)
+    height = 16.0 * scale
+    return rl.Rectangle(float(x), float(y), float(width), float(height))
+
+
+def draw_menu_item(
+    font: SmallFontData | None,
+    label: str,
+    *,
+    x: float,
+    y: float,
+    scale: float,
+    hovered: bool,
+) -> float:
+    alpha = MENU_ITEM_ALPHA_HOVER if hovered else MENU_ITEM_ALPHA_IDLE
+    r, g, b = MENU_ITEM_RGB
+    color = rl.Color(int(r), int(g), int(b), int(255 * alpha))
+    draw_ui_text(font, label, x, y, scale=scale, color=color)
+    width = _ui_text_width(font, label, scale)
+    line_y = y + 13.0 * scale
+    rl.draw_line(int(x), int(line_y), int(x + width), int(line_y), color)
+    return float(width)
+
+
+@dataclass(slots=True)
+class UiButtonState:
+    label: str
+    enabled: bool = True
+    hovered: bool = False
+    activated: bool = False
+    hover_t: int = 0  # 0..1000
+    press_t: int = 0  # 0..1000
+    alpha: float = 1.0
+    force_wide: bool = False
+
+
+def button_width(font: SmallFontData | None, label: str, *, scale: float, force_wide: bool) -> float:
+    text_w = _ui_text_width(font, label, scale)
+    if force_wide:
+        return 145.0 * scale
+    if text_w < 40.0 * scale:
+        return 82.0 * scale
+    return 145.0 * scale
+
+
+def button_hit_rect(*, x: float, y: float, width: float) -> rl.Rectangle:
+    # Mirrors ui_button_update: y is offset by +2, hit height is 0x1c (28).
+    return rl.Rectangle(float(x), float(y + 2.0), float(width), float(28.0))
+
+
+def button_update(
+    state: UiButtonState,
+    *,
+    x: float,
+    y: float,
+    width: float,
+    dt_ms: float,
+    mouse: rl.Vector2,
+    click: bool,
+) -> bool:
+    if not state.enabled:
+        state.hovered = False
+    else:
+        state.hovered = rl.check_collision_point_rec(mouse, button_hit_rect(x=x, y=y, width=width))
+
+    delta = 6 if (state.enabled and state.hovered) else -4
+    state.hover_t = int(_clamp(float(state.hover_t + int(dt_ms) * delta), 0.0, 1000.0))
+
+    if state.press_t > 0:
+        state.press_t = int(_clamp(float(state.press_t - int(dt_ms) * 6), 0.0, 1000.0))
+
+    state.activated = bool(state.enabled and state.hovered and click)
+    if state.activated:
+        state.press_t = 1000
+    return state.activated
+
+
+def _clamp(value: float, lo: float, hi: float) -> float:
+    if value < lo:
+        return lo
+    if value > hi:
+        return hi
+    return value
+
+
+def button_draw(
+    assets: PerkMenuAssets,
+    font: SmallFontData | None,
+    state: UiButtonState,
+    *,
+    x: float,
+    y: float,
+    width: float,
+    scale: float,
+) -> None:
+    texture = assets.button_md if width > 120.0 * scale else assets.button_sm
+    if texture is None:
+        return
+
+    if state.hover_t > 0:
+        alpha = 0.5
+        if state.press_t > 0:
+            alpha = min(1.0, 0.5 + (float(state.press_t) * 0.0005))
+        hl = rl.Color(255, 255, 255, int(255 * alpha * 0.25 * state.alpha))
+        rl.draw_rectangle(int(x + 12.0 * scale), int(y + 5.0 * scale), int(width - 24.0 * scale), int(22.0 * scale), hl)
+
+    tint_a = state.alpha if state.hovered else state.alpha * 0.7
+    tint = rl.Color(255, 255, 255, int(255 * _clamp(tint_a, 0.0, 1.0)))
+
+    src = rl.Rectangle(0.0, 0.0, float(texture.width), float(texture.height))
+    dst = rl.Rectangle(float(x), float(y), float(width), float(32.0 * scale))
+    rl.draw_texture_pro(texture, src, dst, rl.Vector2(0.0, 0.0), 0.0, tint)
+
+    text_w = _ui_text_width(font, state.label, scale)
+    text_x = x + width * 0.5 - text_w * 0.5 + 1.0 * scale
+    text_y = y + 10.0 * scale
+    draw_ui_text(font, state.label, text_x, text_y, scale=scale, color=tint)
+
+
+def cursor_draw(assets: PerkMenuAssets, *, mouse: rl.Vector2, scale: float, alpha: float = 1.0) -> None:
+    tex = assets.cursor
+    if tex is None:
+        return
+    a = int(255 * _clamp(alpha, 0.0, 1.0))
+    tint = rl.Color(255, 255, 255, a)
+    size = 32.0 * scale
+    src = rl.Rectangle(0.0, 0.0, float(tex.width), float(tex.height))
+    dst = rl.Rectangle(float(mouse.x), float(mouse.y), size, size)
+    rl.draw_texture_pro(tex, src, dst, rl.Vector2(0.0, 0.0), 0.0, tint)

crimson/views/__init__.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from .registry import all_views, view_by_name
+
+
+def _register_builtin_views() -> None:
+    from . import empty as _empty  # noqa: F401
+    from . import fonts as _fonts  # noqa: F401
+    from . import animations as _animations  # noqa: F401
+    from . import sprites as _sprites  # noqa: F401
+    from . import terrain as _terrain  # noqa: F401
+    from . import ground as _ground  # noqa: F401
+    from . import projectiles as _projectiles  # noqa: F401
+    from . import projectile_fx as _projectile_fx  # noqa: F401
+    from . import bonuses as _bonuses  # noqa: F401
+    from . import perks as _perks  # noqa: F401
+    from . import perk_menu_debug as _perk_menu_debug  # noqa: F401
+    from . import wicons as _wicons  # noqa: F401
+    from . import ui as _ui  # noqa: F401
+    from . import particles as _particles  # noqa: F401
+    from . import spawn_plan as _spawn_plan  # noqa: F401
+    from . import player as _player  # noqa: F401
+    from . import survival as _survival  # noqa: F401
+    from . import rush as _rush  # noqa: F401
+    from . import game_over as _game_over  # noqa: F401
+    from . import small_font_debug as _small_font_debug  # noqa: F401
+    from . import camera_debug as _camera_debug  # noqa: F401
+    from . import camera_shake as _camera_shake  # noqa: F401
+    from . import decals_debug as _decals_debug  # noqa: F401
+    from . import corpse_stamp_debug as _corpse_stamp_debug  # noqa: F401
+    from . import player_sprite_debug as _player_sprite_debug  # noqa: F401
+    from . import aim_debug as _aim_debug  # noqa: F401
+    from . import projectile_render_debug as _projectile_render_debug  # noqa: F401
+    from . import arsenal_debug as _arsenal_debug  # noqa: F401
+    from . import lighting_debug as _lighting_debug  # noqa: F401
+
+
+_register_builtin_views()
+
+__all__ = ["all_views", "view_by_name"]

crimson/views/aim_debug.py

@@ -0,0 +1,276 @@
+from __future__ import annotations
+
+import math
+
+import pyray as rl
+
+from grim.config import ensure_crimson_cfg
+from grim.fonts.small import SmallFontData, draw_small_text, load_small_font
+from grim.view import ViewContext
+
+from ..game_world import GameWorld
+from ..gameplay import PlayerInput
+from ..paths import default_runtime_dir
+from ..ui.cursor import draw_cursor_glow
+from .registry import register_view
+
+WORLD_SIZE = 1024.0
+
+UI_TEXT_SCALE = 1.0
+UI_TEXT_COLOR = rl.Color(220, 220, 220, 255)
+UI_HINT_COLOR = rl.Color(140, 140, 140, 255)
+UI_ERROR_COLOR = rl.Color(240, 80, 80, 255)
+
+
+def _clamp(value: float, lo: float, hi: float) -> float:
+    if value < lo:
+        return lo
+    if value > hi:
+        return hi
+    return value
+
+
+class AimDebugView:
+    def __init__(self, ctx: ViewContext) -> None:
+        self._assets_root = ctx.assets_dir
+        self._missing_assets: list[str] = []
+        self._small: SmallFontData | None = None
+        self._world = GameWorld(
+            assets_dir=ctx.assets_dir,
+            world_size=WORLD_SIZE,
+            demo_mode_active=False,
+            difficulty_level=0,
+            hardcore=False,
+        )
+        self._player = self._world.players[0] if self._world.players else None
+
+        self.close_requested = False
+
+        self._ui_mouse_x = 0.0
+        self._ui_mouse_y = 0.0
+        self._cursor_pulse_time = 0.0
+
+        self._simulate = False
+        self._draw_world = True
+        self._draw_world_aim = True
+        self._show_cursor_glow = False
+        self._draw_expected_overlay = True
+        self._draw_test_circle = True
+
+        self._force_heat = True
+        self._forced_heat = 0.18
+        self._test_circle_radius = 96.0
+
+    def _ui_line_height(self, scale: float = UI_TEXT_SCALE) -> int:
+        if self._small is not None:
+            return int(self._small.cell_size * scale)
+        return int(20 * scale)
+
+    def _draw_ui_text(
+        self,
+        text: str,
+        x: float,
+        y: float,
+        color: rl.Color,
+        scale: float = UI_TEXT_SCALE,
+    ) -> None:
+        if self._small is not None:
+            draw_small_text(self._small, text, x, y, scale, color)
+        else:
+            rl.draw_text(text, int(x), int(y), int(20 * scale), color)
+
+    def _update_ui_mouse(self) -> None:
+        mouse = rl.get_mouse_position()
+        screen_w = float(rl.get_screen_width())
+        screen_h = float(rl.get_screen_height())
+        self._ui_mouse_x = _clamp(float(mouse.x), 0.0, max(0.0, screen_w - 1.0))
+        self._ui_mouse_y = _clamp(float(mouse.y), 0.0, max(0.0, screen_h - 1.0))
+
+    def _draw_cursor_glow(self, *, x: float, y: float) -> None:
+        draw_cursor_glow(self._world.particles_texture, x=x, y=y)
+
+    def _handle_debug_input(self) -> None:
+        if rl.is_key_pressed(rl.KeyboardKey.KEY_ESCAPE):
+            self.close_requested = True
+
+        if rl.is_key_pressed(rl.KeyboardKey.KEY_SPACE):
+            self._simulate = not self._simulate
+
+        if rl.is_key_pressed(rl.KeyboardKey.KEY_ONE):
+            self._draw_world = not self._draw_world
+        if rl.is_key_pressed(rl.KeyboardKey.KEY_TWO):
+            self._draw_world_aim = not self._draw_world_aim
+        if rl.is_key_pressed(rl.KeyboardKey.KEY_THREE):
+            self._draw_expected_overlay = not self._draw_expected_overlay
+        if rl.is_key_pressed(rl.KeyboardKey.KEY_FOUR):
+            self._show_cursor_glow = not self._show_cursor_glow
+        if rl.is_key_pressed(rl.KeyboardKey.KEY_FIVE):
+            self._draw_test_circle = not self._draw_test_circle
+
+        if rl.is_key_pressed(rl.KeyboardKey.KEY_H):
+            self._force_heat = not self._force_heat
+
+        if rl.is_key_pressed(rl.KeyboardKey.KEY_LEFT_BRACKET):
+            self._forced_heat = max(0.0, self._forced_heat - 0.02)
+        if rl.is_key_pressed(rl.KeyboardKey.KEY_RIGHT_BRACKET):
+            self._forced_heat = min(0.48, self._forced_heat + 0.02)
+
+        if rl.is_key_pressed(rl.KeyboardKey.KEY_MINUS):
+            self._test_circle_radius = max(8.0, self._test_circle_radius - 8.0)
+        if rl.is_key_pressed(rl.KeyboardKey.KEY_EQUAL):
+            self._test_circle_radius = min(512.0, self._test_circle_radius + 8.0)
+
+        if rl.is_key_pressed(rl.KeyboardKey.KEY_R):
+            self._world.reset(seed=0xBEEF, player_count=1)
+            self._player = self._world.players[0] if self._world.players else None
+            self._world.update_camera(0.0)
+
+    def open(self) -> None:
+        self._missing_assets.clear()
+        try:
+            self._small = load_small_font(self._assets_root, self._missing_assets)
+        except Exception:
+            self._small = None
+
+        runtime_dir = default_runtime_dir()
+        if runtime_dir.is_dir():
+            try:
+                self._world.config = ensure_crimson_cfg(runtime_dir)
+            except Exception:
+                self._world.config = None
+        else:
+            self._world.config = None
+
+        self._world.reset(seed=0xBEEF, player_count=1)
+        self._player = self._world.players[0] if self._world.players else None
+        self._world.open()
+        self._world.update_camera(0.0)
+        self._ui_mouse_x = float(rl.get_screen_width()) * 0.5
+        self._ui_mouse_y = float(rl.get_screen_height()) * 0.5
+        self._cursor_pulse_time = 0.0
+
+    def close(self) -> None:
+        if self._small is not None:
+            rl.unload_texture(self._small.texture)
+            self._small = None
+        self._world.close()
+
+    def update(self, dt: float) -> None:
+        dt_frame = float(dt)
+        self._update_ui_mouse()
+        self._handle_debug_input()
+        self._cursor_pulse_time += dt_frame * 1.1
+
+        aim_x, aim_y = self._world.screen_to_world(self._ui_mouse_x, self._ui_mouse_y)
+        if self._player is not None:
+            self._player.aim_x = float(aim_x)
+            self._player.aim_y = float(aim_y)
+            if self._force_heat:
+                self._player.spread_heat = float(self._forced_heat)
+
+        move_x = 0.0
+        move_y = 0.0
+        if rl.is_key_down(rl.KeyboardKey.KEY_A):
+            move_x -= 1.0
+        if rl.is_key_down(rl.KeyboardKey.KEY_D):
+            move_x += 1.0
+        if rl.is_key_down(rl.KeyboardKey.KEY_W):
+            move_y -= 1.0
+        if rl.is_key_down(rl.KeyboardKey.KEY_S):
+            move_y += 1.0
+
+        dt_world = dt_frame if self._simulate else 0.0
+        self._world.update(
+            dt_world,
+            inputs=[
+                PlayerInput(
+                    move_x=move_x,
+                    move_y=move_y,
+                    aim_x=float(aim_x),
+                    aim_y=float(aim_y),
+                    fire_down=False,
+                    fire_pressed=False,
+                    reload_pressed=False,
+                )
+            ],
+            auto_pick_perks=False,
+            perk_progression_enabled=False,
+        )
+
+        if self._player is not None and self._force_heat:
+            self._player.spread_heat = float(self._forced_heat)
+
+    def draw(self) -> None:
+        if self._draw_world:
+            self._world.draw(draw_aim_indicators=self._draw_world_aim)
+        else:
+            rl.clear_background(rl.Color(10, 10, 12, 255))
+
+        mouse_x = float(self._ui_mouse_x)
+        mouse_y = float(self._ui_mouse_y)
+
+        if self._draw_test_circle:
+            cx = float(rl.get_screen_width()) * 0.5
+            cy = float(rl.get_screen_height()) * 0.5
+            self._world._draw_aim_circle(x=cx, y=cy, radius=float(self._test_circle_radius))
+            rl.draw_circle_lines(int(cx), int(cy), int(max(1.0, self._test_circle_radius)), rl.Color(255, 80, 80, 220))
+
+        if self._show_cursor_glow:
+            self._draw_cursor_glow(x=mouse_x, y=mouse_y)
+
+        mouse_world_x, mouse_world_y = self._world.screen_to_world(mouse_x, mouse_y)
+        mouse_back_x, mouse_back_y = self._world.world_to_screen(float(mouse_world_x), float(mouse_world_y))
+
+        if self._draw_expected_overlay and self._player is not None:
+            dist = math.hypot(float(self._player.aim_x) - float(self._player.pos_x), float(self._player.aim_y) - float(self._player.pos_y))
+            radius = max(6.0, dist * float(self._player.spread_heat) * 0.5)
+            cam_x, cam_y, scale_x, scale_y = self._world._world_params()
+            scale = (scale_x + scale_y) * 0.5
+            screen_radius = max(1.0, radius * scale)
+            aim_screen_x, aim_screen_y = self._world.world_to_screen(float(self._player.aim_x), float(self._player.aim_y))
+
+            rl.draw_circle_lines(
+                int(aim_screen_x),
+                int(aim_screen_y),
+                int(max(1.0, screen_radius)),
+                rl.Color(80, 220, 120, 240),
+            )
+            rl.draw_line(
+                int(mouse_x),
+                int(mouse_y),
+                int(aim_screen_x),
+                int(aim_screen_y),
+                rl.Color(80, 220, 120, 200),
+            )
+
+            lines = [
+                "Aim debug view",
+                "SPACE simulate world update",
+                "1 world  2 aim-indicators  3 expected overlay  4 cursor glow  5 test circle",
+                f"H force_heat={self._force_heat}  forced_heat={self._forced_heat:.2f}  [ ] adjust",
+                f"test_circle_radius={self._test_circle_radius:.0f}  -/+ adjust",
+                (
+                    f"mouse=({mouse_x:.1f},{mouse_y:.1f}) -> "
+                    f"world=({mouse_world_x:.1f},{mouse_world_y:.1f}) -> "
+                    f"screen=({mouse_back_x:.1f},{mouse_back_y:.1f})"
+                ),
+                f"player_aim_world=({float(self._player.aim_x):.1f},{float(self._player.aim_y):.1f})  "
+                f"player_aim_screen=({aim_screen_x:.1f},{aim_screen_y:.1f})",
+                f"player=({float(self._player.pos_x):.1f},{float(self._player.pos_y):.1f})  dist={dist:.1f}",
+                f"spread_heat={float(self._player.spread_heat):.3f}  r_world={radius:.2f}  r_screen={screen_radius:.2f}",
+                f"cam=({cam_x:.2f},{cam_y:.2f})  scale=({scale_x:.3f},{scale_y:.3f})  demo_mode={self._world.demo_mode_active}",
+                f"bulletTrail={'yes' if self._world.bullet_trail_texture is not None else 'no'}  "
+                f"particles={'yes' if self._world.particles_texture is not None else 'no'}",
+            ]
+            x0 = 16.0
+            y0 = 16.0
+            lh = float(self._ui_line_height())
+            for idx, line in enumerate(lines):
+                self._draw_ui_text(line, x0, y0 + lh * float(idx), UI_TEXT_COLOR if idx < 6 else UI_HINT_COLOR)
+        elif self._draw_expected_overlay and self._player is None:
+            self._draw_ui_text("Aim debug view: missing player", 16.0, 16.0, UI_ERROR_COLOR)
+
+
+@register_view("aim-debug", "Aim indicator debug")
+def _create_aim_debug_view(*, ctx: ViewContext) -> AimDebugView:
+    return AimDebugView(ctx)