How zzz1220/threejs-flappybird works
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: game.ts Game loop · audioController.ts Audio · bird.ts Bird · pillars.ts Pillars
Components 17
Bootstrap & build
Browser entry and project build boundary.
- Entry page · Browser document that loads the bundled game.
index.html - Bootstrap · Starts the game from the browser entry point.
src/main.ts - Vite config · Development and bundle configuration for the app.
vite.config.js
Game core
Central orchestration, state, and shared constants.
- Game loop · Owns scene setup, update flow, and runtime coordination.
src/game.ts - Game status · Defines the high-level play phases and transitions.
src/gameStatus.ts - Constants · Centralized gameplay and layout values.
src/constant.ts
World & actors
Playfield entities and shared object abstractions.
- Bird · Player-controlled moving character.
src/bird.ts - Pillars · Scrolling obstacle system and collision boundary.
src/pillars.ts - Background · Decorative environment layer for the playfield.
src/background.ts - Base element · Common abstraction for positioned or movable world objects.
src/baseElement.ts
UI & flow
Menus, score presentation, and end-state screens.
Services
Cross-cutting runtime services such as audio.
- Audio · Plays sound effects for gameplay events.
src/audioController.ts
Static assets
Runtime-served asset directories.
- Sprites · Runtime sprite assets served directly by Vite.
public/sprites - Audio assets · Runtime sound files for wing, hit, point, swoosh, and die.
public/audio
Connections 21
- 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.