Design direction · for Justin Butlion's "Commit Town" · 17 Aug 2026
Your GitHub is a town.
Make it alive, not just rendered.
The idea is charming and the passive loop is genuinely the right shape for developers (the work is work you were doing anyway). But the "GitHub → 3D city" screenshot is already a commodity, and the living part — the thing Justin called the hard part — is the cheap part. What is hard is giving anyone a reason to come back.
One shared metropolis; every profile is a skyscraper (height = contributions). Windows glow while you code, VS Code ext, shop, share cards, referrals. Grew 211 → 11k signups/day after one Reel. $1,606 all-time revenue, no subscriptions. Planning "visual decay" + multiplayer.
Per-user low-poly Three.js diorama from one year's grid, boats and clouds loop, STL export. PH #2 of the day. Dormant since Oct 2023. Ships 111 GLBs ≈ 6 MB and real-time PCF shadows — the perf trap to avoid.
GitCity: 365-day iso skyline with a README SVG embed; got "clone" accusations on launch day. GitAnimals (1.8k★): commits → animated pets in your README with a points economy. Spaceorbust: typed event→resource civ game — text only, 1★.
Also GitHub's own Skyline (now a CLI, STL export), contribution-city, gitown, gitcity.io, isometric-contributions (3.7k★). Nobody has shipped simulation: state that evolves between visits, allocation you steer, commit ≠ merged PR ≠ review ≠ star rendered as different things in the world, time as an axis. That residue is real. It just has to be visible in the first screenshot or the internet files it under "another GitCity".
repo scope. There is no read-only private scope; use read:user + GraphQL contribution counts.Population → house count and tiny walkers. Happiness → parks, lit windows, festival lanterns. Tourism → balloons, boats, a viewing tower. Technology → cranes, antennas, height. Neglect → fog, dim lights, parked cranes. Numbers are a secondary layer you can hide. Justin's prototype has this inverted: the tiles carry the information and the field carries none.
Six to eight cheap ambient loops (train, crane sway, balloons, boat bob, windmill, flags, walkers, a blinking window). Day/night from the developer's own clock — a 2 a.m. push lights the town, and that is the shareable frame. GitHub events as visible beats: commit = bricks arrive; merged PR = topping-out; release = fireworks; star = a balloon lands; CI red = smoke. Growth is construction, never pop-in.
A visible plinth edge turns the town into an object; it grows and annexes islets with stage, solves the world edge, and frames identically for OG, banner and vertical clip. Fixed orthographic camera with four snap rotations and three zooms. Greyscale-check every asset (Dorfromantik), no dirt or noise (Two Point). Real-time shadow maps are banned — bake AO and warm ground bounce.
All three were generated from the same brief. The differences are exactly the differences that matter at share size.
Rejected outright: pixel art / RPG-Maker sprites on a flat field. It is the asset-flip tell, it is what the category already looks like (Git City is pixel-neon), and it cannot make the plinth-object composition that the share unit needs.
Max height, ground material (dirt → cobble → asphalt) and one hero landmark (well → clock tower → crane → towers → spire). Monotonic — a town never de-ranks. Thresholds borrow GitHub's own tier ladders (Pull Shark 2 / 16 / 128 / 1024, Starstruck 16 / 128 / 512).
| Stage | Threshold (civic points) | Silhouette |
|---|---|---|
| Hamlet | first login | Flat warm island: 3–6 low cottages, one dirt road, a well, staked-out plots with survey flags, a parked cart. Wide low horizon. |
| Village | ~100 pts / 2 merged PRs | First vertical: a stone church or clock tower. Cobbled market square with awnings, first balloon pad, windmill turning at the edge. |
| Town | ~750 pts / 16 merged PRs | Grid roads, 3–5-storey blocks, small station with a looping train, town hall with flag, first park with pond, one crane. Skyline gets a shoulder. |
| City | ~4,000 pts / 128 merged PRs | Two or three glass towers, elevated rail loop, river with bridge, districts by repo, night mode, several balloons; plinth annexes an islet. |
| Metropolis | ~20,000 pts / 1,024 merged PRs | One supertall spire, harbour with cranes and ferries, tiny airstrip, monorail, monument park recording releases. Dense but readable, plinth edge still visible. |
Points: merged PR 10 · star 5 · release 25 · review 3 · closed issue 2 · commit 1 (daily cap). Overlays that must read at 400 px: fog (dormant), lanterns/fireworks (festival), crane + scaffold (construction).
53 weeks × 7 days is already an isometric grid: 53 blocks by 7 avenues. Cell intensity becomes the plot — meadow, cottage, house, mid-rise, tower. Left to right is the town's history laid out in space. Your own graph — ten quiet months, then a June–August boom — renders as meadows in the west and a dense new quarter in the east: hamlet to town in one quarter, on real data.
Live: canvas, no libraries, ≈250 lines. Scrub or let it play. Reconstructed from your screenshot (344 contributions) — the public API for the three local logins totals 3 / 1 / 0, so the 344 view is a private-inclusive view of another account; swap in contrib.json from GraphQL contributionsCollection when you want the exact cells.
fix: retry OTP send — 3 bricks to the Post Office.Why bricks are capped. Raw commits are the most gameable signal (gitfiti, activity generators) and the one that punishes the senior on a private monorepo who ships five big PRs a week. Bricks earn with daily diminishing returns and are never the headline number; Blueprints (merged PRs) are.
Bricks (labour), Blueprints (validated work), Visitors (external attention), Morale (community). Justin's four sliders — Expansion / Technology / Happiness / Tourism — stop being resources and become the spend, each with a distinct visible outcome.
| GitHub event | Resource | Visible in town | Earned? |
|---|---|---|---|
| Push / commit | Bricks — daily diminishing, capped | Cart drops bricks at a site; scaffolding rises one tier | Earned but gameable — cap it, never headline it |
| PR opened | Small Blueprints + reserved plot | Surveyors stake a plot; sign shows the PR title; crane parks | WIP towns should visibly have cranes |
| PR merged | Blueprints (primary building currency); bonus into others' repos | Topping-out: crane lifts roof, windows light, ribbon-cut; size ∝ lines changed (capped) | Most earned; Pull Shark tiers 2/16/128/1024 |
| PR review / review comment | Morale | Inspector walks the site with a clipboard; approve = green stamp floats up | Under-celebrated elsewhere — a differentiator |
| Issue opened on your repo | none | Pothole / orange cone on a road | Legible; do not reward (spam vector) |
| Issue closed | Bricks small + Morale small | Road crew fills the pothole | Earned |
| Release published | Blueprints × multiplier + Visitors burst | Fireworks over the tallest building + a named landmark with the tag | Rare — attach the share prompt here |
| Star received | Visitors | Tourist balloon lands; Starstruck tiers unlock viewing tower / observation deck | External validation — weight above commits |
| Fork | Visitors + a road segment | Road exits the map edge toward a "sister settlement" outline | Subtle only |
| CI green / red on default branch (webhook) | state | Power plant hums, lights on / smoke, one district flickers; clears on next green | Honest, non-destructive |
| Discussion answered / sponsorship | Morale / Visitors + Morale | Crowd in the square; plaque / patron statue | Low volume, earned |
| Streak (computed) / inactivity | unlocks seasons / none | 7d lanterns, 30d festival, 90d biome; fog rolls in, cranes park; return = sunrise | Additive only; grace like Duolingo's freeze |
Data reality. Public Events API: ≤300 events / 30 days, 30 s–6 h latency, no CI status. There is no read-only private OAuth scope (repo = read/write) — use read:user + GraphQL contributionsCollection counts, or a GitHub App with webhooks. Never ask for repo. Test the slider nouns with five users; one meaningful choice per stage (which district, which landmark for a release) may beat set-once sliders — agency over upgrade paths sustains engagement even with deterministic outcomes (Cutting, Gundry & Cairns 2019, n = 1,972).
InstancedMesh per kit piece (60–80 pieces), vertex-coloured, textureless → ≈150–400 KB GLB after gltf-transform quantize + meshoptBan list. Real-time shadow maps (GithubCity's failure mode). Kenney kits beyond blockout — CC0 kits are the asset-flip tell; budget 1–2 weeks of tech-artist for a bespoke tiered kit + bake before any living layer. Textures. Post-processing. Voxel engines (exported look ≠ reference). SVG/CSS only for the README badge.
The town page. No stat tiles, no green field. Four resource meters, four coarse council settings, a "since you left" strip, and a share button. Everything else is the town.
feat/otp-retry → Post Office
🎈 2 tourists landed (stars on measure)
🧱 +31 bricks · scaffold up on Block 47
🌫 fog lifted
Coded, not generated. Coarse 4-step council settings instead of percentage sliders (a set-once slider is a widget, not a game); the strip at the bottom is the "what changed since you left" reveal that gives a passive product a reason to be opened.
Ranked share units: (1) the README animated-SVG embed — every profile view is an impression and it self-updates; (2) a public URL with a live OG image; (3) event-triggered 4–8 s clips with the share prompt at the moment; (4) weekly "This week in Janardhanpur" as a retention email, not a viral unit; (5) a year-end Town Wrapped timelapse.
The plinth diorama is chosen so a single frame works as a 1.91:1 OG image, a 3:1 README banner and a 9:16 clip. That is a design constraint on the camera, not an export setting.
Style lock prepended to every prompt: isometric low-poly clay diorama on a square plinth over calm water, fixed 45°/30° orthographic-isometric view, golden-hour light from upper left, baked soft AO and warm ground bounce, no hard shadows, matte flat-shaded, no textures or noise, subtle tilt-shift, muted value-first palette with a few accents, premium Blender/C4D toy-diorama render, no text. Every frame after the hero was made by image-reference editing of the hero so camera, palette and style stay locked.
Offer. If Justin wants it, the next artefact I would make is a Three.js proof-of-loop — the hero plate's geometry as an instanced kit with the ambient layer running at 60 fps under 1 MB — so the "living town" question is settled with a URL rather than a debate. That is a few days, not a project.