# perhapseb/chromajump architecture

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

- Interactive diagram: https://gitdiagram.com/perhapseb/chromajump
- Repository: https://github.com/perhapseb/chromajump

## Overview

##### Project type & purpose (from README + file tree)
This project is a **static, browser-delivered 2D pixel-art platformer** (“ChromaJump”) built with **p5play** (game framework on top of p5-style rendering/physics/sprites) and **q5.js** (rendering/utility). It’s intended to run on **GitHub Pages** (link in README), so there’s **no backend**; everything is client-side.

From the tree:
- `index.html`, `style.css`, `sketch.js` → classic single-page p5/p5play-style game structure (HTML host, CSS page styling, JS “sketch” containing game loop).
- `Images/`, `Spritesheets/`, `Sounds/`, `Music/` → packaged game assets.
- No bundler/config (`package.json`, `vite`, etc.) → likely CDN script tags and direct asset loading.

##### File-structure-to-architecture mapping (what each folder “means”
Top-level components implied by the structure:

##### Runtime / app shell
- **`index.html`**
Entry point. Loads libraries (p5play/q5.js), loads `sketch.js`, links `style.css`, defines canvas container.
- **`style.css`**
Presentation around the canvas (page layout, maybe scaling / centering).
- **`sketch.js`**
The “game executable”: initialization, main loop, scene/level logic, collision rules, lens switching, UI, and asset references.

##### Assets (immutable content)
- **`Images/`** (including `Images/Parallax/`)
Backgrounds, parallax layers, UI images, etc.
- **`Spritesheets/`**
Animated sprite atlases for player/enemies/platforms.
- **`Sounds/`** and **`Music/`**
SFX and ambient music.

##### What to infer from the README (key gameplay modules to show)
The README describes a core mechanic:
- **Lens system (Red/Green/Blue)**: platforms are visible/active only when the current lens matches.
- **Progression**: lenses unlock over time; levels get harder.
- **Input**: keyboard + gamepad support.

##### Browser ← GitHub Pages: returns HTML
4. **Browser → GitHub Pages**: GET `style.css`, `sketch.js`, library scripts, and assets on demand
##### index.html → (loads) `sketch.js` + libs

**Runtime initialization**
##### Game Runtime → Engine (p5play/q5): initialize canvas, sprites, physics world

**Per-frame gameplay loop**
##### Physics/Collision → Player/Entities: resolves collisions & triggers events
11. **Events (jump, land, lens swap, level complete) → Audio Manager → WebAudio** (plays SFX/BGM)
12. **Game Loop → Renderer (q5/p5play) → Canvas**: draws current frame (including parallax layers)

**Progression**

##### Architectural patterns / principles (what’s important here)
Even in a single JS file, this kind of p5play game usually follows:

- **State machine / scene management**: menu → level → win/lose → next level.
- **Client-only deployment**: no server logic; all content shipped as static assets.

- The **lens mechanic** as a controller that affects both **rendering** (visible) and **physics/collision** (solid/interactive).
- The **asset pipeline** (preload + runtime use), because asset folders dominate the project structure.

##### Relevant technologies & frameworks (explicitly
- Browser APIs: **Canvas**, **WebAudio**, **Gamepad**, **Keyboard**
- Frameworks: **p5play**, **q5.js**
- Hosting: **GitHub Pages**
- Asset formats: `.mp3`, `.wav`, sprite sheets (PNG/WebP depending on your assets)

##### “Don’t overthink it”: maximal component separation that still matches reality
- Bootstrapping
- Asset loading
- Input mapping (keyboard + gamepad)
- Level/scene management
- Entity + physics + collisions
- Rendering (including parallax)
- Audio (music + SFX)

That’s the “as many components as possible” breakdown that remains accurate to this project’s purpose and structure.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =======================
  %% Context / Hosting Layer
  %% =======================
  User([Player]):::external

  subgraph "Static Hosting (No Backend)"
    GH[("GitHub Pages\n(static file host)")]:::hosting
    Readme["README\n(overview & mechanics)"]:::doc
  end

  subgraph "Client Platform"
    Browser["Web Browser"]:::external

    subgraph "Browser APIs"
      Canvas{{Canvas API}}:::browserapi
      WebAudio{{WebAudio API}}:::browserapi
      Gamepad{{Gamepad API}}:::browserapi
      Keyboard{{Keyboard API}}:::browserapi
    end
  end

  %% =======================
  %% App Shell
  %% =======================
  subgraph "App Shell (Single Page)"
    HTML["index.html\n(entry point)"]:::app
    CSS["style.css\n(layout/styling)"]:::app
  end

  %% =======================
  %% Libraries
  %% =======================
  subgraph "3rd-Party Libraries (via script includes)"
    Q5["q5.js\n(rendering/util)"]:::lib
    P5P["p5play\n(sprites/physics)"]:::lib
  end

  %% =======================
  %% Game Runtime
  %% =======================
  subgraph "Game Runtime (sketch.js)"
    Sketch["sketch.js\n(game executable)"]:::runtime

    subgraph "Core Loop"
      Loop["Game Loop / Engine Adapter\nsetup() + draw()"]:::runtime
      Render["Renderer\n(draw pass)"]:::runtime
      Update["Update Tick\n(per-frame state)"]:::runtime
    end

    subgraph "Gameplay Systems"
      Assets["Asset Loader\n(preload & cache)"]:::runtime
      Levels["Scene / Level Manager\n(progress & transitions)"]:::runtime
      Lens["Lens / Color-State Controller\n(R/G/B + unlocks)"]:::runtime
      Input["Input Manager\n(keyboard + gamepad)"]:::runtime
      Entities["Entity System\n(player/platforms/hazards/goal)"]:::runtime
      Physics["Physics / Collision\n(p5play world)"]:::runtime
      Audio["Audio Manager\n(BGM + SFX)"]:::runtime
      Parallax["Parallax Background System"]:::runtime
    end
  end

  %% =======================
  %% Asset Bundle
  %% =======================
  subgraph "Asset Bundle (Static Content)"
    Images[("Images/")]:::asset
    ParallaxDir[("Images/Parallax/")]:::asset
    Sprites[("Spritesheets/")]:::asset

    Sounds[("Sounds/")]:::asset
    LensSwap["LensSwap.wav"]:::assetfile
    LensUnlock["LensUnlock.mp3"]:::assetfile
    LevelComplete["LevelComplete.mp3"]:::assetfile
    Thud["Thud.mp3"]:::assetfile

    Music[("Music/")]:::asset
    Ambience["Ambience.mp3"]:::assetfile
  end

  %% =======================
  %% Legend
  %% =======================
  subgraph "Legend"
    L1["Runtime code component"]:::runtime
    L2["External library"]:::lib
    L3["Browser API"]:::browserapi
    L4[("Asset store/bundle")]:::asset
    L5["Static host"]:::hosting
  end

  %% =======================
  %% Connections (Delivery / Boot)
  %% =======================
  User -->|navigate| Browser
  Browser -.->|GET index.html| GH
  GH -.->|serve| HTML
  Browser -.->|GET style.css| GH
  GH -.->|serve| CSS
  Browser -.->|GET sketch.js| GH
  GH -.->|serve| Sketch
  Browser -.->|GET README docs| GH
  GH -.->|serve| Readme

  HTML -->|loads| CSS
  HTML -->|loads| Sketch
  HTML -.->|loads libraries| Q5
  HTML -.->|loads libraries| P5P

  %% =======================
  %% Runtime initialization & per-frame loop
  %% =======================
  Sketch -->|initializes| Loop
  Loop -->|calls per frame| Update
  Loop -->|calls per frame| Render

  Update -->|preload/startup| Assets
  Assets -->|fetch images| Images
  Assets -->|fetch parallax layers| ParallaxDir
  Assets -->|fetch spritesheets| Sprites
  Assets -->|fetch sfx| Sounds
  Assets -->|fetch bgm| Music

  Update -->|updates| Levels
  Update -->|updates| Input
  Update -->|updates| Lens
  Update -->|updates| Entities
  Entities -->|uses| Physics
  Physics -->|collision callbacks| Entities

  Lens -->|visibility/solidity rules| Entities
  Lens -->|gates platforms| Physics

  Input -->|keyboard events| Keyboard
  Input -->|gamepad events| Gamepad
  Input -->|controls| Entities

  Render -->|draw sprites| P5P
  Render -->|draw backgrounds| Parallax
  Parallax -->|uses layers| ParallaxDir
  Render -->|draw calls| Q5
  Render -->|present frame| Canvas

  Audio -->|playback| WebAudio
  Levels -->|level complete event| Audio
  Input -->|lens swap event| Audio
  Lens -->|lens unlock event| Audio
  Physics -->|impact/land event| Audio

  Audio -->|uses| Ambience
  Audio -->|uses| LensSwap
  Audio -->|uses| LensUnlock
  Audio -->|uses| LevelComplete
  Audio -->|uses| Thud

  %% =======================
  %% Click Events (mapped paths)
  %% =======================
  click HTML "https://github.com/perhapseb/chromajump/blob/main/index.html"
  click CSS "https://github.com/perhapseb/chromajump/blob/main/style.css"
  click Sketch "https://github.com/perhapseb/chromajump/blob/main/sketch.js"

  click Images "https://github.com/perhapseb/chromajump/tree/main/Images/"
  click ParallaxDir "https://github.com/perhapseb/chromajump/tree/main/Images/Parallax/"
  click Sprites "https://github.com/perhapseb/chromajump/tree/main/Spritesheets/"

  click Sounds "https://github.com/perhapseb/chromajump/tree/main/Sounds/"
  click LensSwap "https://github.com/perhapseb/chromajump/blob/main/Sounds/LensSwap.wav"
  click LensUnlock "https://github.com/perhapseb/chromajump/blob/main/Sounds/LensUnlock.mp3"
  click LevelComplete "https://github.com/perhapseb/chromajump/blob/main/Sounds/LevelComplete.mp3"
  click Thud "https://github.com/perhapseb/chromajump/blob/main/Sounds/Thud.mp3"

  click Music "https://github.com/perhapseb/chromajump/tree/main/Music/"
  click Ambience "https://github.com/perhapseb/chromajump/blob/main/Music/Ambience.mp3"

  click Readme "https://github.com/perhapseb/chromajump/blob/main/README.md"

  %% =======================
  %% Styles
  %% =======================
  classDef external fill:#ffffff,stroke:#334155,stroke-width:1.5px,color:#0f172a
  classDef hosting fill:#ede9fe,stroke:#6d28d9,stroke-width:2px,color:#2e1065
  classDef app fill:#dbeafe,stroke:#2563eb,stroke-width:2px,color:#0b1b3a
  classDef runtime fill:#bfdbfe,stroke:#1d4ed8,stroke-width:2px,color:#0b1b3a
  classDef lib fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#052e16
  classDef browserapi fill:#ffedd5,stroke:#f97316,stroke-width:2px,color:#431407
  classDef asset fill:#e5e7eb,stroke:#6b7280,stroke-width:2px,color:#111827
  classDef assetfile fill:#f3f4f6,stroke:#6b7280,stroke-width:1.5px,color:#111827
  classDef doc fill:#fef9c3,stroke:#ca8a04,stroke-width:2px,color:#422006
```
