# 0001 — Custom immediate-mode GUI on ISurface

- Status: Accepted
- Date: 2026-10-27

## Context

The text-only menu is becoming cumbersome as features accumulate. The cheat
already has a proven overlay draw path through `ISurface` (`PaintTraverseEx`),
native text with the bundled Liberation Sans font, text metrics, filled/outlined
rects, lines and textured polygons. The game runs Source on Linux with a
32-bit process; the cheat is a single `LD_PRELOAD` shared object.

The main alternatives were:

1. Dear ImGui with its standard OpenGL renderer, hooked into the game's
   swap/present path.
2. Dear ImGui rendered through `ISurface`.
3. A custom immediate-mode GUI on `ISurface`.
4. Keep the text menu and add categories/pages.

`ISurface::Vertex_t` only carries position and UV, not per-vertex color, so a
standard ImGui draw-list renderer would lose per-widget text colors unless
draws were split or text was rendered through a separate path. An OpenGL ImGui
backend would require locating and hooking the swap path, saving/restoring GL
state, uploading the font atlas, and integrating SDL input events — an
unverified risk in this build. The existing ISurface path already draws in-game
and in menus without a new graphics context.

## Decision

Build a custom immediate-mode GUI directly on the existing `ISurface` draw
path.

- Fixed dark theme with automatic scale:
  `clamp(min(screen_w/1920, screen_h/1080), 0.75, 1.5)`.
- Base window 960x620, body/title fonts 15/20 px at scale 1.
- Left sidebar categories (Movement, Combat, Visuals, Weapons, System) and a
  content pane of feature cards with collapsible settings.
- Native OS cursor by releasing SDL relative-mouse mode while the GUI is open.
- While open, freeze look/attack/use and skip combat features, but allow
  normal movement; bind capture blocks all game input. Keep the game
  simulating and keep ESP/FOV circle/speed graph drawing.
- Replace the text menu with the GUI. No permanent fallback menu; git history
  retains the old implementation.

## Consequences

- We own the widget set (scrollbar, sliders, toggles, keybind capture, tooltips)
  and the layout/clipping code. Text clipping and wheel events need explicit
  handling because ISurface has no clip-rect API and SDL does not expose wheel
  state by polling.
- No new runtime dependency or GL context management.
- The GUI remains inside the engine's VGUI paint path, so it inherits the
  existing font registration and in-game overlay behavior.
- The old text menu is removed once the GUI reaches feature parity. During
  development the GUI is built alongside the text menu; Insert toggles the
  GUI and F1 keeps the old tree accessible. The replacement is complete only
  when the old tree is deleted.