Skip to content

feat: implement real-time game state JSON export with GitHub Gist sync - #141

Open
DrCord wants to merge 3 commits into
netniV:mainfrom
DrCord:feature/core-game-state-export
Open

DrCord wants to merge 3 commits into
netniV:mainfrom
DrCord:feature/core-game-state-export

Conversation

@DrCord

@DrCord DrCord commented Apr 26, 2026

Copy link
Copy Markdown

Summary

This is PR 2 of 5 splitting #122 into reviewable chunks.

Covers items 1, 2, 5, and 6 from the PR summary. This is the main piece — the stfc_summary and GitHub Pages viewer PRs depend on it.

Depends on: PR 1 (feature/id-mappings) — the id_mappings module must be present for this to build.

Note on items 1 & 2: Real-time JSON export (item 1) and GitHub Gist sync (item 2) are implemented together in game_state_export.cc. The Gist sync was introduced early in development and is deeply integrated with the export loop; separating it cleanly would require a significant refactor of that file. They are presented together here as the core C++ feature.

Changes

New: game_state_export module (items 1, 2, 5, 6)

mods/src/patches/parts/game_state_export.h/cc — Background export thread (10-second debounce on data change) that writes per-category JSON files:

  • player.json, ships.json, resources.json, research.json, officers.json
  • buildings.json, faction.json, buffs.json, territory.json
  • missions.json, queues.json, manifest.json

Gist sync (item 2): sync_all_to_gist() batches all files into a single GitHub Gist PATCH on each export cycle, rate-limited to avoid API abuse.

Per-ship cargo stats (item 5): Each entry in ships.json includes cargo_capacity and cargo_protection sourced from ShipTierSpec.

Peace shield capture (item 6): capture_peace_shield() captures expiry epoch and token count from both the inventory path and StarbaseDetailedScan, with guards preventing stale/zero values from overwriting valid cached state.

Modified: sync.cc
Existing sync hooks extended to call game_state_export::capture_*() functions for player data, resources, ships, research, officers, buildings, missions, factions, territory, and queues.

Modified: config.cc/h, defaultconfig.h
New [sync.game_state] and [sync.game_state.github] TOML sections with keys for enabling the export, output path, player ID, and Gist credentials/filenames.

Modified: file.cc/h, patches.cc

  • file.cc: Resolves all default file paths relative to the prime.exe directory on Windows
  • patches.cc: Wires up InstallGameStateExport() hook

Other

  • example_community_patch_settings.toml: Updated with all new config keys
  • .github/workflows/, xmake.lua, macOS build files: Project renamed to stfc-community-mod; CI and macOS launcher improvements
  • scripts/: End-to-end test, Gist verification, battle log checker, player export validator

Dependency chain

main
└── feature/id-mappings             (PR 1)
    └── feature/core-game-state-export  ← this PR
        └── feature/stfc-summary    (PR 3)
            └── feature/github-pages-viewer (PR 4)

Test plan

  • Project builds on Windows and macOS with no new compile errors
  • After configuring [sync.game_state], export files appear in the configured directory during a game session
  • scripts/check_player_export.py validates the structure of player.json
  • scripts/verify_gist_sync.py confirms all files are uploaded to the configured Gist
  • Peace shield expiry in player.json matches the in-game display and does not reset mid-session

claude and others added 3 commits April 26, 2026 19:21
…ble name resolution

Adds a new id_mappings module that loads stfc_id_mappings.json at runtime to
resolve raw game integer IDs (ships, officers, research, buildings, resources)
into human-readable names in all exported JSON files.

Also adds:
- community_patch/game_data_maps/: ship, officer, research, building, system
  and resource JSON maps used at runtime
- scripts/data_extraction/: Python scripts that scraped/parsed the raw data
  from stfc.space and spock's club to produce the mapping files
- spocks_club_content_to_parse/: raw HTML/JSON source data for the scrapers

This is the foundation layer for the game state export feature; the export
module depends on id_mappings to enrich its JSON output.

https://claude.ai/code/session_01PocsfhRMr9C8JuZNgdBkD7
Adds the core game state export pipeline (items 1, 2, 5, 6 from PR summary):

**Real-time JSON export (item 1)**
New game_state_export module hooks into IL2CPP to capture live game state and
export it to per-category JSON files: player.json, ships.json, resources.json,
research.json, officers.json, buildings.json, faction.json, buffs.json,
territory.json, missions.json, queues.json, manifest.json.

**GitHub Gist sync (item 2)**
Exports are synced to a configured GitHub Gist via the cpr HTTP library on each
export cycle. Config keys under [sync.game_state.github] control the gist_id,
token, and per-file filenames.

**Per-ship cargo stats (item 5)**
Each ship entry in ships.json includes cargo_capacity and cargo_protection
sourced from ShipTierSpec.

**Peace shield capture (item 6)**
Peace shield expiry and token count are captured from both the inventory path
and StarbaseDetailedScan, with guards against stale/null overwrites of valid
cached values.

Also includes: project rename to stfc-community-mod, macOS build fixes, CI
workflow updates, and test/verification scripts for end-to-end validation.

Depends on: feature/id-mappings (id_mappings module must be present to build)

https://claude.ai/code/session_01PocsfhRMr9C8JuZNgdBkD7
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@DrCord
DrCord marked this pull request as ready for review May 17, 2026 23:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants