# zhouit/z25d architecture

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

- Interactive diagram: https://gitdiagram.com/zhouit/z25d
- Repository: https://github.com/zhouit/z25d

## Overview

1. **Overall shape**
   - This is a **JavaFX-based 2.5D RPG**. The codebase is organized around a lightweight game framework rather than a general web/app architecture.
   - The main runtime concerns are: **scene/controller switching**, **map and sprite state**, **resource loading**, **movement/pathfinding**, **dialog/script playback**, and **combat**.

2. **Entry and application bootstrap**
   - `src/com/arpg/index/Bootstrap.java` is the likely application entry point.
   - `IndexController` appears to manage the initial/start screen and transition into the game.
   - The `index` package acts as the top-level startup boundary before control moves into game subsystems.

3. **Controller-driven game flow**
   - Controllers are the central orchestration layer: `Controller`, `AbstarctController`, `MenuController`, `RpgController`, `FightController`, `ActFightController`, `ScriptController`, and `MapEditor`.
   - These controllers likely represent distinct application modes or screens:
     - menu/startup
     - overworld RPG play
     - scripted cutscenes/dialog
     - battle
     - map editing
   - `ViewResolver` suggests a layer that binds a controller/state to the appropriate JavaFX view.

4. **Shared game state containers**
   - `ContextContainer`, `MapContainer`, and `SpriteContainer` are the main shared-state hubs.
   - They likely hold the current world state, active map, sprite collections, and other mutable runtime data.
   - This is an important architectural boundary: controllers coordinate behavior, while containers hold the current game snapshot.

5. **Sprite system**
   - The `sprite` package defines the entity model for characters and moving objects:
     - `Sprite`, `SpriteState`, `SpriteType`, `SpriteContainer`
   - `ImageSpriteFactory` builds sprite instances from assets.
   - This subsystem is responsible for how characters are represented, animated, and categorized in the world.

6. **Map and world representation**
   - The `MapContainer` and `ImageMapFactory` pair suggest map loading and map state management.
   - Map data lives under `resource/image/map/*.map`, indicating a custom map format rather than a standard engine format.
   - The game includes multiple map types/areas, and the runtime likely switches among them through controller logic and teleport handling.

7. **Movement and navigation**
   - `src/com/arpg/astar/Astar.java` and `Node.java` implement pathfinding for automated movement.
   - The README explicitly lists “astar自动寻路” and “精灵八方走”, so the movement system supports **8-direction movement** plus **auto-routing**.
   - This subsystem sits between player input/controller logic and map collision/path data.

8. **Teleportation and scene transitions**
   - `Tepleporter.java` appears to handle map-to-map transitions.
   - This is part of the world navigation boundary: when a character reaches a trigger or portal, the active map and state in the containers are swapped.

9. **Scripted story / dialog subsystem**
   - The `avg` package is a dialogue/cutscene layer:
     - `Cg`, `Message`, `ScriptController`
     - script file: `src/com/arpg/avg/script/script.sc`
   - This indicates a simple script interpreter or scenario runner used for story sequences and text-driven events.
   - It is separate from combat and overworld control, but likely invoked by the main RPG controller.

10. **Combat subsystem**
   - The `fight` package contains the battle logic:
     - `FightController`, `ActFightController`
     - `Magic`, `MagicType`, `Stopwatch`
     - `magic.xml`
   - Combat appears to be data-driven for spell definitions and likely time/turn-based or action-based through `Stopwatch`.
   - This is a distinct mode with its own controller and resource set.

11. **Editor tooling**
   - `src/com/arpg/editor/MapEditor.java` and `MapConfig.java` define an in-app or companion **map editor**.
   - The editor is part of the same codebase, indicating the project bundles both gameplay and authoring tools.
   - This is relevant to architecture because map data is likely produced by the editor and consumed by the runtime map loader.

12. **Resource and asset pipeline**
   - Runtime assets are under `resource/`:
     - `audio/bg.mp3`
     - images for index, magic, maps, role faces
     - map files under `resource/image/map`
   - Utility classes such as `ResourceManager`, `AudioManager`, `ImageUtils`, `JavafxImageWriter`, `NinePatch`, and `FontUtils` form the asset-loading/rendering support layer.
   - The architecture depends heavily on these utilities because much of the game’s state is externalized in files.

13. **Utility and infrastructure layer**
   - Common helpers in `utils` provide string, math, I/O, threading, and resource abstractions.
   - `RpgConstants` centralizes shared constants.
   - These utilities are not domain features themselves, but they support all major subsystems and reduce duplication across controllers and loaders.

14. **Testing and debug support**
   - `src/test/com/arpg/Tests.java` and `DebugUilts.java` indicate some internal validation/debug tooling.
   - This likely supports development of maps, sprites, or pathfinding rather than a broad automated test suite.

15. **How the pieces connect**
   - The typical flow is: **bootstrap → index/menu → game controller → load map/sprites/resources → render/update world → pathfinding/teleport/script/fight as needed**.
   - The most important architectural boundaries for a diagram are:
     - **controllers vs. shared containers**
     - **runtime gameplay vs. editor tooling**
     - **world exploration vs. scripted dialogue vs. combat**
     - **code vs. external asset files** (maps, scripts, XML, audio, images)

Main entry points: [`src/com/arpg/RpgController.java`](https://github.com/zhouit/z25d/blob/master/src/com/arpg/RpgController.java) (RPG Ctrl), [`src/com/arpg/fight/FightController.java`](https://github.com/zhouit/z25d/blob/master/src/com/arpg/fight/FightController.java) (Fight Ctrl), [`src/com/arpg/index/IndexController.java`](https://github.com/zhouit/z25d/blob/master/src/com/arpg/index/IndexController.java) (Index Ctrl), [`src/com/arpg/utils/ResourceManager.java`](https://github.com/zhouit/z25d/blob/master/src/com/arpg/utils/ResourceManager.java) (Resource Manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_startup["Startup & UI"]
  node_bootstrap["Bootstrap<br/>app entry<br/>[Bootstrap.java]"]
  node_index_controller["Index Ctrl<br/>startup controller"]
  node_view_resolver["View Resolver<br/>view binding<br/>[ViewResolver.java]"]
  node_base_controller["Base Ctrl<br/>controller base<br/>[Controller.java]"]
  node_abstract_controller["Abstract Ctrl<br/>controller base"]
  node_menu_controller["Menu Ctrl<br/>menu mode"]
end

subgraph group_runtime["Game Runtime"]
  node_rpg_controller["RPG Ctrl<br/>overworld controller<br/>[RpgController.java]"]
  node_context_container[("Context<br/>runtime state")]
  node_map_container[("Map State<br/>world state<br/>[MapContainer.java]")]
  node_sprite_container[("Sprite State<br/>entity state")]
  node_sprite_model(("Sprite<br/>entity model<br/>[Sprite.java]"))
end

subgraph group_systems["Gameplay Systems"]
  node_pathfinding{{"A* Path<br/>navigation<br/>[Astar.java]"}}
  node_teleporter["Teleporter<br/>scene transition<br/>[Tepleporter.java]"]
  node_script_controller["Script Ctrl<br/>dialog system"]
  node_fight_controller["Fight Ctrl<br/>combat mode"]
  node_act_fight_controller["Act Fight<br/>combat mode"]
  node_magic_model{{"Magic<br/>combat data<br/>[Magic.java]"}}
end

subgraph group_assets["Resources & Tools"]
  node_sprite_factory["Sprite Factory<br/>entity factory"]
  node_map_factory["Map Factory"]
  node_resource_manager["Resource Manager<br/>asset loader"]
  node_map_editor["Map Editor<br/>editor tool<br/>[MapEditor.java]"]
  node_script_data["Script File<br/>external script<br/>[script.sc]"]
  node_magic_data["Magic XML<br/>external data<br/>[magic.xml]"]
end

node_bootstrap -->|"starts"| node_index_controller
node_index_controller -->|"binds"| node_view_resolver
node_index_controller -->|"opens"| node_menu_controller
node_menu_controller -->|"enters"| node_rpg_controller
node_rpg_controller -->|"reads/writes"| node_context_container
node_rpg_controller -->|"updates"| node_map_container
node_rpg_controller -->|"updates"| node_sprite_container
node_sprite_container -->|"contains"| node_sprite_model
node_sprite_factory -->|"creates"| node_sprite_model
node_map_factory -->|"loads"| node_map_container
node_resource_manager -->|"feeds"| node_sprite_factory
node_resource_manager -->|"feeds"| node_map_factory
node_rpg_controller -->|"uses"| node_pathfinding
node_rpg_controller -->|"triggers"| node_teleporter
node_rpg_controller -->|"invokes"| node_script_controller
node_rpg_controller -->|"switches to"| node_fight_controller
node_fight_controller -->|"coordinates"| node_act_fight_controller
node_fight_controller -->|"uses"| node_magic_model
node_script_controller -->|"plays"| node_script_data
node_fight_controller -->|"loads"| node_magic_data
node_map_editor -->|"writes/reads"| node_map_factory
node_map_editor -->|"uses"| node_resource_manager

click node_bootstrap "https://github.com/zhouit/z25d/blob/master/src/com/arpg/index/Bootstrap.java"
click node_index_controller "https://github.com/zhouit/z25d/blob/master/src/com/arpg/index/IndexController.java"
click node_view_resolver "https://github.com/zhouit/z25d/blob/master/src/com/arpg/ViewResolver.java"
click node_base_controller "https://github.com/zhouit/z25d/blob/master/src/com/arpg/Controller.java"
click node_abstract_controller "https://github.com/zhouit/z25d/blob/master/src/com/arpg/AbstarctController.java"
click node_menu_controller "https://github.com/zhouit/z25d/blob/master/src/com/arpg/MenuController.java"
click node_rpg_controller "https://github.com/zhouit/z25d/blob/master/src/com/arpg/RpgController.java"
click node_context_container "https://github.com/zhouit/z25d/blob/master/src/com/arpg/ContextContainer.java"
click node_map_container "https://github.com/zhouit/z25d/blob/master/src/com/arpg/MapContainer.java"
click node_sprite_container "https://github.com/zhouit/z25d/blob/master/src/com/arpg/sprite/SpriteContainer.java"
click node_sprite_model "https://github.com/zhouit/z25d/blob/master/src/com/arpg/sprite/Sprite.java"
click node_sprite_factory "https://github.com/zhouit/z25d/blob/master/src/com/arpg/ImageSpriteFactory.java"
click node_map_factory "https://github.com/zhouit/z25d/blob/master/src/com/arpg/ImageMapFactory.java"
click node_pathfinding "https://github.com/zhouit/z25d/blob/master/src/com/arpg/astar/Astar.java"
click node_teleporter "https://github.com/zhouit/z25d/blob/master/src/com/arpg/Tepleporter.java"
click node_script_controller "https://github.com/zhouit/z25d/blob/master/src/com/arpg/avg/ScriptController.java"
click node_fight_controller "https://github.com/zhouit/z25d/blob/master/src/com/arpg/fight/FightController.java"
click node_act_fight_controller "https://github.com/zhouit/z25d/blob/master/src/com/arpg/fight/ActFightController.java"
click node_magic_model "https://github.com/zhouit/z25d/blob/master/src/com/arpg/fight/Magic.java"
click node_resource_manager "https://github.com/zhouit/z25d/blob/master/src/com/arpg/utils/ResourceManager.java"
click node_map_editor "https://github.com/zhouit/z25d/blob/master/src/com/arpg/editor/MapEditor.java"
click node_script_data "https://github.com/zhouit/z25d/blob/master/src/com/arpg/avg/script/script.sc"
click node_magic_data "https://github.com/zhouit/z25d/blob/master/src/com/arpg/fight/magic.xml"

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_bootstrap,node_index_controller,node_view_resolver,node_base_controller,node_abstract_controller,node_menu_controller toneBlue
class node_rpg_controller,node_context_container,node_map_container,node_sprite_container,node_sprite_model toneAmber
class node_pathfinding,node_teleporter,node_script_controller,node_fight_controller,node_act_fight_controller,node_magic_model toneMint
class node_sprite_factory,node_map_factory,node_resource_manager,node_map_editor,node_script_data,node_magic_data toneRose
```

## Components

### Startup & UI

Application bootstrap and screen/controller switching.

- [Bootstrap](https://github.com/zhouit/z25d/blob/master/src/com/arpg/index/Bootstrap.java): app entry · JavaFX application entry point. · `src/com/arpg/index/Bootstrap.java`
- [Index Ctrl](https://github.com/zhouit/z25d/blob/master/src/com/arpg/index/IndexController.java): startup controller · Initial screen and transition into the game. · `src/com/arpg/index/IndexController.java`
- [View Resolver](https://github.com/zhouit/z25d/blob/master/src/com/arpg/ViewResolver.java): view binding · Maps controllers or states to JavaFX views. · `src/com/arpg/ViewResolver.java`
- [Base Ctrl](https://github.com/zhouit/z25d/blob/master/src/com/arpg/Controller.java): controller base · Common controller contract and shared behavior. · `src/com/arpg/Controller.java`
- [Abstract Ctrl](https://github.com/zhouit/z25d/blob/master/src/com/arpg/AbstarctController.java): controller base · Shared controller implementation layer. · `src/com/arpg/AbstarctController.java`
- [Menu Ctrl](https://github.com/zhouit/z25d/blob/master/src/com/arpg/MenuController.java): menu mode · Menu and start-screen flow. · `src/com/arpg/MenuController.java`

### Game Runtime

Shared state and world exploration flow.

- [RPG Ctrl](https://github.com/zhouit/z25d/blob/master/src/com/arpg/RpgController.java): overworld controller · Main exploration and gameplay orchestration. · `src/com/arpg/RpgController.java`
- [Context](https://github.com/zhouit/z25d/blob/master/src/com/arpg/ContextContainer.java): runtime state · Shared mutable game context. · `src/com/arpg/ContextContainer.java`
- [Map State](https://github.com/zhouit/z25d/blob/master/src/com/arpg/MapContainer.java): world state · Current map and map-level runtime state. · `src/com/arpg/MapContainer.java`
- [Sprite State](https://github.com/zhouit/z25d/blob/master/src/com/arpg/sprite/SpriteContainer.java): entity state · Active sprites and their runtime state. · `src/com/arpg/sprite/SpriteContainer.java`
- [Sprite](https://github.com/zhouit/z25d/blob/master/src/com/arpg/sprite/Sprite.java): entity model · Core sprite representation and behavior. · `src/com/arpg/sprite/Sprite.java`

### Gameplay Systems

Pathfinding, scripts, combat, and movement helpers.

- [A* Path](https://github.com/zhouit/z25d/blob/master/src/com/arpg/astar/Astar.java): navigation · Auto-routing and navigation graph search. · `src/com/arpg/astar/Astar.java`
- [Teleporter](https://github.com/zhouit/z25d/blob/master/src/com/arpg/Tepleporter.java): scene transition · Handles map-to-map transitions and portals. · `src/com/arpg/Tepleporter.java`
- [Script Ctrl](https://github.com/zhouit/z25d/blob/master/src/com/arpg/avg/ScriptController.java): dialog system · Runs cutscenes, dialog, and scripted events. · `src/com/arpg/avg/ScriptController.java`
- [Fight Ctrl](https://github.com/zhouit/z25d/blob/master/src/com/arpg/fight/FightController.java): combat mode · Battle-mode orchestration. · `src/com/arpg/fight/FightController.java`
- [Act Fight](https://github.com/zhouit/z25d/blob/master/src/com/arpg/fight/ActFightController.java): combat mode · Action/combat variant controller. · `src/com/arpg/fight/ActFightController.java`
- [Magic](https://github.com/zhouit/z25d/blob/master/src/com/arpg/fight/Magic.java): combat data · Spell definitions and combat abilities. · `src/com/arpg/fight/Magic.java`

### Resources & Tools

Asset loading, external data, and editor tooling.

- [Sprite Factory](https://github.com/zhouit/z25d/blob/master/src/com/arpg/ImageSpriteFactory.java): entity factory · Builds sprites from image resources. · `src/com/arpg/ImageSpriteFactory.java`
- [Map Factory](https://github.com/zhouit/z25d/blob/master/src/com/arpg/ImageMapFactory.java): map factory · Loads map data and constructs map state. · `src/com/arpg/ImageMapFactory.java`
- [Resource Manager](https://github.com/zhouit/z25d/blob/master/src/com/arpg/utils/ResourceManager.java): asset loader · Loads images, audio, and other runtime resources. · `src/com/arpg/utils/ResourceManager.java`
- [Map Editor](https://github.com/zhouit/z25d/blob/master/src/com/arpg/editor/MapEditor.java): editor tool · In-app map editing and authoring. · `src/com/arpg/editor/MapEditor.java`
- [Script File](https://github.com/zhouit/z25d/blob/master/src/com/arpg/avg/script/script.sc): external script · Dialogue/script scenario data. · `src/com/arpg/avg/script/script.sc`
- [Magic XML](https://github.com/zhouit/z25d/blob/master/src/com/arpg/fight/magic.xml): external data · Combat spell configuration data. · `src/com/arpg/fight/magic.xml`

## Connections

- Bootstrap → Index Ctrl: starts · Bootstraps the application into the initial screen.
- Index Ctrl → View Resolver: binds · Resolves the initial UI view.
- Index Ctrl → Menu Ctrl: opens · Moves from the index into menu flow.
- Menu Ctrl → RPG Ctrl: enters · Launches main gameplay.
- RPG Ctrl → Context: reads/writes · Uses shared runtime context.
- RPG Ctrl → Map State: updates · Switches and mutates active map state.
- RPG Ctrl → Sprite State: updates · Coordinates active sprites.
- Sprite State → Sprite: contains · Holds sprite instances and state.
- Sprite Factory → Sprite: creates · Constructs sprites from assets.
- Map Factory → Map State: loads · Builds map state from external map files.
- Resource Manager → Sprite Factory: feeds · Supplies image assets for sprites.
- Resource Manager → Map Factory: feeds · Supplies image and map resources.
- RPG Ctrl → A* Path: uses · Requests auto-routing for movement.
- RPG Ctrl → Teleporter: triggers · Handles area transitions and portals.
- RPG Ctrl → Script Ctrl: invokes · Launches scripted events and dialog.
- RPG Ctrl → Fight Ctrl: switches to · Enters battle mode from exploration.
- Fight Ctrl → Act Fight: coordinates · Battle flow may delegate to action combat variant.
- Fight Ctrl → Magic: uses · Consumes spell data during combat.
- Script Ctrl → Script File: plays · Interprets external scenario/script data.
- Fight Ctrl → Magic XML: loads · Reads combat configuration from XML.
- Map Editor → Map Factory: writes/reads · Authoring tool works with the same map format.
- Map Editor → Resource Manager: uses · Loads and saves editor assets.
