# neparij/katawa-shoujo-agb architecture

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

- Interactive diagram: https://gitdiagram.com/neparij/katawa-shoujo-agb
- Repository: https://github.com/neparij/katawa-shoujo-agb

## Overview

This repository is a Game Boy Advance adaptation of Katawa Shoujo. The main player-facing flow is visual-novel play: the scene manager coordinates dialogue, backgrounds, characters, transitions, menus, and saved progress, with music and video playback alongside gameplay. Separate converter tools transform upstream scripts, translations, definitions, and character art for the port. The README also documents oversized event backgrounds and the adapted OST. The supplied excerpts show only parts of runtime wiring; omitted relationships are not inferred.

Main entry points: [`src/scenemanager.cpp`](https://github.com/neparij/katawa-shoujo-agb/blob/main/src/scenemanager.cpp) (Scene manager), [`tools/converter/src/main.py`](https://github.com/neparij/katawa-shoujo-agb/blob/main/tools/converter/src/main.py) (Converter commands), [`src/sound_manager.cpp`](https://github.com/neparij/katawa-shoujo-agb/blob/main/src/sound_manager.cpp) (Sound manager), [`src/menu/menu_ingame_pause.cpp.h`](https://github.com/neparij/katawa-shoujo-agb/blob/main/src/menu/menu_ingame_pause.cpp.h) (Pause and saves menus)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gameplay["Game Runtime"]
  node_scene["Scene manager<br/>[scenemanager.cpp]"]
  node_dialogue["Dialogue UI<br/>[dialogbox.cpp.h]"]
  node_menus["Pause and saves menus"]
  node_globals["Game state<br/>[globals.h]"]
end

subgraph group_assets["Game Content"]
  node_scenario["Scenario definitions<br/>[definitions.h]"]
  node_backgrounds["Background catalog<br/>[background_metas.h]"]
  node_hugebg["Huge backgrounds"]
  node_sprites["Character sprite catalog"]
end

subgraph group_persistence["Save System"]
  node_saves[("Save data<br/>[save_file.cpp]")]
end

subgraph group_media["Audio Video"]
  node_soundmanager["Sound manager<br/>[sound_manager.cpp]"]
  node_soundmix["Audio mixer<br/>[sound_mixer.h]"]
  node_audio8ad["8AD audio player<br/>[player_8ad.iwram.c]"]
  node_audioulc["ULC audio player<br/>[player_ulc.iwram.c]"]
  node_video["Video playback<br/>[video_player.cpp]"]
  node_videoengine["DXTV player<br/>[videoplayer.cpp]"]
end

subgraph group_conversion["Conversion Tools"]
  node_converter["Converter commands<br/>[main.py]"]
  node_scenarioreader["Scenario reader<br/>[scenario_reader.py]"]
  node_spriteconverter["Sprite converter"]
  node_graphics["Graphics tool"]
end

node_player(("Player"))

node_player -.->|"plays through"| node_scene
node_scene -->|"manages dialogue"| node_dialogue
node_scene -->|"dispatches menus"| node_menus
node_scene -->|"updates state"| node_globals
node_scene -->|"uses save data"| node_saves
node_scene -->|"uses backgrounds"| node_backgrounds
node_scene -->|"uses sprite metadata"| node_sprites
node_scene -.->|"supports events"| node_hugebg
node_menus -->|"reads save slots"| node_saves
node_scene -->|"controls sound"| node_soundmanager
node_soundmanager -->|"uses mixer"| node_soundmix
node_soundmanager -->|"dispatches effects"| node_audio8ad
node_soundmanager -->|"dispatches music"| node_audioulc
node_scene -->|"uses video"| node_video
node_video -->|"delegates playback"| node_videoengine
node_converter -->|"reads scripts"| node_scenarioreader
node_converter -->|"converts sprites"| node_spriteconverter
node_converter -.->|"generates graphics"| node_graphics
node_converter -.->|"produces game content"| node_scenario

click node_scene "https://github.com/neparij/katawa-shoujo-agb/blob/main/src/scenemanager.cpp"
click node_dialogue "https://github.com/neparij/katawa-shoujo-agb/blob/main/src/dialogbox.cpp.h"
click node_menus "https://github.com/neparij/katawa-shoujo-agb/blob/main/src/menu/menu_ingame_pause.cpp.h"
click node_globals "https://github.com/neparij/katawa-shoujo-agb/blob/main/src/globals.h"
click node_scenario "https://github.com/neparij/katawa-shoujo-agb/blob/main/include/definitions.h"
click node_backgrounds "https://github.com/neparij/katawa-shoujo-agb/blob/main/include/background_metas.h"
click node_hugebg "https://github.com/neparij/katawa-shoujo-agb/blob/main/src/ks_huge_bgs_manager.cpp"
click node_sprites "https://github.com/neparij/katawa-shoujo-agb/blob/main/include/character_sprite_meta.h"
click node_saves "https://github.com/neparij/katawa-shoujo-agb/blob/main/src/savefile/save_file.cpp"
click node_soundmanager "https://github.com/neparij/katawa-shoujo-agb/blob/main/src/sound_manager.cpp"
click node_soundmix "https://github.com/neparij/katawa-shoujo-agb/blob/main/src/sound/sound_mixer.h"
click node_audio8ad "https://github.com/neparij/katawa-shoujo-agb/blob/main/src/sound/player_8ad.iwram.c"
click node_audioulc "https://github.com/neparij/katawa-shoujo-agb/blob/main/src/sound/player_ulc.iwram.c"
click node_video "https://github.com/neparij/katawa-shoujo-agb/blob/main/src/videoplayer/video_player.cpp"
click node_videoengine "https://github.com/neparij/katawa-shoujo-agb/blob/main/src/dxtvplayer/videoplayer.cpp"
click node_converter "https://github.com/neparij/katawa-shoujo-agb/blob/main/tools/converter/src/main.py"
click node_scenarioreader "https://github.com/neparij/katawa-shoujo-agb/blob/main/tools/converter/src/scenario_reader.py"
click node_spriteconverter "https://github.com/neparij/katawa-shoujo-agb/blob/main/tools/converter/src/character_sprite/character_sprite.py"
click node_graphics "https://github.com/neparij/katawa-shoujo-agb/blob/main/tools/ks_graphics_tool.py"

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_scene,node_dialogue,node_menus,node_globals toneBlue
class node_scenario,node_backgrounds,node_hugebg,node_sprites toneAmber
class node_saves toneMint
class node_soundmanager,node_soundmix,node_audio8ad,node_audioulc,node_video,node_videoengine toneRose
class node_converter,node_scenarioreader,node_spriteconverter,node_graphics,node_player toneIndigo
```

## Components

### Game Runtime

- [Scene manager](https://github.com/neparij/katawa-shoujo-agb/blob/main/src/scenemanager.cpp): `src/scenemanager.cpp`
- [Dialogue UI](https://github.com/neparij/katawa-shoujo-agb/blob/main/src/dialogbox.cpp.h): `src/dialogbox.cpp.h`
- [Pause and saves menus](https://github.com/neparij/katawa-shoujo-agb/blob/main/src/menu/menu_ingame_pause.cpp.h): `src/menu/menu_ingame_pause.cpp.h`
- [Game state](https://github.com/neparij/katawa-shoujo-agb/blob/main/src/globals.h): `src/globals.h`

### Game Content

- [Scenario definitions](https://github.com/neparij/katawa-shoujo-agb/blob/main/include/definitions.h): `include/definitions.h`
- [Background catalog](https://github.com/neparij/katawa-shoujo-agb/blob/main/include/background_metas.h): `include/background_metas.h`
- [Huge backgrounds](https://github.com/neparij/katawa-shoujo-agb/blob/main/src/ks_huge_bgs_manager.cpp): `src/ks_huge_bgs_manager.cpp`
- [Character sprite catalog](https://github.com/neparij/katawa-shoujo-agb/blob/main/include/character_sprite_meta.h): `include/character_sprite_meta.h`

### Save System

- [Save data](https://github.com/neparij/katawa-shoujo-agb/blob/main/src/savefile/save_file.cpp): `src/savefile/save_file.cpp`

### Audio Video

- [Sound manager](https://github.com/neparij/katawa-shoujo-agb/blob/main/src/sound_manager.cpp): `src/sound_manager.cpp`
- [Audio mixer](https://github.com/neparij/katawa-shoujo-agb/blob/main/src/sound/sound_mixer.h): `src/sound/sound_mixer.h`
- [8AD audio player](https://github.com/neparij/katawa-shoujo-agb/blob/main/src/sound/player_8ad.iwram.c): `src/sound/player_8ad.iwram.c`
- [ULC audio player](https://github.com/neparij/katawa-shoujo-agb/blob/main/src/sound/player_ulc.iwram.c): `src/sound/player_ulc.iwram.c`
- [Video playback](https://github.com/neparij/katawa-shoujo-agb/blob/main/src/videoplayer/video_player.cpp): `src/videoplayer/video_player.cpp`
- [DXTV player](https://github.com/neparij/katawa-shoujo-agb/blob/main/src/dxtvplayer/videoplayer.cpp): `src/dxtvplayer/videoplayer.cpp`

### Conversion Tools

- [Converter commands](https://github.com/neparij/katawa-shoujo-agb/blob/main/tools/converter/src/main.py): `tools/converter/src/main.py`
- [Scenario reader](https://github.com/neparij/katawa-shoujo-agb/blob/main/tools/converter/src/scenario_reader.py): `tools/converter/src/scenario_reader.py`
- [Sprite converter](https://github.com/neparij/katawa-shoujo-agb/blob/main/tools/converter/src/character_sprite/character_sprite.py): `tools/converter/src/character_sprite/character_sprite.py`
- [Graphics tool](https://github.com/neparij/katawa-shoujo-agb/blob/main/tools/ks_graphics_tool.py): `tools/ks_graphics_tool.py`

### Other components

- **Player**

## Connections

- Player → Scene manager: plays through
- Scene manager → Dialogue UI: manages dialogue
- Scene manager → Pause and saves menus: dispatches menus (evidence: `src/scenemanager.cpp`)
- Scene manager → Game state: updates state (evidence: `src/scenemanager.cpp`)
- Scene manager → Save data: uses save data (evidence: `src/scenemanager.cpp`)
- Scene manager → Background catalog: uses backgrounds
- Scene manager → Character sprite catalog: uses sprite metadata
- Scene manager → Huge backgrounds: supports events
- Pause and saves menus → Save data: reads save slots
- Scene manager → Sound manager: controls sound (evidence: `src/scenemanager.cpp`)
- Sound manager → Audio mixer: uses mixer (evidence: `src/sound_manager.cpp`)
- Sound manager → 8AD audio player: dispatches effects
- Sound manager → ULC audio player: dispatches music
- Scene manager → Video playback: uses video (evidence: `src/scenemanager.cpp`)
- Video playback → DXTV player: delegates playback (evidence: `src/videoplayer/video_player.cpp`)
- Converter commands → Scenario reader: reads scripts (evidence: `tools/converter/src/main.py`)
- Converter commands → Sprite converter: converts sprites (evidence: `tools/converter/src/main.py`)
- Converter commands → Graphics tool: generates graphics
- Converter commands → Scenario definitions: produces game content
