Builders World

A living, browser-based world for developers and designers, set in real African cities, where your real work is your currency.

Play it · Straight into the world · Tour · Run it locally · Contribute

Every commit you push on GitHub becomes Efforts, the money you spend in the world. You arrive, get a home, and live a builder's life: work from hubs, cafés and studios, ride across the city, fly to another one, play padel after work, and meet the other builders who are online at the same time.

The streets are real. Lagos, Nairobi, Accra, Abuja, Port Harcourt and Uyo are rebuilt from OpenStreetMap at their real size, on their real street grid, with the real time of day and the weather that's happening there right now. It all runs in the browser, with no download and no game engine: three.js, Vite and a small Rust server.

Contents

• A tour of the world
• The cities
• What you can do
• Controls
• Run it locally
• How it's built
• What's in this repository
• Contributing
• Still to come
• Team
• Licences and credits

A tour of the world

Lagos at golden hour. Victoria Island, the Lekki-Ikoyi Link Bridge and the skyline. The sun sets when it sets in Lagos.	Nairobi from the air. Each city is streamed round you to the horizon, every building from OpenStreetMap.
Yaba, where it started. The Creative Hub, the community board and residents going about their day.	Work from a hub. Find a free desk, ask for the Wi-Fi password, open your laptop.
Get around. Walk, cycle, skate, or hire a danfo, keke or taxi. Driving yourself needs a licence.	Fly to another city. Check in, go through security and passport control, board, land, clear customs.
Play by the real rules. Padel, tennis, table tennis, basketball, swimming, and chess against regulars or anyone online.	Dress your way. Ankara, Adire, kaftan and agbada, gele and fila, and ten hairstyles.
A phone with real apps. Map, Ride, Travel, Wallet, Radio, Weather, Pets, Sports. It needs Wi-Fi.	The world map. 135 tech cities in 84 countries: six live today, the rest coming.

 

_{Pick a city, each on its own clock and weather. It plays on phones too, with touch controls.}

_{Screenshots from main on 22 October 2026, on a desktop browser. The live game can be a few days behind main.}

The cities

Six cities are live, each with areas built in full and the whole city streamed round them:

City	Areas	The open world covers
Lagos	Yaba, Ikeja, Victoria Island, Lekki Phase 1, Surulere, Apapa, Lagos Island	Ikeja down to Lagos Island and Lekki Phase 1, about 18 by 23 km
Nairobi	Kilimani, City Centre, Westlands	Central Nairobi, Westlands and Kilimani, about 9 by 7 km
Accra	Osu, Accra Central, Airport City	Osu, Accra Central and Airport City, down to the sea
Abuja	Wuse, Central Business District, Jabi	Wuse, the CBD and Jabi
Port Harcourt	Old GRA, Rumuola, Trans-Amadi	Old GRA, Rumuola and Trans-Amadi
Akwa Ibom	Uyo, Ring Road Uyo, Eket, Ikot Ekpene	Uyo and Ring Road

Each city has its own landmarks, side of the road (Nairobi keeps left), vehicles (danfos, matatus, trotros, kekes), street food, real FM radio stations, signs and accents. A Nairobi resident speaks Swahili, English or Sheng and is called Wanjiku or Otieno; that comes from each city's knowledge base in cities/.

Another 129 cities are on the world map as "coming later". Adding one is a good first contribution: cities/README.md.

What you can do

Live a builder's life

• Start in your own home: seven rooms with a workspace, a lab and a studio. Sit, sleep, cook, shower, watch TV.
• Work from hubs, a co-working loft, a design studio and cafés. Wi-Fi has passwords, found on notice boards, menus and your membership cards. Some places are members only.
• Earn Efforts from your GitHub commits and spend them on rides, food, gadgets, passes, fees and travel.
• Carry a bag with gadgets, badges, and a card holder for your passes, passport and driver's licence.

Live in the city

• Residents have names, jobs, families, homes and moods, and greet you in English or Pidgin.
• Traffic keeps to its lanes and the speed limit and gives way at crossings, with LASTMA, FRSC and NTSA officers on the roads.
• Order suya, roasted corn or a plate from a food truck face to face, and watch it being made.
• Feed the pigeons, make friends with a dog, or adopt your own and walk around as it.
• Live time of day and weather: morning mist, rain, wet streets that dry, streetlights at dusk.

Get around

• On foot (click to walk, with a GPS trail), on rented bikes, or on your own bicycle, skateboard, skates, hoverboard or e-scooter.
• By hired danfo, keke or taxi, as a passenger, or as the driver once you've passed the eye and theory tests.
• By taxi across the city to its other areas and landmarks, or by plane to another city. Flying abroad needs a passport from the Immigration Centre.

Together

• Sign in with GitHub and see the other builders who are online, on the street and on the map. Chat, emote, and look at each other's profiles (only what each person chooses to share).
• Pick up litter, fund street bins together, build benches in the community build area, pin notes on the board.
• Play sport by the real rules, and chess against anyone online.

The full feature list is in the game's README.

Controls

Key	Does	Key	Does
W A S D / arrows	Walk (or click the street to walk there)	Tab	Phone
Shift	Run	M	Map
Space	Jump	I	Bag
E	Interact, enter, order, talk	V	Camera view
C	Cinematic travel along your route	B	Aerial view
1 to 6, G	Emotes, all emotes	Enter	Chat
Q	Play as your dog	Esc	Close, stand up

It also plays with a PlayStation or Xbox controller, and with touch controls on phones. Every key is in the game's README.

Run it locally

You need Node 20 or newer.

git clone https://github.com/builders-world/builders-world.git
cd builders-world/apps/game
npm install
npm run dev

Open the address it prints for the onboarding, or add ?world=1 to go straight into the world. Without the server the game plays on its own with a demo balance.

Some useful switches to add to the address:

Switch	What it does
?city=Nairobi&area=Westlands	Start in a city and area
?hour=19.5	Set the time of day
?wx=rain	Set the weather: clear, cloudy, drizzle, rain, storm, fog, haze
?quality=low	Graphics tier: low, medium, high, ultra (Auto adapts to your device)
?hud=0	Hide the interface

The rest are in the game's README. To run the server for sign-in and other players, see services/backend (Rust, PostgreSQL and Redis).

How it's built

flowchart LR
  subgraph Browser
    G["Game<br/>three.js + Vite"]
  end
  subgraph Vercel
    S["Static build<br/>and baked city data"]
  end
  subgraph Railway
    GW["Gateway (Rust)<br/>sign-in, presence,<br/>bins, Efforts"]
    J["Jobs (Rust)"]
    PG[("PostgreSQL")]
    R[("Redis")]
  end
  OSM["OpenStreetMap and<br/>building heights"] -- "baked by<br/>apps/game/scripts" --> S
  S --> G
  G -- "/api" --> GW
  GW --> PG
  GW --> R
  J --> PG
  J --> R
  GW -- "sign-in with no scopes,<br/>commit counts" --> GH["GitHub"]
  G -- "live weather" --> OM["Open-Meteo"]

Loading

• The world is baked, not queried live. Streets, buildings, heights and terrain are baked from open data into JSON chunks (apps/game/public/city/) that ship with the game. Only the 200 m pieces near you are built, in a worker, with detail that scales with distance and with your device.
• One set of rules, a look per city. Traffic, zoning, physics and UI work the same everywhere; architecture, vehicles, food, radio and language are set per city.
• The server only knows what it must. The gateway handles GitHub sign-in (no scopes, so it can't see your code), who is online, the street bins and the Efforts count. Everything a browser sends is cleaned before it's stored or shown.
• The world bible is the source of truth for scale, streets, level design, art, game logic, UI, writing and performance. The PRD decides what the product is; the bible decides how it's built.

What's in this repository

Folder	What it is	Checks
apps/game	The game (three.js + Vite). Deploys to Vercel from main	game.yml: unit tests, build, browser tests
services/backend	The Rust gateway and jobs. Deploys to Railway	backend.yml: fmt, clippy, tests, sqlx
cities	One folder per country and city, with each city's knowledge base	checked by the game's tests
assets	Blender sources, the procedural model kit, reference art
docs	Product, world bible, architecture, decisions and collaboration notes

Each check runs only when its folder changes. packages/, database/, infra/, tests/ and tools/ are reserved for the planned architecture; see the repository layout.

Project documents

• Product requirements (PRD v1.1), also as HTML and PDF
• World bible and the immersive onboarding brief
• Request tracker, where things stand now and decision records

Contributing

Contributions are welcome, and you don't need to write code to help. Report bugs, tell us what your city is really like, add a city to the map, fix something, or improve the docs.

• Start with CONTRIBUTING.md: setup, checks, branches and the rules that keep the world honest.
• Read the code of conduct. It covers this repository and how players treat each other in the game.
• Found a security problem? Report it privately, as SECURITY.md explains.

Still to come

• Efforts kept on the server in a ledger, so balances can't be edited locally.
• Character models in the reference art style.
• Dribbble sign-in for designers.
• A browser on the in-game laptop.
• More countries and cities.

The tracker has the full list and the decisions still open.

Team

Name	Role
Elvis Obi	Design Engineer
Samson Goddy	Developer
Czar Ayotomide	Software Engineer
Joshua Ayokhai	Developer

Licences and credits

Builders World is open source. Different parts of the repository are under different licences:

What	Licence
The code: everything not listed below	Apache 2.0
The city data built from OpenStreetMap: apps/game/public/city/, apps/game/public/data/	ODbL 1.0
The original art: assets/	CC BY 4.0

By opening a pull request you agree that your contribution is shared under the licence of the folder it changes.

Map data © OpenStreetMap contributors. Building heights from GHS-BUILT-H (European Commission, JRC), terrain from Terrain Tiles on AWS, weather from Open-Meteo, and country outlines from Natural Earth. Every source and its credit is in NOTICE. Sound and music are generated in the browser.

Real places keep their real names, and their owners have not endorsed the game. The companies on the skyline billboards, the hubs, the airlines and the people in the world are invented.