# adsgames/jim-surface-protocol architecture

> Architecture diagram of the GitHub repository adsgames/jim-surface-protocol, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/adsgames/jim-surface-protocol
- Repository: https://github.com/adsgames/jim-surface-protocol

## Overview

J1M Surface Protocol is a resource-management game about reclaiming a polluted world. The player moves a worker across a generated tile map, gathers resources, builds trees and purifiers, and advances environmental-purity progress; the game also supports upgrades, menus, and saving/loading. The graph follows the documented gameplay and the sampled scene/world ownership. Some subsystems, including lighting and tile rendering details, are represented from the source index and declarations rather than inspected implementation excerpts.

Main entry points: [`src/world/world.cpp`](https://github.com/adsgames/jim-surface-protocol/blob/main/src/world/world.cpp) (World simulation), [`src/tiles/tile_dictionary.cpp`](https://github.com/adsgames/jim-surface-protocol/blob/main/src/tiles/tile_dictionary.cpp) (Tile dictionary), [`src/main.cpp`](https://github.com/adsgames/jim-surface-protocol/blob/main/src/main.cpp) (Application entry), [`src/states/game.cpp`](https://github.com/adsgames/jim-surface-protocol/blob/main/src/states/game.cpp) (Game scene)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Game flow"]
  node_entry["Application entry<br/>[main.cpp]"]
  node_init["Initialization<br/>[init.cpp]"]
  node_intro["Intro screen<br/>[intro.cpp]"]
  node_menu["Main menu<br/>[menu.cpp]"]
  node_game["Game scene<br/>[game.cpp]"]
end

subgraph group_world["World simulation"]
  node_worldcore["World simulation<br/>[world.cpp]"]
  node_effects["World effects<br/>[world_effects.cpp]"]
  node_lighting["World lighting<br/>[world_lighting.cpp]"]
  node_sound["Sound orchestration"]
end

subgraph group_tiles["Terrain and structures"]
  node_map["Tile map<br/>[tile_map.cpp]"]
  node_tiletypes["Tile types<br/>[tile_type.cpp]"]
  node_tiledict["Tile dictionary"]
  node_structures["Structure dictionary"]
end

subgraph group_play["Player systems"]
  node_worker["Worker<br/>[worker.cpp]"]
  node_pathfinder["Pathfinder<br/>[pathfinder.cpp]"]
  node_toolbar["Toolbar<br/>[toolbar.cpp]"]
  node_controls["Input controls<br/>[controls.cpp]"]
end

subgraph group_support["Game services"]
  node_resources["Resource manager<br/>[resource_manager.h]"]
  node_save["Save game<br/>[save_game.cpp]"]
  node_json["JSON utilities<br/>[json_util.cpp]"]
  node_config["Game configuration<br/>[project.h]"]
end

node_player(("Player"))

node_player -.->|"starts"| node_entry
node_entry -->|"binds input"| node_controls
node_entry -->|"registers scene"| node_init
node_entry -->|"registers scene"| node_game
node_entry -->|"registers scene"| node_intro
node_entry -->|"registers scene"| node_menu
node_init -->|"loads"| node_tiledict
node_init -->|"loads"| node_structures
node_intro -->|"uses"| node_controls
node_intro -->|"loads"| node_tiledict
node_intro -->|"loads"| node_structures
node_menu -->|"uses"| node_controls
node_menu -->|"loads or saves"| node_save
node_menu -->|"creates map"| node_map
node_game -->|"updates and draws"| node_worldcore
node_game -->|"handles toolbar"| node_toolbar
node_game -->|"reads input"| node_controls
node_game -->|"saves game"| node_save
node_game -->|"loads tiles"| node_tiledict
node_worldcore -->|"updates worker"| node_worker
node_worldcore -->|"updates map"| node_map
node_worldcore -->|"manages resources"| node_resources
node_worldcore -->|"updates sound"| node_sound
node_worldcore -->|"updates effects"| node_effects
node_worldcore -->|"uses lighting"| node_lighting
node_worldcore -->|"finds routes"| node_pathfinder
node_worker -->|"queries world"| node_worldcore
node_pathfinder -->|"reads traversability"| node_map
node_toolbar -->|"reads input"| node_controls
node_toolbar -->|"uses tile data"| node_tiledict
node_map -->|"generates structures"| node_structures
node_map -.->|"uses tile IDs"| node_tiledict
node_tiledict -->|"creates tile types"| node_tiletypes
node_tiledict -->|"parses definitions"| node_json
node_structures -->|"parses definitions"| node_json
node_config -.->|"provides game settings"| node_worldcore

click node_entry "https://github.com/adsgames/jim-surface-protocol/blob/main/src/main.cpp"
click node_init "https://github.com/adsgames/jim-surface-protocol/blob/main/src/states/init.cpp"
click node_intro "https://github.com/adsgames/jim-surface-protocol/blob/main/src/states/intro.cpp"
click node_menu "https://github.com/adsgames/jim-surface-protocol/blob/main/src/states/menu.cpp"
click node_game "https://github.com/adsgames/jim-surface-protocol/blob/main/src/states/game.cpp"
click node_worldcore "https://github.com/adsgames/jim-surface-protocol/blob/main/src/world/world.cpp"
click node_map "https://github.com/adsgames/jim-surface-protocol/blob/main/src/tiles/tile_map.cpp"
click node_tiletypes "https://github.com/adsgames/jim-surface-protocol/blob/main/src/tiles/tile_type.cpp"
click node_tiledict "https://github.com/adsgames/jim-surface-protocol/blob/main/src/tiles/tile_dictionary.cpp"
click node_structures "https://github.com/adsgames/jim-surface-protocol/blob/main/src/tiles/structure_dictionary.cpp"
click node_worker "https://github.com/adsgames/jim-surface-protocol/blob/main/src/tasks/worker.cpp"
click node_pathfinder "https://github.com/adsgames/jim-surface-protocol/blob/main/src/tasks/pathfinder.cpp"
click node_toolbar "https://github.com/adsgames/jim-surface-protocol/blob/main/src/world/toolbar.cpp"
click node_controls "https://github.com/adsgames/jim-surface-protocol/blob/main/src/lib/controls.cpp"
click node_resources "https://github.com/adsgames/jim-surface-protocol/blob/main/src/world/resource_manager.h"
click node_save "https://github.com/adsgames/jim-surface-protocol/blob/main/src/lib/save_game.cpp"
click node_json "https://github.com/adsgames/jim-surface-protocol/blob/main/src/lib/json_util.cpp"
click node_effects "https://github.com/adsgames/jim-surface-protocol/blob/main/src/world/world_effects.cpp"
click node_lighting "https://github.com/adsgames/jim-surface-protocol/blob/main/src/world/world_lighting.cpp"
click node_sound "https://github.com/adsgames/jim-surface-protocol/blob/main/src/world/sound_orchestrator.cpp"
click node_config "https://github.com/adsgames/jim-surface-protocol/blob/main/src/lib/project.h"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entry,node_init,node_intro,node_menu,node_game toneBlue
class node_worldcore,node_effects,node_lighting,node_sound toneAmber
class node_map,node_tiletypes,node_tiledict,node_structures toneMint
class node_worker,node_pathfinder,node_toolbar,node_controls toneRose
class node_resources,node_save,node_json,node_config,node_player toneIndigo
```

## Components

### Game flow

- [Application entry](https://github.com/adsgames/jim-surface-protocol/blob/main/src/main.cpp): `src/main.cpp`
- [Initialization](https://github.com/adsgames/jim-surface-protocol/blob/main/src/states/init.cpp): `src/states/init.cpp`
- [Intro screen](https://github.com/adsgames/jim-surface-protocol/blob/main/src/states/intro.cpp): `src/states/intro.cpp`
- [Main menu](https://github.com/adsgames/jim-surface-protocol/blob/main/src/states/menu.cpp): `src/states/menu.cpp`
- [Game scene](https://github.com/adsgames/jim-surface-protocol/blob/main/src/states/game.cpp): `src/states/game.cpp`

### World simulation

- [World simulation](https://github.com/adsgames/jim-surface-protocol/blob/main/src/world/world.cpp): `src/world/world.cpp`
- [World effects](https://github.com/adsgames/jim-surface-protocol/blob/main/src/world/world_effects.cpp): `src/world/world_effects.cpp`
- [World lighting](https://github.com/adsgames/jim-surface-protocol/blob/main/src/world/world_lighting.cpp): `src/world/world_lighting.cpp`
- [Sound orchestration](https://github.com/adsgames/jim-surface-protocol/blob/main/src/world/sound_orchestrator.cpp): `src/world/sound_orchestrator.cpp`

### Terrain and structures

- [Tile map](https://github.com/adsgames/jim-surface-protocol/blob/main/src/tiles/tile_map.cpp): `src/tiles/tile_map.cpp`
- [Tile types](https://github.com/adsgames/jim-surface-protocol/blob/main/src/tiles/tile_type.cpp): `src/tiles/tile_type.cpp`
- [Tile dictionary](https://github.com/adsgames/jim-surface-protocol/blob/main/src/tiles/tile_dictionary.cpp): `src/tiles/tile_dictionary.cpp`
- [Structure dictionary](https://github.com/adsgames/jim-surface-protocol/blob/main/src/tiles/structure_dictionary.cpp): `src/tiles/structure_dictionary.cpp`

### Player systems

- [Worker](https://github.com/adsgames/jim-surface-protocol/blob/main/src/tasks/worker.cpp): `src/tasks/worker.cpp`
- [Pathfinder](https://github.com/adsgames/jim-surface-protocol/blob/main/src/tasks/pathfinder.cpp): `src/tasks/pathfinder.cpp`
- [Toolbar](https://github.com/adsgames/jim-surface-protocol/blob/main/src/world/toolbar.cpp): `src/world/toolbar.cpp`
- [Input controls](https://github.com/adsgames/jim-surface-protocol/blob/main/src/lib/controls.cpp): `src/lib/controls.cpp`

### Game services

- [Resource manager](https://github.com/adsgames/jim-surface-protocol/blob/main/src/world/resource_manager.h): `src/world/resource_manager.h`
- [Save game](https://github.com/adsgames/jim-surface-protocol/blob/main/src/lib/save_game.cpp): `src/lib/save_game.cpp`
- [JSON utilities](https://github.com/adsgames/jim-surface-protocol/blob/main/src/lib/json_util.cpp): `src/lib/json_util.cpp`
- [Game configuration](https://github.com/adsgames/jim-surface-protocol/blob/main/src/lib/project.h): `src/lib/project.h`

### Other components

- **Player**

## Connections

- Player → Application entry: starts
- Application entry → Input controls: binds input (evidence: `src/main.cpp`)
- Application entry → Initialization: registers scene (evidence: `src/main.cpp`)
- Application entry → Game scene: registers scene (evidence: `src/main.cpp`)
- Application entry → Intro screen: registers scene (evidence: `src/main.cpp`)
- Application entry → Main menu: registers scene (evidence: `src/main.cpp`)
- Initialization → Tile dictionary: loads (evidence: `src/states/init.cpp`)
- Initialization → Structure dictionary: loads (evidence: `src/states/init.cpp`)
- Intro screen → Input controls: uses (evidence: `src/states/intro.cpp`)
- Intro screen → Tile dictionary: loads (evidence: `src/states/intro.cpp`)
- Intro screen → Structure dictionary: loads (evidence: `src/states/intro.cpp`)
- Main menu → Input controls: uses (evidence: `src/states/menu.cpp`)
- Main menu → Save game: loads or saves (evidence: `src/states/menu.cpp`)
- Main menu → Tile map: creates map (evidence: `src/states/menu.cpp`)
- Game scene → World simulation: updates and draws (evidence: `src/states/game.cpp`)
- Game scene → Toolbar: handles toolbar
- Game scene → Input controls: reads input (evidence: `src/states/game.cpp`)
- Game scene → Save game: saves game (evidence: `src/states/game.cpp`)
- Game scene → Tile dictionary: loads tiles (evidence: `src/states/game.cpp`)
- World simulation → Worker: updates worker
- World simulation → Tile map: updates map
- World simulation → Resource manager: manages resources
- World simulation → Sound orchestration: updates sound
- World simulation → World effects: updates effects
- World simulation → World lighting: uses lighting
- World simulation → Pathfinder: finds routes (evidence: `src/world/world.cpp`)
- Worker → World simulation: queries world (evidence: `src/tasks/worker.cpp`)
- Pathfinder → Tile map: reads traversability (evidence: `src/tasks/pathfinder.cpp`)
- Toolbar → Input controls: reads input (evidence: `src/world/toolbar.cpp`)
- Toolbar → Tile dictionary: uses tile data (evidence: `src/world/toolbar.cpp`)
- Tile map → Structure dictionary: generates structures (evidence: `src/tiles/tile_map.cpp`)
- Tile map → Tile dictionary: uses tile IDs
- Tile dictionary → Tile types: creates tile types (evidence: `src/tiles/tile_dictionary.cpp`)
- Tile dictionary → JSON utilities: parses definitions (evidence: `src/tiles/tile_dictionary.cpp`)
- Structure dictionary → JSON utilities: parses definitions (evidence: `src/tiles/structure_dictionary.cpp`)
- Game configuration → World simulation: provides game settings
