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

[Billytifft]

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 Load labels from labels.txt and use in-game #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: PediaIcons Parser - Be Able to Read in Tech Icons #389 (PediaIcons parser — closed, direct precedent), Tech Selection Picker #390 (tech selection picker — closed), Load labels from labels.txt and use in-game #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.

[WildWeazel]

I will suggest NOT trying to consume the Civ3 pedia content (civilopedia.txt and pediaicons.txt) directly in game, but having a step when loading mods to convert it into our own sensible format (JSON) first. Remember for standalone mode we are compiling our own articles which can be kept in our preferred format. There may be some code available from this or other projects to help with the conversion.

[WildWeazel]

Also, while we generally want to maintain UI graphics compatibility (ie, keep the same layout for the background texture) this is a place where I think we can do better with the UI. For example the whole navigation box on the right seems like a waste of space.

[Billytifft]

i 100% agree. im thinking a searchbar up top above the title and bringing a heirarchy/top level list on the left in small text, then navigation (forward/back) on the top left near the search bar. i think a 1 time file conversion of the civ3 content into our own format would be good and not use their text format. my suggestion would be markdown or rst file types

[Billytifft]

Items to think about:

• GODOT does not natively support markdown. we can work through this.
• Name is "Pedia"
• potential for exporting Pedia as a json
• link to standard pedia on the main menu?

[Billytifft]

Phase 1 (data layer) is being implemented in PR #999 — parsing Text/Civilopedia.txt into structured entries, attaching civilopedia keys to units/buildings/civilizations during import, and loading it beside PediaIcons. UI/prose: the new model is Codex/CodexEntry (markdown bodies, $LINK->Text), kept out of saves and null-safe for scenario-only entries. Phase 1 is ready for review; Phase 2/3 (UI shell, links/deep-linking, search) to follow.

[WildWeazel]

Here's a plugin to use markdown in a RichTextLabel. I think that would be best as it's the simpler and much more widely known format these days, and would allow us to directly edit and copy articles from the wiki.

https://github.com/daenvil/MarkdownLabel