# zzz1220/threejs-flappybird architecture

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

- Interactive diagram: https://gitdiagram.com/zzz1220/threejs-flappybird
- Repository: https://github.com/zzz1220/threejs-flappybird

## Overview

1. **Project shape**
   - This is a browser game demo built with **TypeScript + Vite** and centered on **Three.js**.
   - The repository is organized like a small game engine: a bootstrap entry, a game orchestrator, and a set of scene/object modules.

2. **Runtime entry and build boundary**
   - `index.html` is the browser entry point.
   - `src/main.ts` is the application bootstrap that likely creates the game instance and starts the initial state.
   - `vite.config.js`, `tsconfig.json`, and the CI workflow define the build/test pipeline, but they do not affect gameplay architecture directly.

3. **Core orchestration layer**
   - `src/game.ts` is the main coordinator. It is the most important architectural boundary in the repo.
   - It likely owns scene setup, update loops, state transitions, and interactions between the bird, obstacles, score, and UI/status modules.
   - `src/gameStatus.ts` appears to define the game’s state model, such as menu, running, and game-over phases.

4. **Game object model**
   - `src/bird.ts`, `src/pillars.ts`, `src/background.ts`, and `src/baseElement.ts` represent the primary world entities.
   - `baseElement.ts` is likely a shared abstraction for positioned/movable game objects, used by other entities to reduce duplication.
   - `pillars.ts` is the obstacle system, `bird.ts` the player-controlled actor, and `background.ts` the decorative/environment layer.

5. **UI and screen-flow subsystems**
   - `src/menu.ts` and `src/gameover.ts` represent the pre-game and post-game screens.
   - `src/counter.ts` and `src/score.ts` handle visible score display and probably scoring logic.
   - These modules are separate from the world objects, suggesting a clean split between **gameplay** and **overlay/UI**.

6. **Audio subsystem**
   - `src/audioController.ts` is the dedicated sound manager.
   - Audio assets live in `public/audio` with paired `.wav` and `.ogg` files for events like wing, swoosh, hit, point, and die.
   - This implies sound effects are triggered by gameplay events rather than continuously streamed.

7. **Asset and static content boundary**
   - `public/sprites` and `public/audio` are the runtime asset directories served directly by Vite.
   - The sprite/audio assets are external to the TypeScript module graph, so the game code probably references them by URL at runtime.

8. **Data flow through the game**
   - Input and timing likely enter through the game loop in `game.ts`.
   - The bird’s state changes drive collision checks against pillars and the ground/base layer.
   - Collision or scoring events then fan out to the audio controller, score/counter modules, and the status/gameover flow.

9. **State transitions**
   - The likely state progression is:
     - menu/start screen
     - active gameplay
     - game over
     - restart back to menu or gameplay
   - `gameStatus.ts`, `menu.ts`, and `gameover.ts` together define those transitions and what gets rendered or updated in each phase.

10. **Rendering model**
   - Because the project is Three.js-based, rendering is probably scene-graph driven rather than DOM-driven.
   - Game entities are likely translated into Three.js meshes/sprites, while UI/status elements may be overlay elements or scene objects depending on implementation.
   - `background.ts`, `bird.ts`, and `pillars.ts` are the main visual layers in the scene.

11. **Separation of concerns**
   - The repo cleanly separates:
     - orchestration (`game.ts`)
     - domain state (`gameStatus.ts`, `score.ts`)
     - world objects (`bird.ts`, `pillars.ts`, `background.ts`, `baseElement.ts`)
     - presentation overlays (`menu.ts`, `gameover.ts`, `counter.ts`)
     - effects/services (`audioController.ts`)
   - This makes the architecture easy to diagram as a central game coordinator surrounded by specialized subsystems.

12. **Operational context**
   - The `.github/workflows/ci.yml` file indicates automated CI for the project.
   - The app is intended to be deployed as a static front-end bundle, with assets served from `public/` and bundled source from `src/`.

13. **What to emphasize in an architecture diagram**
   - Put `game.ts` at the center.
   - Show `main.ts` as the bootstrap entry into the game.
   - Show `bird`, `pillars`, and `background` as gameplay/rendering components feeding into the central loop.
   - Show `menu`, `gameover`, `counter`, and `score` as UI/state overlays driven by `gameStatus`.
   - Show `audioController` as an event-driven side service triggered by collisions, jumps, scoring, and death.

Main entry points: [`src/game.ts`](https://github.com/zzz1220/threejs-flappybird/blob/master/src/game.ts) (Game loop), [`src/audioController.ts`](https://github.com/zzz1220/threejs-flappybird/blob/master/src/audioController.ts) (Audio), [`src/bird.ts`](https://github.com/zzz1220/threejs-flappybird/blob/master/src/bird.ts) (Bird), [`src/pillars.ts`](https://github.com/zzz1220/threejs-flappybird/blob/master/src/pillars.ts) (Pillars)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_bootstrap["Bootstrap & build"]
  node_node_index_html["Entry page<br/>html entry<br/>[index.html]"]
  node_node_main_ts["Bootstrap<br/>app entry<br/>[main.ts]"]
  node_node_vite_config["Vite config<br/>build config<br/>[vite.config.js]"]
end

subgraph group_group_core["Game core"]
  node_node_game_ts["Game loop<br/>orchestrator<br/>[game.ts]"]
  node_node_status_ts(("Game status<br/>state model<br/>[gameStatus.ts]"))
  node_node_constant_ts["Constants<br/>shared config<br/>[constant.ts]"]
end

subgraph group_group_world["World & actors"]
  node_node_bird_ts(("Bird<br/>player actor<br/>[bird.ts]"))
  node_node_pillars_ts["Pillars<br/>obstacles<br/>[pillars.ts]"]
  node_node_background_ts["Background<br/>scene layer<br/>[background.ts]"]
  node_node_base_element_ts["Base element<br/>shared actor base<br/>[baseElement.ts]"]
end

subgraph group_group_ui["UI & flow"]
  node_node_menu_ts["Menu<br/>start screen<br/>[menu.ts]"]
  node_node_gameover_ts["Game over<br/>end screen<br/>[gameover.ts]"]
  node_node_counter_ts["Counter<br/>score display<br/>[counter.ts]"]
  node_node_score_ts["Score<br/>scoring<br/>[score.ts]"]
end

subgraph group_group_services["Services"]
  node_node_audio_ts["Audio<br/>sound manager<br/>[audioController.ts]"]
end

subgraph group_group_assets["Static assets"]
  node_node_sprites[("Sprites<br/>static assets")]
  node_node_audio_assets[("Audio assets<br/>static assets")]
end

node_node_index_html -->|"loads"| node_node_main_ts
node_node_main_ts -->|"starts"| node_node_game_ts
node_node_game_ts -->|"drives"| node_node_status_ts
node_node_game_ts -->|"uses"| node_node_constant_ts
node_node_game_ts -->|"updates"| node_node_bird_ts
node_node_game_ts -->|"updates"| node_node_pillars_ts
node_node_game_ts -->|"updates"| node_node_background_ts
node_node_game_ts -->|"shows"| node_node_menu_ts
node_node_game_ts -->|"shows"| node_node_gameover_ts
node_node_game_ts -->|"updates"| node_node_counter_ts
node_node_game_ts -->|"tracks"| node_node_score_ts
node_node_game_ts -->|"triggers"| node_node_audio_ts
node_node_bird_ts -->|"extends"| node_node_base_element_ts
node_node_pillars_ts -->|"extends"| node_node_base_element_ts
node_node_background_ts -->|"extends"| node_node_base_element_ts
node_node_bird_ts -->|"collides with"| node_node_pillars_ts
node_node_bird_ts -->|"causes"| node_node_audio_ts
node_node_score_ts -->|"causes"| node_node_audio_ts
node_node_gameover_ts -->|"causes"| node_node_audio_ts
node_node_audio_ts -->|"plays"| node_node_audio_assets
node_node_game_ts -->|"renders"| node_node_sprites

click node_node_index_html "https://github.com/zzz1220/threejs-flappybird/blob/master/index.html"
click node_node_main_ts "https://github.com/zzz1220/threejs-flappybird/blob/master/src/main.ts"
click node_node_vite_config "https://github.com/zzz1220/threejs-flappybird/blob/master/vite.config.js"
click node_node_game_ts "https://github.com/zzz1220/threejs-flappybird/blob/master/src/game.ts"
click node_node_status_ts "https://github.com/zzz1220/threejs-flappybird/blob/master/src/gameStatus.ts"
click node_node_constant_ts "https://github.com/zzz1220/threejs-flappybird/blob/master/src/constant.ts"
click node_node_bird_ts "https://github.com/zzz1220/threejs-flappybird/blob/master/src/bird.ts"
click node_node_pillars_ts "https://github.com/zzz1220/threejs-flappybird/blob/master/src/pillars.ts"
click node_node_background_ts "https://github.com/zzz1220/threejs-flappybird/blob/master/src/background.ts"
click node_node_base_element_ts "https://github.com/zzz1220/threejs-flappybird/blob/master/src/baseElement.ts"
click node_node_menu_ts "https://github.com/zzz1220/threejs-flappybird/blob/master/src/menu.ts"
click node_node_gameover_ts "https://github.com/zzz1220/threejs-flappybird/blob/master/src/gameover.ts"
click node_node_counter_ts "https://github.com/zzz1220/threejs-flappybird/blob/master/src/counter.ts"
click node_node_score_ts "https://github.com/zzz1220/threejs-flappybird/blob/master/src/score.ts"
click node_node_audio_ts "https://github.com/zzz1220/threejs-flappybird/blob/master/src/audioController.ts"
click node_node_sprites "https://github.com/zzz1220/threejs-flappybird/tree/master/public/sprites"
click node_node_audio_assets "https://github.com/zzz1220/threejs-flappybird/tree/master/public/audio"

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_node_index_html,node_node_main_ts,node_node_vite_config toneBlue
class node_node_game_ts,node_node_status_ts,node_node_constant_ts toneAmber
class node_node_bird_ts,node_node_pillars_ts,node_node_background_ts,node_node_base_element_ts toneMint
class node_node_menu_ts,node_node_gameover_ts,node_node_counter_ts,node_node_score_ts toneRose
class node_node_audio_ts toneIndigo
class node_node_sprites,node_node_audio_assets toneTeal
```

## Components

### Bootstrap & build

Browser entry and project build boundary.

- [Entry page](https://github.com/zzz1220/threejs-flappybird/blob/master/index.html): html entry · Browser document that loads the bundled game. · `index.html`
- [Bootstrap](https://github.com/zzz1220/threejs-flappybird/blob/master/src/main.ts): app entry · Starts the game from the browser entry point. · `src/main.ts`
- [Vite config](https://github.com/zzz1220/threejs-flappybird/blob/master/vite.config.js): build config · Development and bundle configuration for the app. · `vite.config.js`

### Game core

Central orchestration, state, and shared constants.

- [Game loop](https://github.com/zzz1220/threejs-flappybird/blob/master/src/game.ts): orchestrator · Owns scene setup, update flow, and runtime coordination. · `src/game.ts`
- [Game status](https://github.com/zzz1220/threejs-flappybird/blob/master/src/gameStatus.ts): state model · Defines the high-level play phases and transitions. · `src/gameStatus.ts`
- [Constants](https://github.com/zzz1220/threejs-flappybird/blob/master/src/constant.ts): shared config · Centralized gameplay and layout values. · `src/constant.ts`

### World & actors

Playfield entities and shared object abstractions.

- [Bird](https://github.com/zzz1220/threejs-flappybird/blob/master/src/bird.ts): player actor · Player-controlled moving character. · `src/bird.ts`
- [Pillars](https://github.com/zzz1220/threejs-flappybird/blob/master/src/pillars.ts): obstacles · Scrolling obstacle system and collision boundary. · `src/pillars.ts`
- [Background](https://github.com/zzz1220/threejs-flappybird/blob/master/src/background.ts): scene layer · Decorative environment layer for the playfield. · `src/background.ts`
- [Base element](https://github.com/zzz1220/threejs-flappybird/blob/master/src/baseElement.ts): shared actor base · Common abstraction for positioned or movable world objects. · `src/baseElement.ts`

### UI & flow

Menus, score presentation, and end-state screens.

- [Menu](https://github.com/zzz1220/threejs-flappybird/blob/master/src/menu.ts): start screen · Pre-game screen and start flow. · `src/menu.ts`
- [Game over](https://github.com/zzz1220/threejs-flappybird/blob/master/src/gameover.ts): end screen · Post-loss screen and restart flow. · `src/gameover.ts`
- [Counter](https://github.com/zzz1220/threejs-flappybird/blob/master/src/counter.ts): score display · On-screen score presentation and updates. · `src/counter.ts`
- [Score](https://github.com/zzz1220/threejs-flappybird/blob/master/src/score.ts): scoring · Tracks points earned during play. · `src/score.ts`

### Services

Cross-cutting runtime services such as audio.

- [Audio](https://github.com/zzz1220/threejs-flappybird/blob/master/src/audioController.ts): sound manager · Plays sound effects for gameplay events. · `src/audioController.ts`

### Static assets

Runtime-served asset directories.

- [Sprites](https://github.com/zzz1220/threejs-flappybird/tree/master/public/sprites): static assets · Runtime sprite assets served directly by Vite. · `public/sprites`
- [Audio assets](https://github.com/zzz1220/threejs-flappybird/tree/master/public/audio): static assets · Runtime sound files for wing, hit, point, swoosh, and die. · `public/audio`

## Connections

- Entry page → Bootstrap: loads · The browser document loads the application bootstrap.
- Bootstrap → Game loop: starts · Bootstrap creates the game orchestrator and begins play.
- Game loop → Game status: drives · The loop reads and updates the current game phase.
- Game loop → Constants: uses · Core gameplay values are sourced from shared constants.
- Game loop → Bird: updates · The orchestrator advances the player actor.
- Game loop → Pillars: updates · The orchestrator advances obstacle generation and motion.
- Game loop → Background: updates · The orchestrator keeps the scene layers in sync.
- Game loop → Menu: shows · Menu flow is activated before active gameplay.
- Game loop → Game over: shows · Game-over flow is activated after a loss.
- Game loop → Counter: updates · Visible score is refreshed from gameplay state.
- Game loop → Score: tracks · Score changes are coordinated by the central loop.
- Game loop → Audio: triggers · Gameplay events emit sound effects through the audio service.
- Bird → Base element: extends · The player actor builds on the shared element abstraction.
- Pillars → Base element: extends · Obstacles reuse the shared world-object base.
- Background → Base element: extends · Background elements reuse the shared world-object base.
- Bird → Pillars: collides with · Player movement is checked against obstacle geometry.
- Bird → Audio: causes · Jumps and collisions can emit sound effects.
- Score → Audio: causes · Point events can trigger the scoring sound.
- Game over → Audio: causes · Loss flow can trigger hit or die sounds.
- Audio → Audio assets: plays · The sound manager uses the bundled runtime audio files.
- Game loop → Sprites: renders · Visual entities rely on sprite assets at runtime.
