Shape of the World
English · 中文
Shape of the World (世界的形状) — see how the world works. A set of playable visual worlds for a general audience: beauty, surprise, and touch come first, and the science follows. Live at shapeof.world.
This repository holds the web experience, the world runtime and the worlds themselves. The retired private repository oneworld is kept only as an archive. The site does not sell anything.
Root AGENTS.md holds the few facts and rules that apply across the repository.
Local development
pnpm install
pnpm dev
Open http://localhost:3000. Simplified Chinese is the default locale; English pages live under /en.
The exact upstream snapshot of the official Three.js periodic-table example and
this project's adaptation live in vendor/three-periodic-table/. After changing
it, run pnpm build:periodic-table.
Verification
pnpm check
pnpm check is the local quality gate: types, unit and infrastructure tests, the
generators, the production build, the client asset budget and the Worker bundle
budget. The repository does not configure GitHub Actions; the publisher runs this
command on a clean worktree.
For a single world, pnpm world:check --id <world-id>.
Deploy
Production is Cloudflare Workers: Worker shape-of-the-world serves
shapeof.world. The site as it stood before 2026-10-21 stays online, unindexed,
at v2.shapeof.world. Analytics (infra/insights) and the video press kits
(infra/press) deploy as their own Workers.
The short films are code too: films/ holds the source that renders each
frame and its music. See films/README.md.
pnpm check
pnpm build
npx wrangler deploy
Product architecture
- TanStack Start + TanStack Router: server rendering and routing
- Client experience registry: each world’s component, private CSS and English dictionary lazy-load in parallel; large browser engines stay out of the Worker server bundle
- 384×256 catalogue thumbnails: catalogue and series cards never download a 2560px poster
- deck.gl / Flowmap.gl, model-viewer, Mol* and Three.js adapters: flow networks, structure, molecules, planetary imagery and native interactive experiments
- Cloudflare Workers: edge deploy, same-origin assets and anonymous events
- Build budgets: Worker, global CSS, shared experience runtime, individual JS chunks and Cloudflare static asset size
- An installable PWA shell
- Anonymous product events: opens, real interaction, meaningful dwell, saves, shares and remote-asset load failures; no knowledge content and no personal identity
Worlds and their sources
Every world carries its own source and rights record beside its code, and the
project only ships material that is either drawn by the project or licensed by a
third party for reuse with attribution, without a permission request and without
a non-commercial restriction. The entry rule for new worlds is in
AGENTS.md.
Licensing and commercial terms
- Project-owned software in this repository:
AGPL-3.0-only.
Commercial use that fully meets the AGPL obligations for that use needs no paid
licence. Using the code in a closed-source product or service beyond the AGPL
grant requires a separate commercial licence.
- Original editorial copy and project-owned visual work:
CC BY-NC 4.0.
Uses outside that NonCommercial grant that legally need a copyright licence
require separate written permission.
- Third-party code, models, data, images, fonts, audio and embedded services keep
their own licences; this repository’s terms do not relicense them.
- The name “Shape of the World / 世界的形状”, the logo and brand marks are not
licensed with the code or content: TRADEMARKS.md.
Full boundaries: LICENSING.md. Issues are welcome; pull
requests are not accepted for now: CONTRIBUTING.md.
Contributors
- MakerJackie: creator and maintainer.
- Past contributor: Yu (yuzerofish), design and development, July to October 2026.
Sponsors
This project is sponsored by 叠加态社区 (SUPERPOSITION) and 数耀量生 (QuantSparkle).
Rights for sponsor logos: asset notice.
