# thespheric/guebo architecture

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

- Interactive diagram: https://gitdiagram.com/thespheric/guebo
- Repository: https://github.com/thespheric/guebo

## Overview

This repository is a small Haxe game built on Flixel-style runtime code. The architecture is centered around a single playable state, with most gameplay behavior split into reusable entity classes and a scripting layer for content-driven stages.

1. Boot and state flow  
`source/Main.hx` is the entry point, and `source/PlayState.hx` appears to be the main gameplay state. The runtime likely boots into `PlayState`, which then creates the player, enemies, bullets, and stage logic.

2. Core gameplay layer  
The `source/obj` folder contains the main in-game objects: `Player`, `Enemy`, `Bullet`, `PlayerBullet`, `Shooter`, `BulletSpawner`, and `BulletSpawnerGroup`. This suggests the game is organized around a shoot-’em-up style loop where actors emit bullets and manage attack patterns.

3. Player/combat boundary  
`Player.hx` is separate from projectile classes, which implies player movement and input are isolated from combat output. `PlayerBullet.hx` suggests player firing is modeled independently from generic `Bullet.hx`, allowing different collision or behavior rules.

4. Enemy system  
`Enemy.hx` is the base enemy abstraction, with specific enemies layered on top. `EnemyDatabase.hx` likely acts as a lookup/factory layer for instantiating enemy types or configuring their stats/patterns. `source/obj/enemies/FairyAah.hx` is a concrete enemy implementation.

5. Pattern and spawning subsystem  
`Shooter.hx`, `BulletSpawner.hx`, and `BulletSpawnerGroup.hx` indicate a modular firing system. Rather than embedding all attack logic inside enemies, the game likely composes enemies from shooter/spawner components, making patterns reusable across enemy types.

6. Script-driven content  
`source/scripts/HScript.hx` and `source/obj/enemies/HScriptEnemy.hx` show that the game can execute enemy or stage behavior from scripts. The script file `assets/scripts/stage/stg0.hx` is a content asset, not just code, which means stage behavior is designed to be data/script-driven rather than hardcoded only in the main source tree.

7. Event decoupling  
`source/backend/EventManager.hx` suggests a lightweight event bus or dispatcher used to coordinate gameplay systems without tight coupling. In a game like this, that typically connects state changes, spawning, scripting triggers, and maybe audio or UI reactions.

8. Asset organization boundary  
The `assets` tree is cleanly partitioned into `data`, `images`, `music`, `sounds`, and `scripts`. That separation implies the code layer handles mechanics, while content is loaded from asset folders at runtime. The text placeholder files indicate these folders are expected to be populated by real game content.

9. Engine/runtime dependency  
`source/flixel/FlxBasic.hx` indicates a local copy or override of a Flixel core class, which is a meaningful architectural detail: the repo is not just consuming the engine, it may be adapting or vendoring part of it. That suggests some engine-level behavior is customized locally.

10. Likely overall data flow  
Game start -> `Main` -> `PlayState` -> load assets and stage script -> create player and enemy objects -> enemies use shooter/spawner logic to emit bullets -> `EventManager` and scripting coordinate transitions, patterns, or stage events. The major boundary is between static code objects and script/content assets.

11. Diagramming guidance  
For an architecture diagram, the main boxes should be: boot/state, gameplay entities, enemy/pattern system, scripting layer, event manager, and asset storage. The key arrows are from `PlayState` into entities, from scripts into enemy/stage behavior, and from events back into gameplay objects.

Main entry points: [`source/PlayState.hx`](https://github.com/thespheric/guebo/blob/main/source/PlayState.hx) (Play State), [`source/obj/Bullet.hx`](https://github.com/thespheric/guebo/blob/main/source/obj/Bullet.hx) (Bullet), [`source/obj/Enemy.hx`](https://github.com/thespheric/guebo/blob/main/source/obj/Enemy.hx) (Enemy), [`source/obj/Player.hx`](https://github.com/thespheric/guebo/blob/main/source/obj/Player.hx) (Player)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_boot["Boot & state"]
  node_main["Main<br/>entrypoint<br/>[Main.hx]"]
  node_playstate["Play State<br/>game state<br/>[PlayState.hx]"]
end

subgraph group_gameplay["Gameplay entities"]
  node_player["Player<br/>actor<br/>[Player.hx]"]
  node_playerbullet(("Player Bullet<br/>projectile<br/>[PlayerBullet.hx]"))
  node_bullet(("Bullet<br/>projectile base<br/>[Bullet.hx]"))
end

subgraph group_enemy["Enemy system"]
  node_enemybase["Enemy<br/>[Enemy.hx]"]
  node_faryaah["FairyAah<br/>enemy impl<br/>[FairyAah.hx]"]
  node_enemydb["Enemy DB<br/>enemy registry<br/>[EnemyDatabase.hx]"]
end

subgraph group_pattern["Patterns & spawning"]
  node_shooter{{"Shooter<br/>fire pattern<br/>[Shooter.hx]"}}
  node_spawner{{"Spawner<br/>bullet emitter<br/>[BulletSpawner.hx]"}}
  node_spawnergroup{{"Spawner Group<br/>pattern group"}}
end

subgraph group_scripting["Scripting layer"]
  node_hscript["HScript<br/>script runtime<br/>[HScript.hx]"]
  node_scriptenemy["Script Enemy<br/>scripted enemy<br/>[HScriptEnemy.hx]"]
end

subgraph group_platform["Runtime support"]
  node_eventmgr(("Event Manager<br/>event bus<br/>[EventManager.hx]"))
  node_flxbasic["FlxBasic<br/>runtime override<br/>[FlxBasic.hx]"]
end

subgraph group_assets["Content assets"]
  node_stg0["Stage 0<br/>stage script<br/>[stg0.hx]"]
end

node_main -->|"starts"| node_playstate
node_playstate -->|"creates"| node_player
node_playstate -->|"loads enemies"| node_enemydb
node_playstate -->|"subscribes"| node_eventmgr
node_playstate -->|"runs stage"| node_stg0
node_playstate -->|"executes"| node_hscript
node_player -->|"fires"| node_playerbullet
node_playerbullet -->|"extends"| node_bullet
node_enemybase -->|"uses"| node_bullet
node_enemybase -->|"composes"| node_shooter
node_shooter -->|"organizes"| node_spawnergroup
node_spawnergroup -->|"contains"| node_spawner
node_spawner -->|"emits"| node_bullet
node_enemydb -->|"instantiates"| node_faryaah
node_scriptenemy -->|"delegates"| node_hscript
node_stg0 -->|"configures"| node_scriptenemy
node_eventmgr -->|"signals"| node_playstate
node_flxbasic -->|"supports"| node_playstate

click node_main "https://github.com/thespheric/guebo/blob/main/source/Main.hx"
click node_playstate "https://github.com/thespheric/guebo/blob/main/source/PlayState.hx"
click node_player "https://github.com/thespheric/guebo/blob/main/source/obj/Player.hx"
click node_playerbullet "https://github.com/thespheric/guebo/blob/main/source/obj/PlayerBullet.hx"
click node_bullet "https://github.com/thespheric/guebo/blob/main/source/obj/Bullet.hx"
click node_enemybase "https://github.com/thespheric/guebo/blob/main/source/obj/Enemy.hx"
click node_faryaah "https://github.com/thespheric/guebo/blob/main/source/obj/enemies/FairyAah.hx"
click node_enemydb "https://github.com/thespheric/guebo/blob/main/source/obj/EnemyDatabase.hx"
click node_shooter "https://github.com/thespheric/guebo/blob/main/source/obj/Shooter.hx"
click node_spawner "https://github.com/thespheric/guebo/blob/main/source/obj/BulletSpawner.hx"
click node_spawnergroup "https://github.com/thespheric/guebo/blob/main/source/obj/BulletSpawnerGroup.hx"
click node_hscript "https://github.com/thespheric/guebo/blob/main/source/scripts/HScript.hx"
click node_scriptenemy "https://github.com/thespheric/guebo/blob/main/source/obj/enemies/HScriptEnemy.hx"
click node_eventmgr "https://github.com/thespheric/guebo/blob/main/source/backend/EventManager.hx"
click node_flxbasic "https://github.com/thespheric/guebo/blob/main/source/flixel/FlxBasic.hx"
click node_stg0 "https://github.com/thespheric/guebo/blob/main/assets/scripts/stage/stg0.hx"

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_main,node_playstate,node_stg0 toneBlue
class node_player,node_playerbullet,node_bullet toneAmber
class node_enemybase,node_faryaah,node_enemydb toneMint
class node_shooter,node_spawner,node_spawnergroup toneRose
class node_hscript,node_scriptenemy toneIndigo
class node_eventmgr,node_flxbasic toneTeal
```

## Components

### Boot & state

Application entrypoint and main gameplay state.

- [Main](https://github.com/thespheric/guebo/blob/main/source/Main.hx): entrypoint · Program entry and startup bootstrap. · `source/Main.hx`
- [Play State](https://github.com/thespheric/guebo/blob/main/source/PlayState.hx): game state · Primary gameplay state that owns the active stage. · `source/PlayState.hx`

### Gameplay entities

Core in-game actors and projectiles.

- [Player](https://github.com/thespheric/guebo/blob/main/source/obj/Player.hx): actor · Controllable player character and movement/input boundary. · `source/obj/Player.hx`
- [Player Bullet](https://github.com/thespheric/guebo/blob/main/source/obj/PlayerBullet.hx): projectile · Projectile behavior for player-fired shots. · `source/obj/PlayerBullet.hx`
- [Bullet](https://github.com/thespheric/guebo/blob/main/source/obj/Bullet.hx): projectile base · Shared projectile logic for bullets in the game. · `source/obj/Bullet.hx`

### Enemy system

Enemy base classes and concrete enemy implementations.

- [Enemy](https://github.com/thespheric/guebo/blob/main/source/obj/Enemy.hx): enemy base · Base enemy abstraction used by concrete enemies. · `source/obj/Enemy.hx`
- [FairyAah](https://github.com/thespheric/guebo/blob/main/source/obj/enemies/FairyAah.hx): enemy impl · Concrete enemy implementation. · `source/obj/enemies/FairyAah.hx`
- [Enemy DB](https://github.com/thespheric/guebo/blob/main/source/obj/EnemyDatabase.hx): enemy registry · Lookup and configuration layer for enemy types. · `source/obj/EnemyDatabase.hx`

### Patterns & spawning

Reusable shooting and bullet spawning components.

- [Shooter](https://github.com/thespheric/guebo/blob/main/source/obj/Shooter.hx): fire pattern · Reusable firing/pattern component. · `source/obj/Shooter.hx`
- [Spawner](https://github.com/thespheric/guebo/blob/main/source/obj/BulletSpawner.hx): bullet emitter · Single bullet emission unit used by patterns and enemies. · `source/obj/BulletSpawner.hx`
- [Spawner Group](https://github.com/thespheric/guebo/blob/main/source/obj/BulletSpawnerGroup.hx): pattern group · Collection of spawners for coordinated attack patterns. · `source/obj/BulletSpawnerGroup.hx`

### Scripting layer

Script execution and script-backed enemy behavior.

- [HScript](https://github.com/thespheric/guebo/blob/main/source/scripts/HScript.hx): script runtime · Script execution layer for content-driven behavior. · `source/scripts/HScript.hx`
- [Script Enemy](https://github.com/thespheric/guebo/blob/main/source/obj/enemies/HScriptEnemy.hx): scripted enemy · Enemy wrapper that delegates behavior to scripts. · `source/obj/enemies/HScriptEnemy.hx`

### Runtime support

Local engine/runtime overrides and event coordination.

- [Event Manager](https://github.com/thespheric/guebo/blob/main/source/backend/EventManager.hx): event bus · Lightweight dispatcher for gameplay and stage events. · `source/backend/EventManager.hx`
- [FlxBasic](https://github.com/thespheric/guebo/blob/main/source/flixel/FlxBasic.hx): runtime override · Local engine-level Flixel class adaptation. · `source/flixel/FlxBasic.hx`

### Content assets

Runtime-loaded stage and media content.

- [Stage 0](https://github.com/thespheric/guebo/blob/main/assets/scripts/stage/stg0.hx): stage script · Scripted stage content defining stage behavior and events. · `assets/scripts/stage/stg0.hx`

## Connections

- Main → Play State: starts · Bootstraps the main gameplay state.
- Play State → Player: creates · Instantiates the player for the active stage.
- Play State → Enemy DB: loads enemies · Resolves enemy types and configs for the stage.
- Play State → Event Manager: subscribes · Coordinates gameplay through shared events.
- Play State → Stage 0: runs stage · Loads scripted stage content during play.
- Play State → HScript: executes · Uses the script runtime to drive scripted content.
- Player → Player Bullet: fires · Produces player-specific projectiles.
- Player Bullet → Bullet: extends · Reuses shared bullet behavior.
- Enemy → Bullet: uses · Enemy behavior emits shared bullet logic.
- Enemy → Shooter: composes · Enemies delegate attack logic to shooters.
- Shooter → Spawner Group: organizes · Groups spawners into reusable patterns.
- Spawner Group → Spawner: contains · Coordinates individual bullet emitters.
- Spawner → Bullet: emits · Creates bullet instances as part of a pattern.
- Enemy DB → FairyAah: instantiates · Maps database entries to concrete enemy implementations.
- Script Enemy → HScript: delegates · Behavior is driven by scripts rather than hardcoded logic.
- Stage 0 → Script Enemy: configures · Stage script can define scripted enemy behavior.
- Event Manager → Play State: signals · Dispatches state and stage events back into gameplay.
- FlxBasic → Play State: supports · Local engine override underpins state behavior.
