# hcoder10/blocksfield architecture

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

- Interactive diagram: https://gitdiagram.com/hcoder10/blocksfield
- Repository: https://github.com/hcoder10/blocksfield

## Overview

Blocksfield turns a game pitch into playable browser games, with a local Studio interface for launching and watching builds. The documented web workflow plans a kit-constrained game, generates its art and audio, scaffolds and builds the game, then playtests, judges, repairs, and finalizes it for the gallery. ThreeKit supplies reusable runtime systems; the site and Studio expose finished games and build progress. The README also documents a Roblox-place target and promotional-video generation, but sampled evidence is insufficient to map those implementations or connect their stages reliably.

Main entry points: [`blocksfield/web_run.py`](https://github.com/hcoder10/blocksfield/blob/main/blocksfield/web_run.py) (Build orchestration), [`web/kit/ui.js`](https://github.com/hcoder10/blocksfield/blob/main/web/kit/ui.js) (Game UI), [`web/kit/look.js`](https://github.com/hcoder10/blocksfield/blob/main/web/kit/look.js) (Visual direction), [`blocksfield/web_assets.py`](https://github.com/hcoder10/blocksfield/blob/main/blocksfield/web_assets.py) (Generated assets)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_pipeline["Web build pipeline"]
  node_plan["Plan and schema<br/>[web_plan.py]"]
  node_webbuild["Build orchestration<br/>[web_run.py]"]
  node_scaffold["Game scaffold<br/>[web_build.py]"]
  node_playtest["Playtest and judge<br/>[web_play.py]"]
  node_gamefiles["Finished game files"]
end

subgraph group_kit["ThreeKit runtime"]
  node_kitgame["ThreeKit game core<br/>[core.js]"]
  node_kitlevel["Level and world<br/>[level.js]"]
  node_kitworld["World building<br/>[world.js]"]
  node_kitlook["Visual direction<br/>[look.js]"]
  node_kitplayer["Player and physics<br/>[player.js]"]
  node_kitphysics["Physics<br/>[physics.js]"]
  node_kitrules["Gameplay rules<br/>[gameplay.js]"]
  node_kitui["Game UI<br/>[ui.js]"]
  node_kitaudio["Game audio<br/>[audio.js]"]
  node_kitcutscene["Cutscenes<br/>[cutscene.js]"]
  node_kitdebug["Debug and survey<br/>[debug.js]"]
end

subgraph group_experience["Play and gallery"]
  node_browserplayer["Browser player<br/>[game.js]"]
  node_gallery["Game gallery<br/>[site.js]"]
  node_indexer["Gallery index<br/>[build_index.py]"]
end

subgraph group_studio["Blocksfield Studio"]
  node_studioapp["Studio server<br/>[studio.py]"]
  node_studiohome["Studio home<br/>[home.js]"]
  node_studiorun["Run monitor<br/>[run.js]"]
  node_studiocommon["Studio UI helpers<br/>[common.js]"]
end

subgraph group_media["Media generation"]
  node_webassets["Generated assets<br/>[web_assets.py]"]
  node_splat["Splat conversion<br/>[splat_to_parts.py]"]
end

node_pitcher(("Game creator"))
node_comfy{{"ComfyUI"}}
node_arbiter{{"GPU arbiter"}}
node_browser(("Web browser"))
node_publisher["Pages publisher<br/>[publish_pages.py]"]

node_pitcher -.->|"submits pitch"| node_webbuild
node_webbuild -.->|"plans game"| node_plan
node_webbuild -.->|"generates assets"| node_webassets
node_webbuild -.->|"scaffolds game"| node_scaffold
node_webbuild -.->|"tests and repairs"| node_playtest
node_webbuild -.->|"finalizes files"| node_gamefiles
node_webassets -.->|"converts splat"| node_splat
node_webassets -.->|"requests generation"| node_comfy
node_webbuild -.->|"coordinates GPU"| node_arbiter
node_scaffold -.->|"composes kit"| node_kitgame
node_kitlevel -->|"builds with"| node_kitworld
node_kitworld -->|"uses palette"| node_kitlook
node_kitlevel -->|"uses look"| node_kitlook
node_kitplayer -.->|"uses physics"| node_kitphysics
node_kitrules -->|"uses player"| node_kitplayer
node_kitui -->|"reports errors"| node_kitgame
node_kitui -->|"uses palette"| node_kitlook
node_kitui -->|"uses audio"| node_kitaudio
node_kitui -->|"uses survey"| node_kitdebug
node_kitlook -.->|"uses cutscenes"| node_kitcutscene
node_playtest -.->|"plays and judges"| node_browser
node_browserplayer -.->|"loads game"| node_gamefiles
node_gallery -.->|"reads listing"| node_indexer
node_pitcher -.->|"enters pitch"| node_studiohome
node_studiohome -.->|"uses app"| node_studioapp
node_studiorun -.->|"fetches run data"| node_studioapp
node_studiorun -->|"uses helpers"| node_studiocommon
node_studioapp -.->|"launches builds"| node_webbuild
node_studiocommon -.->|"shows GPU status"| node_arbiter
node_publisher -->|"rebuilds index"| node_indexer
node_publisher -.->|"publishes site"| node_gallery

click node_plan "https://github.com/hcoder10/blocksfield/blob/main/blocksfield/web_plan.py"
click node_webbuild "https://github.com/hcoder10/blocksfield/blob/main/blocksfield/web_run.py"
click node_webassets "https://github.com/hcoder10/blocksfield/blob/main/blocksfield/web_assets.py"
click node_splat "https://github.com/hcoder10/blocksfield/blob/main/blocksfield/splat_to_parts.py"
click node_scaffold "https://github.com/hcoder10/blocksfield/blob/main/blocksfield/web_build.py"
click node_playtest "https://github.com/hcoder10/blocksfield/blob/main/blocksfield/web_play.py"
click node_gamefiles "https://github.com/hcoder10/blocksfield/tree/main/web/games"
click node_kitgame "https://github.com/hcoder10/blocksfield/blob/main/web/kit/core.js"
click node_kitlevel "https://github.com/hcoder10/blocksfield/blob/main/web/kit/level.js"
click node_kitworld "https://github.com/hcoder10/blocksfield/blob/main/web/kit/world.js"
click node_kitlook "https://github.com/hcoder10/blocksfield/blob/main/web/kit/look.js"
click node_kitplayer "https://github.com/hcoder10/blocksfield/blob/main/web/kit/player.js"
click node_kitphysics "https://github.com/hcoder10/blocksfield/blob/main/web/kit/physics.js"
click node_kitrules "https://github.com/hcoder10/blocksfield/blob/main/web/kit/gameplay.js"
click node_kitui "https://github.com/hcoder10/blocksfield/blob/main/web/kit/ui.js"
click node_kitaudio "https://github.com/hcoder10/blocksfield/blob/main/web/kit/audio.js"
click node_kitcutscene "https://github.com/hcoder10/blocksfield/blob/main/web/kit/cutscene.js"
click node_kitdebug "https://github.com/hcoder10/blocksfield/blob/main/web/kit/debug.js"
click node_browserplayer "https://github.com/hcoder10/blocksfield/blob/main/web/site/js/game.js"
click node_gallery "https://github.com/hcoder10/blocksfield/blob/main/web/site/js/site.js"
click node_indexer "https://github.com/hcoder10/blocksfield/blob/main/web/tools/build_index.py"
click node_studioapp "https://github.com/hcoder10/blocksfield/blob/main/blocksfield/studio.py"
click node_studiohome "https://github.com/hcoder10/blocksfield/blob/main/web/studio/home.js"
click node_studiorun "https://github.com/hcoder10/blocksfield/blob/main/web/studio/run.js"
click node_studiocommon "https://github.com/hcoder10/blocksfield/blob/main/web/studio/common.js"
click node_publisher "https://github.com/hcoder10/blocksfield/blob/main/deploy/publish_pages.py"

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_plan,node_webbuild,node_scaffold,node_playtest,node_gamefiles,node_comfy,node_browser toneBlue
class node_kitgame,node_kitlevel,node_kitworld,node_kitlook,node_kitplayer,node_kitphysics,node_kitrules,node_kitui,node_kitaudio,node_kitcutscene,node_kitdebug toneAmber
class node_browserplayer,node_gallery,node_indexer toneMint
class node_studioapp,node_studiohome,node_studiorun,node_studiocommon toneRose
class node_webassets,node_splat,node_pitcher,node_arbiter toneIndigo
class node_publisher toneTeal
```

## Components

### Web build pipeline

- [Plan and schema](https://github.com/hcoder10/blocksfield/blob/main/blocksfield/web_plan.py): `blocksfield/web_plan.py`
- [Build orchestration](https://github.com/hcoder10/blocksfield/blob/main/blocksfield/web_run.py): `blocksfield/web_run.py`
- [Game scaffold](https://github.com/hcoder10/blocksfield/blob/main/blocksfield/web_build.py): `blocksfield/web_build.py`
- [Playtest and judge](https://github.com/hcoder10/blocksfield/blob/main/blocksfield/web_play.py): `blocksfield/web_play.py`
- [Finished game files](https://github.com/hcoder10/blocksfield/tree/main/web/games): `web/games`

### ThreeKit runtime

- [ThreeKit game core](https://github.com/hcoder10/blocksfield/blob/main/web/kit/core.js): `web/kit/core.js`
- [Level and world](https://github.com/hcoder10/blocksfield/blob/main/web/kit/level.js): `web/kit/level.js`
- [World building](https://github.com/hcoder10/blocksfield/blob/main/web/kit/world.js): `web/kit/world.js`
- [Visual direction](https://github.com/hcoder10/blocksfield/blob/main/web/kit/look.js): `web/kit/look.js`
- [Player and physics](https://github.com/hcoder10/blocksfield/blob/main/web/kit/player.js): `web/kit/player.js`
- [Physics](https://github.com/hcoder10/blocksfield/blob/main/web/kit/physics.js): `web/kit/physics.js`
- [Gameplay rules](https://github.com/hcoder10/blocksfield/blob/main/web/kit/gameplay.js): `web/kit/gameplay.js`
- [Game UI](https://github.com/hcoder10/blocksfield/blob/main/web/kit/ui.js): `web/kit/ui.js`
- [Game audio](https://github.com/hcoder10/blocksfield/blob/main/web/kit/audio.js): `web/kit/audio.js`
- [Cutscenes](https://github.com/hcoder10/blocksfield/blob/main/web/kit/cutscene.js): `web/kit/cutscene.js`
- [Debug and survey](https://github.com/hcoder10/blocksfield/blob/main/web/kit/debug.js): `web/kit/debug.js`

### Play and gallery

- [Browser player](https://github.com/hcoder10/blocksfield/blob/main/web/site/js/game.js): `web/site/js/game.js`
- [Game gallery](https://github.com/hcoder10/blocksfield/blob/main/web/site/js/site.js): `web/site/js/site.js`
- [Gallery index](https://github.com/hcoder10/blocksfield/blob/main/web/tools/build_index.py): `web/tools/build_index.py`

### Blocksfield Studio

- [Studio server](https://github.com/hcoder10/blocksfield/blob/main/blocksfield/studio.py): `blocksfield/studio.py`
- [Studio home](https://github.com/hcoder10/blocksfield/blob/main/web/studio/home.js): `web/studio/home.js`
- [Run monitor](https://github.com/hcoder10/blocksfield/blob/main/web/studio/run.js): `web/studio/run.js`
- [Studio UI helpers](https://github.com/hcoder10/blocksfield/blob/main/web/studio/common.js): `web/studio/common.js`

### Media generation

- [Generated assets](https://github.com/hcoder10/blocksfield/blob/main/blocksfield/web_assets.py): `blocksfield/web_assets.py`
- [Splat conversion](https://github.com/hcoder10/blocksfield/blob/main/blocksfield/splat_to_parts.py): `blocksfield/splat_to_parts.py`

### Other components

- **Game creator**
- **ComfyUI**
- **GPU arbiter**
- **Web browser**
- [Pages publisher](https://github.com/hcoder10/blocksfield/blob/main/deploy/publish_pages.py): `deploy/publish_pages.py`

## Connections

- Game creator → Build orchestration: submits pitch
- Build orchestration → Plan and schema: plans game
- Build orchestration → Generated assets: generates assets
- Build orchestration → Game scaffold: scaffolds game
- Build orchestration → Playtest and judge: tests and repairs
- Build orchestration → Finished game files: finalizes files
- Generated assets → Splat conversion: converts splat
- Generated assets → ComfyUI: requests generation
- Build orchestration → GPU arbiter: coordinates GPU
- Game scaffold → ThreeKit game core: composes kit
- Level and world → World building: builds with (evidence: `web/kit/level.js`)
- World building → Visual direction: uses palette (evidence: `web/kit/world.js`)
- Level and world → Visual direction: uses look (evidence: `web/kit/level.js`)
- Player and physics → Physics: uses physics (evidence: `web/kit/player.js`)
- Gameplay rules → Player and physics: uses player (evidence: `web/kit/gameplay.js`)
- Game UI → ThreeKit game core: reports errors (evidence: `web/kit/ui.js`)
- Game UI → Visual direction: uses palette (evidence: `web/kit/ui.js`)
- Game UI → Game audio: uses audio (evidence: `web/kit/ui.js`)
- Game UI → Debug and survey: uses survey (evidence: `web/kit/ui.js`)
- Visual direction → Cutscenes: uses cutscenes (evidence: `web/kit/look.js`)
- Playtest and judge → Web browser: plays and judges
- Browser player → Finished game files: loads game
- Game gallery → Gallery index: reads listing
- Game creator → Studio home: enters pitch
- Studio home → Studio server: uses app
- Run monitor → Studio server: fetches run data
- Run monitor → Studio UI helpers: uses helpers (evidence: `web/studio/run.js`)
- Studio server → Build orchestration: launches builds
- Studio UI helpers → GPU arbiter: shows GPU status
- Pages publisher → Gallery index: rebuilds index (evidence: `deploy/publish_pages.py`)
- Pages publisher → Game gallery: publishes site
