How zhouit/z25d works
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: RpgController.java RPG Ctrl · FightController.java Fight Ctrl · IndexController.java Index Ctrl · ResourceManager.java Resource Manager
Components 23
Startup & UI
Application bootstrap and screen/controller switching.
- Bootstrap · JavaFX application entry point.
src/com/arpg/index/Bootstrap.java - Index Ctrl · Initial screen and transition into the game.
src/com/arpg/index/IndexController.java - View Resolver · Maps controllers or states to JavaFX views.
src/com/arpg/ViewResolver.java - Base Ctrl · Common controller contract and shared behavior.
src/com/arpg/Controller.java - Abstract Ctrl · Shared controller implementation layer.
src/com/arpg/AbstarctController.java - Menu Ctrl · Menu and start-screen flow.
src/com/arpg/MenuController.java
Game Runtime
Shared state and world exploration flow.
- RPG Ctrl · Main exploration and gameplay orchestration.
src/com/arpg/RpgController.java - Context · Shared mutable game context.
src/com/arpg/ContextContainer.java - Map State · Current map and map-level runtime state.
src/com/arpg/MapContainer.java - Sprite State · Active sprites and their runtime state.
src/com/arpg/sprite/SpriteContainer.java - Sprite · Core sprite representation and behavior.
src/com/arpg/sprite/Sprite.java
Gameplay Systems
Pathfinding, scripts, combat, and movement helpers.
- A* Path · Auto-routing and navigation graph search.
src/com/arpg/astar/Astar.java - Teleporter · Handles map-to-map transitions and portals.
src/com/arpg/Tepleporter.java - Script Ctrl · Runs cutscenes, dialog, and scripted events.
src/com/arpg/avg/ScriptController.java - Fight Ctrl · Battle-mode orchestration.
src/com/arpg/fight/FightController.java - Act Fight · Action/combat variant controller.
src/com/arpg/fight/ActFightController.java - Magic · Spell definitions and combat abilities.
src/com/arpg/fight/Magic.java
Resources & Tools
Asset loading, external data, and editor tooling.
- Sprite Factory · Builds sprites from image resources.
src/com/arpg/ImageSpriteFactory.java - Map Factory · Loads map data and constructs map state.
src/com/arpg/ImageMapFactory.java - Resource Manager · Loads images, audio, and other runtime resources.
src/com/arpg/utils/ResourceManager.java - Map Editor · In-app map editing and authoring.
src/com/arpg/editor/MapEditor.java - Script File · Dialogue/script scenario data.
src/com/arpg/avg/script/script.sc - Magic XML · Combat spell configuration data.
src/com/arpg/fight/magic.xml
Connections 22
- 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.