This folder is the onboarding manual for the Webspaces project — an ambitious system for creating multiplayer, editable 3D worlds out of nothing but static HTML files. It was built by George Fodor (gfodor) as an evolution of Mozilla Hubs (via the intermediate project "Jel"), and was paused mid-flight; these docs exist so that anyone (including future-you) can get back up to speed rapidly, top to bottom.
The one-sentence pitch: a webspace is a plain
.htmlfile with one<script>include; opening it in Chrome renders the document as a walkable 3D world, editing the world edits the HTML, and the engine writes the HTML back to wherever the file lives (local disk via the File System Access API, or a GitHub repo via the API) while syncing everything peer-to-peer with no dedicated server.
Start at 01 and read in order for a full ramp-up, or jump straight to the area you need.
- 01 — What is Webspaces? — vision, lineage (Hubs → Jel → Webspaces), core ideas, project status.
- 02 — Repository layout — the five repos in this folder and how they relate.
- 03 — Getting started as a developer — running the engine locally, creating a webspace, dev workflow.
- 04 — Architecture overview — the big picture: DOM as the source of truth, ECS, networking, writeback.
- 05 — Boot sequence — from
<script src=…>to an enterable world, step by step. - 06 — The DOM ↔ 3D mapping — how HTML elements become objects; webspace document format.
- 07 — Systems inventory — every system in
src/systems, with deep dives on the big ten. - 08 — Components inventory — every A-Frame component in
src/components. - 09 — Media pipeline — how a URL/file becomes an image, video, PDF, model, or text page in-world.
- 10 — Networking architecture — P2P via p2pcf/Cloudflare, NAF adapter, ownership, presence.
- 11 — Voice chat — WebRTC audio, worklets, lip sync/visemes.
- 12 — Writeback & persistence — saving worlds back to disk and GitHub; the origin abstraction.
- 13 — Collaborative editing — Yjs + Quill rich text sync, metadata dataflow.
- 14 — UI layer — the React app, panels, dialogs, HUD, popups, i18n, storybook.
- 15 — Text & Quill — in-world rich text pages, the Quill fork, rendering text to textures.
- 16 — Voxels & SmoothVoxels — VOX editing, the .svox format, the smoothvoxels library, voxmoji.
- 17 — Terrain — procedural terrain (
src/terra), chunking, workers, water/sky/environment. - 18 — Avatars — avatar construction, customization, animation.
- 19 — Rendering pipeline — three.js fork, batching, effects, materials, text rendering.
- 20 — Physics — Ammo.js/three-ammo integration, character controller.
- 21 — Workers, worklets & WASM — everything running off the main thread.
- 22 — Configuration surface —
webspace.*meta tags, attributes, query params, the COEP service worker, runtime globals. - 23 — The docs/tutorial site — webspace-sdk.github.io and the example worlds.
- 24 — Forked & sibling repos — quill, networked-aframe, smoothvoxels forks; what changed and why.
- 25 — Build, deploy & release — webpack, S3/webspace.run deployment, versioning.
- 26 — Known issues & unfinished work — the todo list, rough edges, where work stopped.
- 27 — Glossary — Hubs/Jel/Webspaces jargon decoder.
- 28 — Webspaces × Atrium — analysis of Tony Parisi's Atrium (glTF browser with multiplayer) and concrete integration paths.
| Main repo | webspace-engine (~563 source files, ~85k lines of JS under src/) |
| License | MPL-2.0 |
| Last engine commit | 2025-12-05 (e9ca4b206 "Fix YouTube resolution failures causing game freeze") |
| Lineage | Mozilla Hubs → Jel → Webspaces |
| Org | github.com/webspace-sdk |
| Public site | https://webspaces.space (served from webspace-sdk.github.io) |
| Engine CDN | webspace.run S3 bucket (webspace-latest.js) |