# tateorrtot/foxbox architecture

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

- Interactive diagram: https://gitdiagram.com/tateorrtot/foxbox
- Repository: https://github.com/tateorrtot/foxbox

## Overview

#### Purpose and Runtime
This is a Godot project containing **Foxbox**, a modular GDScript framework for reusable 2D/3D gameplay systems, plus demo scenes and editor/developer addons. It runs inside the Godot Engine; the project/export boundary is `project.godot` and `export_presets.cfg`. No server-side runtime or external application service is evident.

#### Entry Points and Distribution
Foxbox’s main framework-facing entry is `addons/foxbox/foxbox.gd`, with addon metadata in `addons/foxbox/plugin.cfg`. Consumable behavior is demonstrated through independently runnable Godot scenes under `foxbox_demos/`, such as `foxbox_demos/character/character_demo.tscn` and `foxbox_demos/shop/shop_demo.tscn`. Prebuilt Windows and Android demo artifacts are committed under `exports/`.

#### Core Foundation and Composition
The framework establishes reusable Godot base types and value-model primitives:
- `addons/foxbox/core/components/fox_node.gd`
- `addons/foxbox/core/components/fox_node_3d.gd`
- `addons/foxbox/core/math/fox_stat_pool.gd`

These form a boundary between Godot node/resource lifecycle concerns and higher-level modules. Domain features are designed as attachable nodes, scenes, resources, and scripts rather than a single application flow.

#### Character Control Pipeline
The largest subsystem is 3D character composition. Input/ability intent is translated into motor movement and state transitions, then represented through model, animation, camera, accessories, shadows, and held items.
- Motors: `addons/foxbox/character/components/motors/fox_character_motor_3d.gd`, `addons/foxbox/character/components/motors/fox_advanced_character_motor_3d.gd`
- State/abilities: `addons/foxbox/character/components/state_machine/fox_character_grounded_state.gd`, `addons/foxbox/character/components/abilities/fox_dash_ability.gd`
- Presentation: `addons/foxbox/character/refactor/model/fox_character_model.tscn`, `addons/foxbox/character/refactor/model/animation/fox_character_animation_tree.gd`

The `refactor/` model path and `components/trash/` path indicate active replacement of an older character assembly.

#### Gameplay Interaction Modules
Independent modules expose physics- and scene-facing boundaries:
- Damage detection separates hit producers from hurt receivers: `addons/foxbox/damage/fox_hit_area_3d.gd`, `addons/foxbox/damage/fox_hurt_area_3d.gd`.
- Interaction separates targetable areas from raycast selection: `addons/foxbox/interaction/fox_interactable_area_3d.gd`, `addons/foxbox/interaction/fox_interaction_raycast_3d.gd`.
- Effects manage definitions, instances, and slot policies: `addons/foxbox/effect/fox_effect.gd`, `addons/foxbox/effect/fox_effect_manager.gd`.
- Generic behavior transitions use `addons/foxbox/state_machine/fox_state_machine.gd`.

Related optional capabilities include socket attachment, physics dragging, aim gimbals, camera zoom, and environmental scenes.

#### Economy and UI Boundary
The shop subsystem separates catalog/item/price/wallet domain objects from Godot UI:
- Domain: `addons/foxbox/shop/core/fox_shop_catalog.gd`, `addons/foxbox/shop/core/fox_wallet.gd`
- Concrete simple economy: `addons/foxbox/shop/simple/fox_simple_wallet.gd`
- Presentation: `addons/foxbox/shop/gui/fox_shop_menu.gd`

A shop scene consumes these abstractions in `foxbox_demos/shop/shop_demo.tscn`; there is no evidence of payment-provider or backend integration.

#### Development-Time Tooling and Documentation
Separate Godot editor addons provide signal graph visualization, TODO management, and project validation:
- Signal visualization: `addons/SignalVisualizer/SignalVisualizer.gd`, `addons/SignalVisualizer/Visualizer/signal_visualizer_dock.gd`
- Validation supports editor and CLI collection/reporting, including JUnit XML: `addons/godot_doctor/core/godot_doctor_runner.gd`, `addons/godot_doctor/cli/godot_doctor_cli_runner.gd`
- Generated API documentation is maintained under `docs/xml_output/` and `docs/web/`; these are outputs/documentation infrastructure, not runtime framework modules.

Main entry points: [`addons/foxbox/foxbox.gd`](https://github.com/tateorrtot/foxbox/blob/main/addons/foxbox/foxbox.gd) (Foxbox entry), [`addons/foxbox/character/components/motors/fox_character_motor_3d.gd`](https://github.com/tateorrtot/foxbox/blob/main/addons/foxbox/character/components/motors/fox_character_motor_3d.gd) (Character motors), [`addons/foxbox/core/components/fox_node.gd`](https://github.com/tateorrtot/foxbox/blob/main/addons/foxbox/core/components/fox_node.gd) (Base node types), [`addons/foxbox/shop/core/fox_shop_catalog.gd`](https://github.com/tateorrtot/foxbox/blob/main/addons/foxbox/shop/core/fox_shop_catalog.gd) (Shop domain)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Godot Runtime"]
  node_godot{{"Godot Engine"}}
  node_project["Project &amp; export config<br/>Godot project boundary<br/>[project.godot]"]
  node_character_demo["Character demo<br/>runnable scene"]
  node_shop_demo["Shop demo<br/>runnable scene<br/>[shop_demo.tscn]"]
end

subgraph group_foundation["Foxbox Foundation"]
  node_foxbox["Foxbox entry<br/>framework addon<br/>[foxbox.gd]"]
  node_fox_node["Base node types<br/>GDScript components<br/>[fox_node.gd]"]
  node_stat_pool["Stat pools<br/>value model<br/>[fox_stat_pool.gd]"]
end

subgraph group_character["Character Pipeline"]
  node_character_motor["Character motors<br/>movement components"]
  node_character_state["Grounded state &amp; dash<br/>state and ability"]
  node_character_model["Character model<br/>3D presentation scene"]
  node_character_animation["Animation tree<br/>animation controller"]
end

subgraph group_gameplay["Gameplay Modules"]
  node_damage["Damage areas<br/>hit and hurt physics<br/>[fox_hit_area_3d.gd]"]
  node_interaction["Interaction<br/>targeting and raycast"]
  node_effects["Effects manager<br/>effect lifecycle"]
  node_state_machine["Generic state machine<br/>behavior transitions"]
end

subgraph group_economy["Economy &amp; UI"]
  node_shop_domain["Shop domain<br/>catalog and wallet"]
  node_shop_wallet["Simple wallet<br/>economy implementation"]
  node_shop_ui["Shop menu<br/>Godot UI<br/>[fox_shop_menu.gd]"]
end

subgraph group_tooling["Developer Tooling"]
  node_signal_visualizer["Signal Visualizer<br/>editor addon"]
  node_doctor["Godot Doctor<br/>editor and CLI validator"]
  node_docs["Generated API docs<br/>documentation output"]
end

node_godot -->|"loads"| node_project
node_project -->|"enables"| node_foxbox
node_foxbox -->|"builds on"| node_fox_node
node_foxbox -->|"provides"| node_stat_pool
node_foxbox -->|"provides"| node_character_motor
node_foxbox -->|"provides"| node_damage
node_foxbox -->|"provides"| node_interaction
node_foxbox -->|"provides"| node_effects
node_foxbox -->|"provides"| node_shop_domain
node_character_state -->|"drives movement"| node_character_motor
node_character_motor -->|"updates"| node_character_model
node_character_model -->|"uses"| node_character_animation
node_state_machine -->|"supports"| node_character_state
node_fox_node -.->|"base lifecycle"| node_damage
node_fox_node -.->|"base lifecycle"| node_interaction
node_shop_domain -->|"implemented by"| node_shop_wallet
node_shop_domain -->|"presented by"| node_shop_ui
node_character_demo -->|"demonstrates"| node_character_motor
node_character_demo -->|"demonstrates"| node_character_model
node_shop_demo -->|"runs"| node_shop_ui
node_shop_demo -->|"uses"| node_shop_wallet
node_godot -.->|"editor hosts"| node_signal_visualizer
node_godot -.->|"editor and CLI host"| node_doctor
node_foxbox -.->|"documented by"| node_docs

click node_project "https://github.com/tateorrtot/foxbox/blob/main/project.godot"
click node_foxbox "https://github.com/tateorrtot/foxbox/blob/main/addons/foxbox/foxbox.gd"
click node_fox_node "https://github.com/tateorrtot/foxbox/blob/main/addons/foxbox/core/components/fox_node.gd"
click node_stat_pool "https://github.com/tateorrtot/foxbox/blob/main/addons/foxbox/core/math/fox_stat_pool.gd"
click node_character_motor "https://github.com/tateorrtot/foxbox/blob/main/addons/foxbox/character/components/motors/fox_character_motor_3d.gd"
click node_character_state "https://github.com/tateorrtot/foxbox/blob/main/addons/foxbox/character/components/state_machine/fox_character_grounded_state.gd"
click node_character_model "https://github.com/tateorrtot/foxbox/blob/main/addons/foxbox/character/refactor/model/fox_character_model.tscn"
click node_character_animation "https://github.com/tateorrtot/foxbox/blob/main/addons/foxbox/character/refactor/model/animation/fox_character_animation_tree.gd"
click node_damage "https://github.com/tateorrtot/foxbox/blob/main/addons/foxbox/damage/fox_hit_area_3d.gd"
click node_interaction "https://github.com/tateorrtot/foxbox/blob/main/addons/foxbox/interaction/fox_interactable_area_3d.gd"
click node_effects "https://github.com/tateorrtot/foxbox/blob/main/addons/foxbox/effect/fox_effect_manager.gd"
click node_state_machine "https://github.com/tateorrtot/foxbox/blob/main/addons/foxbox/state_machine/fox_state_machine.gd"
click node_shop_domain "https://github.com/tateorrtot/foxbox/blob/main/addons/foxbox/shop/core/fox_shop_catalog.gd"
click node_shop_wallet "https://github.com/tateorrtot/foxbox/blob/main/addons/foxbox/shop/simple/fox_simple_wallet.gd"
click node_shop_ui "https://github.com/tateorrtot/foxbox/blob/main/addons/foxbox/shop/gui/fox_shop_menu.gd"
click node_character_demo "https://github.com/tateorrtot/foxbox/blob/main/foxbox_demos/character/character_demo.tscn"
click node_shop_demo "https://github.com/tateorrtot/foxbox/blob/main/foxbox_demos/shop/shop_demo.tscn"
click node_signal_visualizer "https://github.com/tateorrtot/foxbox/blob/main/addons/SignalVisualizer/SignalVisualizer.gd"
click node_doctor "https://github.com/tateorrtot/foxbox/blob/main/addons/godot_doctor/core/godot_doctor_runner.gd"

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_godot,node_project,node_character_demo,node_shop_demo toneBlue
class node_foxbox,node_fox_node,node_stat_pool toneAmber
class node_character_motor,node_character_state,node_character_model,node_character_animation toneMint
class node_damage,node_interaction,node_effects,node_state_machine toneRose
class node_shop_domain,node_shop_wallet,node_shop_ui toneIndigo
class node_signal_visualizer,node_doctor,node_docs toneTeal
```

## Components

### Godot Runtime

- **Godot Engine**: engine · Hosts project, scenes, addons, and exports.
- [Project & export config](https://github.com/tateorrtot/foxbox/blob/main/project.godot): Godot project boundary · `project.godot`
- [Character demo](https://github.com/tateorrtot/foxbox/blob/main/foxbox_demos/character/character_demo.tscn): runnable scene · `foxbox_demos/character/character_demo.tscn`
- [Shop demo](https://github.com/tateorrtot/foxbox/blob/main/foxbox_demos/shop/shop_demo.tscn): runnable scene · `foxbox_demos/shop/shop_demo.tscn`

### Foxbox Foundation

- [Foxbox entry](https://github.com/tateorrtot/foxbox/blob/main/addons/foxbox/foxbox.gd): framework addon · `addons/foxbox/foxbox.gd`
- [Base node types](https://github.com/tateorrtot/foxbox/blob/main/addons/foxbox/core/components/fox_node.gd): GDScript components · Reusable Godot lifecycle boundary for feature nodes. · `addons/foxbox/core/components/fox_node.gd`
- [Stat pools](https://github.com/tateorrtot/foxbox/blob/main/addons/foxbox/core/math/fox_stat_pool.gd): value model · `addons/foxbox/core/math/fox_stat_pool.gd`

### Character Pipeline

- [Character motors](https://github.com/tateorrtot/foxbox/blob/main/addons/foxbox/character/components/motors/fox_character_motor_3d.gd): movement components · `addons/foxbox/character/components/motors/fox_character_motor_3d.gd`
- [Grounded state & dash](https://github.com/tateorrtot/foxbox/blob/main/addons/foxbox/character/components/state_machine/fox_character_grounded_state.gd): state and ability · `addons/foxbox/character/components/state_machine/fox_character_grounded_state.gd`
- [Character model](https://github.com/tateorrtot/foxbox/blob/main/addons/foxbox/character/refactor/model/fox_character_model.tscn): 3D presentation scene · `addons/foxbox/character/refactor/model/fox_character_model.tscn`
- [Animation tree](https://github.com/tateorrtot/foxbox/blob/main/addons/foxbox/character/refactor/model/animation/fox_character_animation_tree.gd): animation controller · `addons/foxbox/character/refactor/model/animation/fox_character_animation_tree.gd`

### Gameplay Modules

- [Damage areas](https://github.com/tateorrtot/foxbox/blob/main/addons/foxbox/damage/fox_hit_area_3d.gd): hit and hurt physics · `addons/foxbox/damage/fox_hit_area_3d.gd`
- [Interaction](https://github.com/tateorrtot/foxbox/blob/main/addons/foxbox/interaction/fox_interactable_area_3d.gd): targeting and raycast · `addons/foxbox/interaction/fox_interactable_area_3d.gd`
- [Effects manager](https://github.com/tateorrtot/foxbox/blob/main/addons/foxbox/effect/fox_effect_manager.gd): effect lifecycle · `addons/foxbox/effect/fox_effect_manager.gd`
- [Generic state machine](https://github.com/tateorrtot/foxbox/blob/main/addons/foxbox/state_machine/fox_state_machine.gd): behavior transitions · `addons/foxbox/state_machine/fox_state_machine.gd`

### Economy & UI

- [Shop domain](https://github.com/tateorrtot/foxbox/blob/main/addons/foxbox/shop/core/fox_shop_catalog.gd): catalog and wallet · `addons/foxbox/shop/core/fox_shop_catalog.gd`
- [Simple wallet](https://github.com/tateorrtot/foxbox/blob/main/addons/foxbox/shop/simple/fox_simple_wallet.gd): economy implementation · `addons/foxbox/shop/simple/fox_simple_wallet.gd`
- [Shop menu](https://github.com/tateorrtot/foxbox/blob/main/addons/foxbox/shop/gui/fox_shop_menu.gd): Godot UI · `addons/foxbox/shop/gui/fox_shop_menu.gd`

### Developer Tooling

- [Signal Visualizer](https://github.com/tateorrtot/foxbox/blob/main/addons/SignalVisualizer/SignalVisualizer.gd): editor addon · `addons/SignalVisualizer/SignalVisualizer.gd`
- [Godot Doctor](https://github.com/tateorrtot/foxbox/blob/main/addons/godot_doctor/core/godot_doctor_runner.gd): editor and CLI validator · Collects validation results and can report JUnit XML. · `addons/godot_doctor/core/godot_doctor_runner.gd`
- **Generated API docs**: documentation output

## Connections

- Godot Engine → Project & export config: loads
- Project & export config → Foxbox entry: enables
- Foxbox entry → Base node types: builds on
- Foxbox entry → Stat pools: provides
- Foxbox entry → Character motors: provides
- Foxbox entry → Damage areas: provides
- Foxbox entry → Interaction: provides
- Foxbox entry → Effects manager: provides
- Foxbox entry → Shop domain: provides
- Grounded state & dash → Character motors: drives movement
- Character motors → Character model: updates
- Character model → Animation tree: uses
- Generic state machine → Grounded state & dash: supports
- Base node types → Damage areas: base lifecycle
- Base node types → Interaction: base lifecycle
- Shop domain → Simple wallet: implemented by
- Shop domain → Shop menu: presented by
- Character demo → Character motors: demonstrates
- Character demo → Character model: demonstrates
- Shop demo → Shop menu: runs
- Shop demo → Simple wallet: uses
- Godot Engine → Signal Visualizer: editor hosts
- Godot Engine → Godot Doctor: editor and CLI host
- Foxbox entry → Generated API docs: documented by