Civilopedia — proposal and discussion (data, UI, and navigation)

Start with CivilopediaButton.cs, the PediaIcons.cs parser, and the existing PopupOverlay and advisor patterns; read the discussion before choosing an approach. This issue proposes a multi-phase feature and explicitly leaves data ownership, scope, and UI approach open, so it is not implementation-ready. Done means the proposal is agreed and split into implementation-ready issues; no specific files or tests for that work are named.

Summary

Implement the Civilopedia: the in-game reference for rules, units, buildings, wonders, technologies, civilizations, governments, terrain, resources, and game concepts. Open it from the existing CivilopediaButton in the top-left toolbar (C7/UIElements/UpperLeftNav/CivilopediaButton.cs, currently a no-op that only loads its texture).
This issue is a proposal for discussion. If we reach consensus on the approach, we'll break the work out into separate, implementation-ready issues per phase. The goal is feature parity with Civ3's Civilopedia, not pixel parity — the window's layout and visual design are ours to decide.

How the Civilopedia works in Civ3

• Opened via the book icon next to the advisors, or by clicking hyperlinked content in the game (tech research, build queue, and other screens that show pedia icons).
• It's a popup window that overlays the map (map stays visible around the edges), like the advisor windows — not a full-screen takeover.
• Left column: search field + scrollable index list for the active section. Right pane: article with name, large pedia icon, stat block (where applicable), and prose text.
• Sections (Conquests): Units, City Improvements, Wonders, Technologies, Civilizations, Governments, Terrain, Resources, Terrain Improvements, and "The Library" (game concepts).
• Entries can have multiple pages (e.g. a unit's gameplay text page plus a history page) via a pager; concept entries have a short lines plus a fuller DESC_ page.
• Text hyperlinks ($LINK<Text=Key>) jump between entries.
• Vanilla has a crash bug in the alphabetical-index view; we won't reproduce it.

Where the data comes from

1. Stats — from game data (legacy BIQ import or native ruleset.json). Already present in the engine.
2. Text/PediaIcons.txt — entry → art mapping (#ICON_ + large/small icon paths). Parsing already exists in C7Engine/C7GameData/PediaIcons.cs (unit PediaArt, building iconRowIndex, tech small icons, race art).
3. Text/Civilopedia.txt — the prose. Not parsed yet. Verified real-file format:

• #KEY header → display name → body lines prefixed with ^; entries separated by ||.
• Keys: PRTO_ (units), BLDG_ (buildings and wonders), TECH_, RACE_ (civilizations), GOVT_, TERR_, GOOD_ (resources), TFRM_ (terrain improvements), GCON_ (game concepts); #GAME_CONCEPTS_KEYS lists which concepts exist.
• #DESC_ headers provide additional pages.
• Hyperlinks inline as $LINK<Text=Key>.
• File is Windows-1252 text; some keys have trailing spaces (GCON_Enslavement ).

4. Text/labels.txt — generic UI labels (not pedia index names); tracked separately by #342.

Current state in OpenCiv3

• CivilopediaButton exists but does nothing; natural hook point.
• Full-screen/overlay precedent: advisors shown via C7Action.ShowSpecificAdvisor; lighter overlays via PopupOverlay.ShowPopup(child, category) (GameMenu uses this). A map-overlaying popup matches our existing conventions.
• Legacy file resolution pattern to mirror: Game.cs CreateGameParams GetPediaIconsPath → Util.Civ3MediaPath("Text/PediaIcons.txt"), honoring the BIQ's ScenarioSearchFolders (i.e. mod-provided civilopedia.txt overrides the base).
• CivilopediaEntry keys already exist on Tech, Resource, Government, Terraform, CitizenType; not on UnitPrototype, Building, Civilization — those need the key added (it exists in the QueryCiv3 BIQ sections and is already read during import, e.g. PRTO.CivilopediaEntry).
• Native mode: ruleset.json carries all stats but no prose; standalone ships without Civ3 text files.
• Related issues: #389 (PediaIcons parser — closed, direct precedent), #390 (tech selection picker — closed), #342 (labels.txt, milestone [D/E/F] Legacy game text + I18N).

Proposed phases (to be broken out after discussion)

1. Phase 1 — Data layer: Parse Text/Civilopedia.txt in legacy mode into structured entries (Dictionary<string, CivilopediaEntry> with pages/paragraphs/link segments), load it beside PediaIcons during import, and attach civilopedia keys to all game objects. UI-independent.
2. Phase 2 — UI shell: Wire CivilopediaButton to open a map-overlaying popup window; section tabs, scrollable index list, article pane (large icon + stat block + prose), multi-page pager. All sections, no search yet. Our own design.
3. Phase 3 — Navigation & integration: Render $LINK hyperlinks, deep-link from existing screens (tech selection, build queue, popups), and search-as-you-type.
   Open questions for discussion
4. Text format: parse legacy Text/Civilopedia.txt as-is (mod-compatible, matches our legacy-mode direction), vs. storing prose in a native format in ruleset.json at some point. My lean: start with legacy parsing (Phase 1), revisit native format if/when standalone content is authored.
5. Where the entry dictionary lives (on GameData/SaveGame) and whether it's part of saves.
6. Which sections make the cut for the first implementation vs. deferred (e.g. terrain improvements, eras/landmarks).
7. UI approach: separate PopupOverlay-style window vs. a new C7Action/"game view" overlay like advisors; window sizing/persistence.
8. Deep-linking scope: which screens should open entries (tech selection first?).
9. Standalone mode: placeholder-free graceful degradation, and whether to add authored pedia text there later.

Acceptance criteria(epic-level)

• CivilopediaButton opens and closes the Civilopedia popup during gameplay (legacy mode, real Civ3 install) without hiding the map.
• All intended Civ3 sections are browsable; entries render name + icon + stat block (where applicable) + prose from Text/Civilopedia.txt.
• Multi-page entries (including DESC_ pages) are navigable.
• Mod-provided Text/Civilopedia.txt overrides the base one via the scenario search path.
• Standalone mode runs fine with no text content present.
• Search, hyperlinks, and deep-linking work as described in Phase 3.