# mathuska/ship-game architecture

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

- Interactive diagram: https://gitdiagram.com/mathuska/ship-game
- Repository: https://github.com/mathuska/ship-game

## Overview

This is a browser-based, Three.js arcade game: players rotate to landscape, then control a ship through a 3D world containing generated obstacles and asteroid fields, with score and game-state controls. The graph follows the app-to-game entry and the documented component references; sampled code confirms the obstacle generation and asteroid behavior. Several visual components and game features are only indexed, not excerpted, so their internal behavior and some connections are omitted.

Main entry points: [`src/components/game2/Obstacles.tsx`](https://github.com/mathuska/ship-game/blob/main/src/components/game2/Obstacles.tsx) (Obstacle generation), [`src/stores/useGameStore.ts`](https://github.com/mathuska/ship-game/blob/main/src/stores/useGameStore.ts) (Game state), [`src/games/Game2.tsx`](https://github.com/mathuska/ship-game/blob/main/src/games/Game2.tsx) (Game scene and HUD), [`src/components/game2/World.tsx`](https://github.com/mathuska/ship-game/blob/main/src/components/game2/World.tsx) (World composition)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["App and game"]
  node_app["Orientation gate<br/>[App.tsx]"]
  node_telegram["Telegram wrapper<br/>[TelegramWebApp.tsx]"]
  node_game["Game scene and HUD<br/>[Game2.tsx]"]
end

subgraph group_world["3D world"]
  node_world["World composition<br/>[World.tsx]"]
  node_floor["Scrolling floor<br/>[Floor.tsx]"]
  node_obstacles["Obstacle generation<br/>[Obstacles.tsx]"]
  node_box["Box obstacle<br/>[Box.tsx]"]
  node_cylinder["Cylinder obstacle<br/>[Cylinder.tsx]"]
  node_instances["Obstacle instances"]
  node_asteroidfield["Asteroid field<br/>[AsteroidField.tsx]"]
  node_asteroids["Asteroid models<br/>[Aster2_5.tsx]"]
  node_otherasteroids["Asteroid variants<br/>[Aster2-1.tsx]"]
  node_stars["Custom stars<br/>[CustomStars.tsx]"]
  node_collectibles["Collectibles<br/>[Collectibles.tsx]"]
end

subgraph group_motion["Gameplay and controls"]
  node_ship["Player ship<br/>[Ship1.tsx]"]
  node_camera["Camera follow"]
  node_orientation["Device orientation"]
  node_asteroidlogic["Asteroid motion"]
  node_randomasteroid["Procedural asteroid<br/>[RandomAsteroid.tsx]"]
  node_noise["Perlin noise<br/>[perlin-noise.ts]"]
end

subgraph group_state["State and generation"]
  node_gamestore["Game state<br/>[useGameStore.ts]"]
  node_settings["Game settings"]
  node_generation["Generation logic"]
  node_random["Random range"]
end

node_player(("Player"))

node_player -->|"opens"| node_app
node_app -->|"wraps"| node_telegram
node_app -->|"renders"| node_game
node_game -->|"renders"| node_ship
node_game -->|"renders"| node_camera
node_game -->|"renders"| node_world
node_game -->|"reads and updates"| node_gamestore
node_world -->|"renders"| node_floor
node_world -->|"renders"| node_obstacles
node_world -->|"renders"| node_asteroidfield
node_world -->|"renders"| node_stars
node_obstacles -->|"renders"| node_box
node_obstacles -->|"renders"| node_cylinder
node_obstacles -->|"generates with"| node_generation
node_obstacles -->|"stores references"| node_gamestore
node_obstacles -->|"reads"| node_settings
node_asteroidfield -->|"generates with"| node_generation
node_asteroidfield -->|"renders"| node_asteroids
node_asteroidfield -->|"renders"| node_otherasteroids
node_ship -->|"reads input"| node_orientation
node_ship -->|"uses state"| node_gamestore
node_camera -->|"reads ship reference"| node_gamestore
node_asteroids -->|"uses"| node_asteroidlogic
node_asteroidlogic -->|"reads and updates"| node_gamestore
node_asteroidlogic -->|"reads"| node_settings
node_asteroidlogic -->|"samples range"| node_random
node_generation -->|"reads"| node_settings
node_generation -->|"samples range"| node_random
node_randomasteroid -->|"uses"| node_noise
node_randomasteroid -->|"uses state"| node_gamestore

click node_app "https://github.com/mathuska/ship-game/blob/main/src/App.tsx"
click node_telegram "https://github.com/mathuska/ship-game/blob/main/src/components/TelegramWebApp.tsx"
click node_game "https://github.com/mathuska/ship-game/blob/main/src/games/Game2.tsx"
click node_world "https://github.com/mathuska/ship-game/blob/main/src/components/game2/World.tsx"
click node_floor "https://github.com/mathuska/ship-game/blob/main/src/components/game2/Floor.tsx"
click node_obstacles "https://github.com/mathuska/ship-game/blob/main/src/components/game2/Obstacles.tsx"
click node_box "https://github.com/mathuska/ship-game/blob/main/src/components/game2/obstacles/Box.tsx"
click node_cylinder "https://github.com/mathuska/ship-game/blob/main/src/components/game2/obstacles/Cylinder.tsx"
click node_instances "https://github.com/mathuska/ship-game/blob/main/src/components/game2/obstacles/ObstacleInstances.tsx"
click node_asteroidfield "https://github.com/mathuska/ship-game/blob/main/src/components/AsteroidField.tsx"
click node_asteroids "https://github.com/mathuska/ship-game/blob/main/src/objects/Aster2_5.tsx"
click node_otherasteroids "https://github.com/mathuska/ship-game/blob/main/src/objects/Aster2-1.tsx"
click node_stars "https://github.com/mathuska/ship-game/blob/main/src/components/game2/CustomStars.tsx"
click node_collectibles "https://github.com/mathuska/ship-game/blob/main/src/components/game2/Collectibles.tsx"
click node_ship "https://github.com/mathuska/ship-game/blob/main/src/ships/Ship1.tsx"
click node_camera "https://github.com/mathuska/ship-game/blob/main/src/components/CameraController.tsx"
click node_orientation "https://github.com/mathuska/ship-game/blob/main/src/hooks/useDeviceOrientation.tsx"
click node_asteroidlogic "https://github.com/mathuska/ship-game/blob/main/src/hooks/useAsteroidLogic.tsx"
click node_randomasteroid "https://github.com/mathuska/ship-game/blob/main/src/components/RandomAsteroid.tsx"
click node_noise "https://github.com/mathuska/ship-game/blob/main/src/lib/perlin-noise.ts"
click node_gamestore "https://github.com/mathuska/ship-game/blob/main/src/stores/useGameStore.ts"
click node_settings "https://github.com/mathuska/ship-game/blob/main/src/stores/useSettingsStore.ts"
click node_generation "https://github.com/mathuska/ship-game/blob/main/src/hooks/useGenerateLogic.tsx"
click node_random "https://github.com/mathuska/ship-game/blob/main/src/utils/getRandomInRange.ts"

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_app,node_telegram,node_game toneBlue
class node_world,node_floor,node_obstacles,node_box,node_cylinder,node_instances,node_asteroidfield,node_asteroids,node_otherasteroids,node_stars,node_collectibles toneAmber
class node_ship,node_camera,node_orientation,node_asteroidlogic,node_randomasteroid,node_noise toneMint
class node_gamestore,node_settings,node_generation,node_random toneRose
class node_player toneIndigo
```

## Components

### App and game

- [Orientation gate](https://github.com/mathuska/ship-game/blob/main/src/App.tsx): `src/App.tsx`
- [Telegram wrapper](https://github.com/mathuska/ship-game/blob/main/src/components/TelegramWebApp.tsx): `src/components/TelegramWebApp.tsx`
- [Game scene and HUD](https://github.com/mathuska/ship-game/blob/main/src/games/Game2.tsx): `src/games/Game2.tsx`

### 3D world

- [World composition](https://github.com/mathuska/ship-game/blob/main/src/components/game2/World.tsx): `src/components/game2/World.tsx`
- [Scrolling floor](https://github.com/mathuska/ship-game/blob/main/src/components/game2/Floor.tsx): `src/components/game2/Floor.tsx`
- [Obstacle generation](https://github.com/mathuska/ship-game/blob/main/src/components/game2/Obstacles.tsx): `src/components/game2/Obstacles.tsx`
- [Box obstacle](https://github.com/mathuska/ship-game/blob/main/src/components/game2/obstacles/Box.tsx): `src/components/game2/obstacles/Box.tsx`
- [Cylinder obstacle](https://github.com/mathuska/ship-game/blob/main/src/components/game2/obstacles/Cylinder.tsx): `src/components/game2/obstacles/Cylinder.tsx`
- [Obstacle instances](https://github.com/mathuska/ship-game/blob/main/src/components/game2/obstacles/ObstacleInstances.tsx): `src/components/game2/obstacles/ObstacleInstances.tsx`
- [Asteroid field](https://github.com/mathuska/ship-game/blob/main/src/components/AsteroidField.tsx): `src/components/AsteroidField.tsx`
- [Asteroid models](https://github.com/mathuska/ship-game/blob/main/src/objects/Aster2_5.tsx): `src/objects/Aster2_5.tsx`
- [Asteroid variants](https://github.com/mathuska/ship-game/blob/main/src/objects/Aster2-1.tsx): `src/objects/Aster2-1.tsx`
- [Custom stars](https://github.com/mathuska/ship-game/blob/main/src/components/game2/CustomStars.tsx): `src/components/game2/CustomStars.tsx`
- [Collectibles](https://github.com/mathuska/ship-game/blob/main/src/components/game2/Collectibles.tsx): `src/components/game2/Collectibles.tsx`

### Gameplay and controls

- [Player ship](https://github.com/mathuska/ship-game/blob/main/src/ships/Ship1.tsx): `src/ships/Ship1.tsx`
- [Camera follow](https://github.com/mathuska/ship-game/blob/main/src/components/CameraController.tsx): `src/components/CameraController.tsx`
- [Device orientation](https://github.com/mathuska/ship-game/blob/main/src/hooks/useDeviceOrientation.tsx): `src/hooks/useDeviceOrientation.tsx`
- [Asteroid motion](https://github.com/mathuska/ship-game/blob/main/src/hooks/useAsteroidLogic.tsx): `src/hooks/useAsteroidLogic.tsx`
- [Procedural asteroid](https://github.com/mathuska/ship-game/blob/main/src/components/RandomAsteroid.tsx): `src/components/RandomAsteroid.tsx`
- [Perlin noise](https://github.com/mathuska/ship-game/blob/main/src/lib/perlin-noise.ts): `src/lib/perlin-noise.ts`

### State and generation

- [Game state](https://github.com/mathuska/ship-game/blob/main/src/stores/useGameStore.ts): `src/stores/useGameStore.ts`
- [Game settings](https://github.com/mathuska/ship-game/blob/main/src/stores/useSettingsStore.ts): `src/stores/useSettingsStore.ts`
- [Generation logic](https://github.com/mathuska/ship-game/blob/main/src/hooks/useGenerateLogic.tsx): `src/hooks/useGenerateLogic.tsx`
- [Random range](https://github.com/mathuska/ship-game/blob/main/src/utils/getRandomInRange.ts): `src/utils/getRandomInRange.ts`

### Other components

- **Player**

## Connections

- Player → Orientation gate: opens
- Orientation gate → Telegram wrapper: wraps (evidence: `src/App.tsx`)
- Orientation gate → Game scene and HUD: renders (evidence: `src/App.tsx`)
- Game scene and HUD → Player ship: renders (evidence: `src/games/Game2.tsx`)
- Game scene and HUD → Camera follow: renders (evidence: `src/games/Game2.tsx`)
- Game scene and HUD → World composition: renders (evidence: `src/games/Game2.tsx`)
- Game scene and HUD → Game state: reads and updates (evidence: `src/games/Game2.tsx`)
- World composition → Scrolling floor: renders (evidence: `src/components/game2/World.tsx`)
- World composition → Obstacle generation: renders (evidence: `src/components/game2/World.tsx`)
- World composition → Asteroid field: renders (evidence: `src/components/game2/World.tsx`)
- World composition → Custom stars: renders (evidence: `src/components/game2/World.tsx`)
- Obstacle generation → Box obstacle: renders (evidence: `src/components/game2/Obstacles.tsx`)
- Obstacle generation → Cylinder obstacle: renders (evidence: `src/components/game2/Obstacles.tsx`)
- Obstacle generation → Generation logic: generates with (evidence: `src/components/game2/Obstacles.tsx`)
- Obstacle generation → Game state: stores references (evidence: `src/components/game2/Obstacles.tsx`)
- Obstacle generation → Game settings: reads (evidence: `src/components/game2/Obstacles.tsx`)
- Asteroid field → Generation logic: generates with (evidence: `src/components/AsteroidField.tsx`)
- Asteroid field → Asteroid models: renders (evidence: `src/components/AsteroidField.tsx`)
- Asteroid field → Asteroid variants: renders (evidence: `src/components/AsteroidField.tsx`)
- Player ship → Device orientation: reads input (evidence: `src/ships/Ship1.tsx`)
- Player ship → Game state: uses state (evidence: `src/ships/Ship1.tsx`)
- Camera follow → Game state: reads ship reference (evidence: `src/components/CameraController.tsx`)
- Asteroid models → Asteroid motion: uses (evidence: `src/objects/Aster2_5.tsx`)
- Asteroid motion → Game state: reads and updates (evidence: `src/hooks/useAsteroidLogic.tsx`)
- Asteroid motion → Game settings: reads (evidence: `src/hooks/useAsteroidLogic.tsx`)
- Asteroid motion → Random range: samples range (evidence: `src/hooks/useAsteroidLogic.tsx`)
- Generation logic → Game settings: reads (evidence: `src/hooks/useGenerateLogic.tsx`)
- Generation logic → Random range: samples range (evidence: `src/hooks/useGenerateLogic.tsx`)
- Procedural asteroid → Perlin noise: uses (evidence: `src/components/RandomAsteroid.tsx`)
- Procedural asteroid → Game state: uses state (evidence: `src/components/RandomAsteroid.tsx`)
