Skip to content

Architecture and source map

Source reference: version 0.5.0, commit 05eec6f. This is not a statement of the version currently on Google Play.

Documentation · Development · Testing

invade.io is a Godot 4.7.2 GDScript project using the GL Compatibility renderer. Scenes provide the game entry points; scripts build most interface controls and implement gameplay. There is no game server, account system, or online authority.

PathResponsibility
project.godotMain scene, autoloads, rendering, display settings, translations, and source version
scenes/Menu, battle, HUD, base scene, and executable test scenes
scripts/autoload/Shared state, signals, audio, achievements, telemetry, and toasts
scripts/battle/Battle orchestration, base/troop behavior, AI, territory rendering, and tutorial
scripts/data/Content catalogs, geographic generation, rules, rewards, ranks, and localization helpers
scripts/ui/Menu pages, battle HUD, settings, shared theme, and icons
assets/ and locale/Checked-in geography, fonts, brand/legal assets, and translations
addons/ and ios/plugins/Vendored telemetry SDKs and the native iOS backup picker
tools/ and scripts/Authoring, validation, platform build, and artifact-verification tools
website/Static player website and generated documentation; isolated from Godot with .gdignore and export exclusions
.github/workflows/CI, isolated signing, releases, and website/Pages deployment
MainMenuUI / menu page GameManager: level selection BattleController LevelDatabase / LevelGenerator / CampaignRules GeoDatabase / geo.json BaseNode / Troop / AIController EventBus signals BattleHUD / menu feedback Achievements / progression GameManager: local save Telemetry, when allowed
Generated from the diagram in the source guide.
Diagram source
flowchart TD
    Menu[MainMenuUI / menu page] --> Selection[GameManager: level selection]
    Selection --> Battle[BattleController]
    Levels[LevelDatabase / LevelGenerator / CampaignRules] --> Battle
    Geography[GeoDatabase / geo.json] --> Levels
    Battle --> Units[BaseNode / Troop / AIController]
    Units --> Signals[EventBus signals]
    Battle --> Signals
    Signals --> UI[BattleHUD / menu feedback]
    Signals --> Progress[Achievements / progression]
    Progress --> State[GameManager: local save]
    Signals --> Telemetry[Telemetry, when allowed]

In words: a menu chooses the level, the data layer constructs its map and rules, the battle advances bases/troops/AI, and result signals update the UI and player progress. GameManager persists local state; telemetry observes selected events only when permitted. Not all state changes go through EventBus—some systems call GameManager directly.

main_menu.tscn is the project entry scene. On a new save, MainMenuUI starts europe_1 immediately; subsequent visits build the selected menu page. UIThemeHelper.start_battle() selects the level and switches to battle_field.tscn.

Autoload order is declared in project.godot:

AutoloadRole
EventBusShared battle, reward, economy, appearance, settings, and save-replacement signals
GameManagerCurrent selection, player progress, economy, settings, validation, and persistence
AudioManagerSynthesized sound/music playback, volume settings, and lifecycle suspension
AchievementManagerObserves battle signals, updates statistics, XP/missions, and achievement unlocks
ToastsBrief notifications outside individual pages
AptabaseVendored analytics client; provider initialization is controlled by Telemetry
TelemetryUsage/crash integration, privacy gates, and event context

LevelDatabase routes campaign, inv_…, conquest_…, and daily_… identifiers to their definitions. Built levels are cached by identifier, language, and orientation.

LevelDatabase.mode_of() is the shared mode classifier. Campaign labels use level_name() without constructing geography; get_level_ids() returns a cached, read-only campaign order (duplicate it before extending a list).

  • InvasionDatabase describes regions and constructs three fronts per region.
  • LevelGenerator builds deterministic maps, projects real city coordinates, separates bases for interaction, adds eligible neutral cities, and clips the visible geography.
  • CampaignRules applies continent/region properties, connected sea routes, bosses, and daily holding objectives.
  • GeoDatabase loads geo.json on demand. MapProjection handles Mercator projection; TerritoryMap2D draws political geography and territorial cells.

Difficulty and AI cadence come from LevelDatabase.get_balance(), not the player’s upgrade purchases. Orientation changes preserve content and rules; daily challenges keep a canonical board for comparable records. A seeded scenario is not a guarantee of identical rendered pixels across GPUs/fonts.

BattleController loads the level, instantiates bases and enemy controllers, accepts gestures, dispatches orders, and evaluates battle outcomes. It advances troop packets, resolves collisions, then resolves arrivals, so a large frame step cannot simply skip a crossing fight.

BaseNode owns production, capacity, defense, captures, and base presentation. Troop represents an order split into packets, including delayed departure, retreat, and source-loss behavior. AIController uses seeded decisions, projected defense, incoming-force estimates, and faction archetypes. Player and AI dispatches share the battle controller’s route checks.

Orders are plain Troop.new() nodes. Movement and both arrival previews share the troop arrival formula. Formation offsets and closed territory outlines are prepared once and reused; they do not change simulation timing or rendering. GameManager.victory_rewards() owns mode-specific economy/progression, while the battle controller still decides the outcome and emits the same result events.

The BattleHUD handles briefing/HUD, pause/help, alternate accessible controls, and results. The tutorial overlay guides early interactions.

The five main-menu pages are registered in MainMenuUI.TABS. Scrolling pages inherit ScrollPage, implement _build(), and rebuild after economy changes. Play uses its own responsive map/briefing layout. A successful backup restore or progress reset emits EventBus.save_replaced; MainMenuUI rebuilds the header, badges, and mounted page from the new state without reloading the scene.

UIThemeHelper centralizes palettes, typography, theme variations, reusable controls, safe areas, scaling, and scene transitions. Icons provides the shared SVG icon set. Use these rather than duplicating styling inside new pages.

LocaleStrings resolves translation keys; LanguageCatalog defines locale normalization, font scripts, and RTL direction. Translations and geographic names feed the font subset tools. See the localization workflow.

GameManager saves a versioned JSON document (currently format 7), with field validation, temporary-file replacement, a .previous recovery copy, future-format protection, and confirmed manual import with a .backup copy. Import/reset preserve privacy choices. Successful replacements emit save_replaced once memory and disk agree; failed operations emit no UI refresh. Keep city, level, cosmetic, and achievement identifiers stable where saves refer to them; test migrations before changing the schema.

Unchanged, validated saves skip disk writes without replacing the recovery point. Battle results and achievement checks batch saves within one synchronous action; the outer end_save_batch() reports the commit result. Slider changes can request one deferred save per frame. Manual/lifecycle saves remain synchronous and flush pending requests. Audio/haptic sliders do not broadcast visual settings changes.

On focus loss, progress is saved, audio is suspended, and battle gestures are canceled. The HUD requires explicit resume. An active battle is not serialized. See Platform integration for platform behavior.

Telemetry defaults to enabled in this source, respects independent saved settings, and suppresses providers in tests/headless runs or with --no-telemetry. Public ingestion keys are not administrative credentials. See Analytics and Security.

MusicSynth reads or generates music on the existing worker threads. Its private user://music_cache stores PCM WAV files keyed by synthesis version and track specification. Invalid caches regenerate; unavailable storage never blocks music. Successful writes replace obsolete versions of that track. Bump MusicSynth.CACHE_VERSION when changing synthesis. Muted startup does not prewarm music; sound effects, music samples, and loop boundaries are otherwise unchanged.

ChangeStart withVerify with
Campaign levels, difficulty, continent mechanicslevel_database.gd, campaign_rules.gdFull regression suite and balance simulation
Invasion content/unlocks/rewardsinvasion_database.gd, game_manager.gd, invasion_tab.gdInvasion regressions, balance sample, and invasion UI
Combat, troop packets, enemy decisionsscripts/battle/Full regressions, low-FPS/collision cases, balance and manual controls
Menus, themes, accessibilityscripts/ui/, UIThemeHelperQuick regressions, locale UI, wide/rotated/gesture checks, device QA
Save data, settings, or backupsgame_manager.gd, settings_panel.gdMobile/full regressions, migration and failure-path tests, native picker QA
Translation or city nameslocale/strings.csv, locale overrides, geo.jsonGlyph/format/layout checks, font regeneration if needed, native-language review
Sound/musicaudio_manager.gd, scripts/audio/music_synth.gdFull audio regressions and manual listening/lifecycle checks
Telemetrytelemetry.gd, addons/aptabase/Privacy/schema/local HTTP tests and native-device review
Store screenshots/copyscripts/tests/store_assets.gd, docs/store_listing/Existing store generator and validator; see store guide
Build, native SDK, or release automationtools/, build scripts, workflows, pluginsPython/artifact checks and explicit maintainer review; see Releases

Paths abbreviated to filenames above are within the directories described in this guide. The testing guide contains runnable commands. This is a map of responsibilities, not a generated API reference or a proposed refactor.