# rdarida/gameforge architecture

> Architecture diagram of the GitHub repository rdarida/gameforge, 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/rdarida/gameforge
- Repository: https://github.com/rdarida/gameforge

## Overview

1. **Project shape**
   - This is a **TypeScript library**, not an application server or backend.
   - Its purpose is to provide a **lightweight HTML5 2D game prototyping framework** built on top of **PixiJS**, with audio support via **@pixi/sound** and font loading via **webfontloader**.
   - The main public API is exposed from `src/index.ts` and packaged for npm.

2. **Top-level architecture**
   - The code is organized into a few clear subsystems: **scene management**, **animation**, **utility helpers**, **event types**, and a small **list/binding abstraction**.
   - Each subsystem has its own `index.ts` barrel file, and the root barrel re-exports the library surface.

3. **Scene subsystem**
   - `src/scene/SceneManager.ts` is the central coordinator for game flow.
   - `Scene.ts` is the likely lifecycle base for a game screen or state.
   - `Panel.ts` and `Button.ts` are UI-facing scene components, suggesting the framework includes built-in primitives for interactive overlays and menus.
   - This subsystem is the main boundary between game logic and rendering/input state.

4. **Event model**
   - `src/events/SceneEvent.ts` defines scene-related events separate from rendering details.
   - This suggests scene transitions and lifecycle changes are communicated through domain events rather than direct coupling.
   - The event layer is small and purpose-specific, likely used by `SceneManager` and `Scene` implementations.

5. **Animation subsystem**
   - `src/animation/Tween.ts` and `src/animation/Transition.ts` handle time-based interpolation and state changes.
   - These modules form the time-driven behavior layer for moving, fading, or easing properties in scenes.
   - They are supported by `src/utils/TimeUtil.ts`, which likely standardizes time calculations and frame progression.

6. **Utility layer**
   - `ColorUtil.ts`, `MathUtil.ts`, `PointUtil.ts`, and `TimeUtil.ts` provide reusable low-level helpers.
   - These are shared support modules rather than architecture centers, but they reduce duplication across scenes and animation.
   - The utilities are grouped separately from core scene logic, which keeps the framework modular.

7. **List/binding abstraction**
   - `src/utils/list/` contains `List.ts`, `Item.ts`, and `Binder.ts`.
   - This looks like a lightweight collection/binding system, probably for tracking items and wiring them together without direct framework dependencies.
   - It likely supports internal state management or simple observer-style relationships used elsewhere in the library.

8. **Runtime flow**
   - The expected runtime path is: **browser game loop / PixiJS app → SceneManager → active Scene → UI or animation helpers → render/update**.
   - Assets and media are not managed by a backend; they are loaded in the client runtime through browser APIs and Pixi-related libraries.
   - The framework appears designed for **client-side HTML5 game prototypes**, not for persistent server-side state.

9. **Public surface and boundaries**
   - The `src/*/index.ts` files define the module boundaries for consumers.
   - Internal helpers under `utils` and subsystem internals are likely meant to stay behind those barrels.
   - This indicates a deliberate separation between **stable API exports** and **implementation details**.

10. **Build, test, and documentation pipeline**
   - The repo uses **tsup** for bundling, **Jest** for tests, and **TypeScript** configuration for type safety.
   - `typedoc.json` suggests generated API documentation is part of the project.
   - GitHub Actions handle testing, publishing, and GitHub Pages deployment, while release management is automated through `release-it`.

11. **Quality and distribution**
   - The repository is set up for package publishing to **npm**, with CI/CD hooks for release automation.
   - SonarCloud integration is present for coverage/quality reporting.
   - The architecture is therefore not just library code, but a complete **open-source package pipeline** from source to published artifact and documentation site.

Main entry points: [`src/index.ts`](https://github.com/rdarida/gameforge/blob/main/src/index.ts) (Public API), [`src/scene/index.ts`](https://github.com/rdarida/gameforge/blob/main/src/scene/index.ts) (Scene API), [`package.json`](https://github.com/rdarida/gameforge/blob/main/package.json) (Package build), [`src/animation/index.ts`](https://github.com/rdarida/gameforge/blob/main/src/animation/index.ts) (Animation API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core runtime"]
  node_root["Public API<br/>barrel<br/>[index.ts]"]
  node_scene_index["Scene API<br/>barrel<br/>[index.ts]"]
  node_scene_manager["Scene manager<br/>coordinator<br/>[SceneManager.ts]"]
  node_scene_base["Scene base<br/>lifecycle<br/>[Scene.ts]"]
  node_panel["Panel<br/>ui component<br/>[Panel.ts]"]
  node_button["Button<br/>ui control<br/>[Button.ts]"]
  node_events_index["Events API<br/>barrel<br/>[index.ts]"]
  node_scene_event["Scene event<br/>domain event<br/>[SceneEvent.ts]"]
  node_animation_index["Animation API<br/>barrel<br/>[index.ts]"]
  node_tween["Tween<br/>interpolation<br/>[Tween.ts]"]
  node_transition["Transition<br/>state motion<br/>[Transition.ts]"]
end

subgraph group_support["Support code"]
  node_utils_index["Utils API<br/>barrel<br/>[index.ts]"]
  node_time_util["Time util<br/>helper<br/>[TimeUtil.ts]"]
  node_math_util["Math/color/point<br/>helpers<br/>[MathUtil.ts]"]
  node_list_index["List API<br/>barrel<br/>[index.ts]"]
  node_list["List<br/>collection<br/>[List.ts]"]
  node_item["Item<br/>list element<br/>[Item.ts]"]
  node_binder["Binder<br/>binding<br/>[Binder.ts]"]
end

subgraph group_tooling["Tooling"]
  node_package[("Package build<br/>distribution<br/>[package.json]")]
  node_tsup["Tsup<br/>bundler config<br/>[tsup.config.ts]"]
  node_jest["Jest<br/>test config<br/>[jest.config.ts]"]
  node_typedoc["Typedoc<br/>docs config<br/>[typedoc.json]"]
  node_github_actions["GitHub Actions<br/>ci pipeline<br/>[test.yml]"]
end

node_root -->|"re-exports"| node_scene_index
node_root -->|"re-exports"| node_events_index
node_root -->|"re-exports"| node_animation_index
node_root -->|"re-exports"| node_utils_index
node_root -->|"re-exports"| node_list_index
node_scene_index -->|"exports"| node_scene_manager
node_scene_index -->|"exports"| node_scene_base
node_scene_index -->|"exports"| node_panel
node_scene_index -->|"exports"| node_button
node_scene_manager -->|"emits"| node_scene_event
node_events_index -->|"exports"| node_scene_event
node_animation_index -->|"exports"| node_tween
node_animation_index -->|"exports"| node_transition
node_animation_index -->|"uses"| node_time_util
node_utils_index -->|"exports"| node_time_util
node_utils_index -->|"exports"| node_math_util
node_list_index -->|"exports"| node_list
node_list_index -->|"exports"| node_item
node_list_index -->|"exports"| node_binder
node_scene_base -->|"uses"| node_panel
node_scene_base -->|"uses"| node_button
node_package -->|"drives"| node_tsup
node_package -->|"drives"| node_jest
node_package -->|"drives"| node_typedoc
node_package -->|"automates"| node_github_actions

click node_root "https://github.com/rdarida/gameforge/blob/main/src/index.ts"
click node_scene_index "https://github.com/rdarida/gameforge/blob/main/src/scene/index.ts"
click node_scene_manager "https://github.com/rdarida/gameforge/blob/main/src/scene/SceneManager.ts"
click node_scene_base "https://github.com/rdarida/gameforge/blob/main/src/scene/Scene.ts"
click node_panel "https://github.com/rdarida/gameforge/blob/main/src/scene/Panel.ts"
click node_button "https://github.com/rdarida/gameforge/blob/main/src/scene/Button.ts"
click node_events_index "https://github.com/rdarida/gameforge/blob/main/src/events/index.ts"
click node_scene_event "https://github.com/rdarida/gameforge/blob/main/src/events/SceneEvent.ts"
click node_animation_index "https://github.com/rdarida/gameforge/blob/main/src/animation/index.ts"
click node_tween "https://github.com/rdarida/gameforge/blob/main/src/animation/Tween.ts"
click node_transition "https://github.com/rdarida/gameforge/blob/main/src/animation/Transition.ts"
click node_utils_index "https://github.com/rdarida/gameforge/blob/main/src/utils/index.ts"
click node_time_util "https://github.com/rdarida/gameforge/blob/main/src/utils/TimeUtil.ts"
click node_math_util "https://github.com/rdarida/gameforge/blob/main/src/utils/MathUtil.ts"
click node_list_index "https://github.com/rdarida/gameforge/blob/main/src/utils/list/index.ts"
click node_list "https://github.com/rdarida/gameforge/blob/main/src/utils/list/List.ts"
click node_item "https://github.com/rdarida/gameforge/blob/main/src/utils/list/Item.ts"
click node_binder "https://github.com/rdarida/gameforge/blob/main/src/utils/list/Binder.ts"
click node_package "https://github.com/rdarida/gameforge/blob/main/package.json"
click node_tsup "https://github.com/rdarida/gameforge/blob/main/tsup.config.ts"
click node_jest "https://github.com/rdarida/gameforge/blob/main/jest.config.ts"
click node_typedoc "https://github.com/rdarida/gameforge/blob/main/typedoc.json"
click node_github_actions "https://github.com/rdarida/gameforge/blob/main/.github/workflows/test.yml"

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_root,node_scene_index,node_scene_manager,node_scene_base,node_panel,node_button,node_events_index,node_scene_event,node_animation_index,node_tween,node_transition toneBlue
class node_utils_index,node_time_util,node_math_util,node_list_index,node_list,node_item,node_binder toneAmber
class node_package,node_tsup,node_jest,node_typedoc,node_github_actions toneMint
```

## Components

### Core runtime

Public library surface and game framework subsystems

- [Public API](https://github.com/rdarida/gameforge/blob/main/src/index.ts): barrel · Top-level npm surface exported from src/index.ts · `src/index.ts`
- [Scene API](https://github.com/rdarida/gameforge/blob/main/src/scene/index.ts): barrel · Scene subsystem exports · `src/scene/index.ts`
- [Scene manager](https://github.com/rdarida/gameforge/blob/main/src/scene/SceneManager.ts): coordinator · Central game-flow controller · `src/scene/SceneManager.ts`
- [Scene base](https://github.com/rdarida/gameforge/blob/main/src/scene/Scene.ts): lifecycle · Base screen/state abstraction · `src/scene/Scene.ts`
- [Panel](https://github.com/rdarida/gameforge/blob/main/src/scene/Panel.ts): ui component · UI container for overlays and menus · `src/scene/Panel.ts`
- [Button](https://github.com/rdarida/gameforge/blob/main/src/scene/Button.ts): ui control · Interactive scene primitive · `src/scene/Button.ts`
- [Events API](https://github.com/rdarida/gameforge/blob/main/src/events/index.ts): barrel · Scene event exports · `src/events/index.ts`
- [Scene event](https://github.com/rdarida/gameforge/blob/main/src/events/SceneEvent.ts): domain event · Lifecycle and transition event model · `src/events/SceneEvent.ts`
- [Animation API](https://github.com/rdarida/gameforge/blob/main/src/animation/index.ts): barrel · Time-based behavior exports · `src/animation/index.ts`
- [Tween](https://github.com/rdarida/gameforge/blob/main/src/animation/Tween.ts): interpolation · Property animation over time · `src/animation/Tween.ts`
- [Transition](https://github.com/rdarida/gameforge/blob/main/src/animation/Transition.ts): state motion · Scene or state transition logic · `src/animation/Transition.ts`

### Support code

Reusable utilities and small binding abstractions

- [Utils API](https://github.com/rdarida/gameforge/blob/main/src/utils/index.ts): barrel · Shared helper exports · `src/utils/index.ts`
- [Time util](https://github.com/rdarida/gameforge/blob/main/src/utils/TimeUtil.ts): helper · Frame and duration calculations · `src/utils/TimeUtil.ts`
- [Math/color/point](https://github.com/rdarida/gameforge/blob/main/src/utils/MathUtil.ts): helpers · Low-level geometry and numeric helpers · `src/utils/MathUtil.ts`
- [List API](https://github.com/rdarida/gameforge/blob/main/src/utils/list/index.ts): barrel · Collection and binding exports · `src/utils/list/index.ts`
- [List](https://github.com/rdarida/gameforge/blob/main/src/utils/list/List.ts): collection · Lightweight list abstraction · `src/utils/list/List.ts`
- [Item](https://github.com/rdarida/gameforge/blob/main/src/utils/list/Item.ts): list element · Tracked list entry · `src/utils/list/Item.ts`
- [Binder](https://github.com/rdarida/gameforge/blob/main/src/utils/list/Binder.ts): binding · Links items or values together · `src/utils/list/Binder.ts`

### Tooling

Build, test, docs, and release automation

- [Package build](https://github.com/rdarida/gameforge/blob/main/package.json): distribution · npm packaging and bundling configuration · `package.json`
- [Tsup](https://github.com/rdarida/gameforge/blob/main/tsup.config.ts): bundler config · Build pipeline configuration · `tsup.config.ts`
- [Jest](https://github.com/rdarida/gameforge/blob/main/jest.config.ts): test config · Test runner configuration · `jest.config.ts`
- [Typedoc](https://github.com/rdarida/gameforge/blob/main/typedoc.json): docs config · API documentation generation · `typedoc.json`
- [GitHub Actions](https://github.com/rdarida/gameforge/blob/main/.github/workflows/test.yml): ci pipeline · Test, publish, pages, and merge automation · `.github/workflows/test.yml`

## Connections

- Public API → Scene API: re-exports · Root API exposes scene subsystem
- Public API → Events API: re-exports · Root API exposes event types
- Public API → Animation API: re-exports · Root API exposes animation primitives
- Public API → Utils API: re-exports · Root API exposes shared helpers
- Public API → List API: re-exports · Root API exposes list abstractions
- Scene API → Scene manager: exports · Scene manager is the central coordinator
- Scene API → Scene base: exports · Scene lifecycle base
- Scene API → Panel: exports · UI overlay primitive
- Scene API → Button: exports · Interactive UI primitive
- Scene manager → Scene event: emits · Scene flow is communicated through events
- Events API → Scene event: exports · Event layer surface
- Animation API → Tween: exports · Interpolation primitive
- Animation API → Transition: exports · State transition primitive
- Animation API → Time util: uses · Animations rely on shared time calculations
- Utils API → Time util: exports · Time utilities
- Utils API → Math/color/point: exports · Numeric and geometry helpers
- List API → List: exports · Collection abstraction
- List API → Item: exports · Tracked entry type
- List API → Binder: exports · Binding helper
- Scene base → Panel: uses · Scenes compose UI panels
- Scene base → Button: uses · Scenes compose interactive controls
- Package build → Tsup: drives · Package build uses bundler config
- Package build → Jest: drives · Package scripts run tests
- Package build → Typedoc: drives · Package includes documentation generation
- Package build → GitHub Actions: automates · Repository workflows handle CI and release steps
