Autobattler — Godot Client

Godot 4.6 front-end for the autobattler project.

---

What it is

• Replay viewer: reads a BattleLog JSON produced by the battle engine and animates it. No game logic in GDScript — all combat resolution happens in the engine.
• Lab (Phase 1, in progress): freely build any team (weapons + runes), launch a battle against an invincible dummy, watch the replay.

---

How to run

Open project.godot in Godot 4.6 and press F5.

---

Phases

Phase	Scope	Status
0	Replay viewer — hardcoded BattleLog, health bars + text, no art	✅ done
1	Lab scene — team builder, catalog browser, launch battle	🔧 in progress
2	Shop — between-battle draft	⬜
3	Map — hex map, travel, pre-battle loadout	⬜
4	Desk — archivist office, embeds other scenes via SubViewport	⬜

---

Architecture

catalog.json / keyword_definitions.json
        │
        ▼
   Catalog (autoload) ──────────────────────────────┐
        │                                            │ engine_json blobs (dev only)
        ▼                                            ▼
   EquipScene                               BattleRunner (autoload)
   ┌────────────────────────────────┐            │ OS.execute() → luajit
   │  TeamPanel   │  CatalogPanel  │            │ (→ server call in production)
   │  (drop tgts) │  (drag sources)│            ▼
   └────────────────────────────────┘       battle_log.json
        │                                            │
        │ get_team_json()                            ▼
        └───────────────────────────────────► BattleViewer

Popup system — all item/keyword popups go through PopupManager (autoload). Two tiers: InspectorPopup (persistent, draggable, multiple) and KeywordTooltip (transient, one at a time, browser-style back/forward navigation). Both live in a CanvasLayer at layer 100 — never clipped.

Clause descriptions from catalog.json are rendered to BBCode by ClauseParser. Each [keyword:x] token becomes a hoverable, clickable link that opens a KeywordTooltip with the definition from keyword_definitions.json.

---

Key design decisions

Decision	Rationale
No game logic in GDScript	Engine is authoritative; client is a viewer
BattleRunner abstracts engine call	Swap OS.execute() → HTTP without touching any UI
Catalog strips engine_json from display data	UI code can never accidentally use engine blobs
PopupManager owns all popup lifecycle	Single place for z-ordering, positioning, hover-bridge
Dev strings as i18n msgids	en.po is the copy-editing layer; no polished text hardcoded in source
ClauseParser separates tokenize / render	Template system for non-SVO languages slots in without changing existing code

---

Folder structure

client/
  scenes/
    equip/          — lab + future campaign prep (shared equip scene, mode="lab"|"campaign")
    battle/         — replay viewer
    shop/           — Phase 2
    map/            — Phase 3
    desk/           — Phase 4
    ui/             — InspectorPopup, KeywordTooltip
    main.tscn
  scripts/
    autoloads/      — Catalog, BattleRunner, PopupManager
    replay/         — BattleLog parser + replay controller
    models/         — display-only data classes (no game logic)
    ui/             — ClauseParser and other stateless utilities
  assets/
    fonts/ icons/ sprites/ sounds/
    locales/        — .po translation files
  data/
    catalog.json             — weapons + rune patterns (engine_json present in dev build only)
    keywords.json            — id roster by category; regen-tool owned, not for display text
    keyword_definitions.json — keyword id → dev-English definition (hand-authored)
    battles/                 — sample BattleLog JSON fixtures
  project.godot
  TODO.md           — implementation spec and build checklist

---

Localization

All display copy lives in .po files — including English. Source code and data files use developer English as msgids (clear intent, not polished copy). en.po provides the polished English strings; fr.po, etc. provide translations.

See CLAUDE.md for the full i18n strategy, tr() rules, and the word-order template system plan for non-SVO languages.