A complete reference for the fully on-chain voxel world. Every block, creature, control, and Bitcoin-reactive system documented.
Overview
What is BlockForge?
BlockForge is a fully on-chain voxel world inscribed on Bitcoin. The entire game — code, textures, world generation — runs from a single HTML inscription. No servers, no CDN, no external dependencies.
The world is divided into a 32×32 grid of chunks (1000 pieces total). Each chunk is a separate inscription that can be claimed by its owner and edited. Edits become permanent when inscribed as child inscriptions of the chunk piece.
Architecture: Three.js WebGPU + TSL. World seed is fixed, so terrain is deterministic across all viewers. Edits are diffs from the procedural baseline, stored as JSON child inscriptions.
World Structure
The world spans -16 to +15 in both X and Z chunk coordinates. Each chunk is 32 blocks wide, 32 deep, and 64 tall.
A player's home chunk is determined by the inscription ID they loaded. Chunks not yet claimed show procedural terrain only.
Block coordinates: world X/Z range from -512 to +511. Y ranges 0-63. Bedrock fills y=0, terrain surface varies by biome.
Mega Chunks
8 special 2×2 chunk areas exist at biome intersections. A single inscription owns the entire 2×2 area, giving builders 4× the space for larger builds like cities or castles.
Mega chunks appear on the World Map with an orange outline and diamond marker.
Biomes
The world has 8 biomes, determined by large-scale noise. Each biome has unique terrain, blocks, structures, and creatures.
Plains GREEN
Rolling green hills with scattered trees, tall grass, flowers, and fireflies. The "home" biome.
Rare features: boulders, fallen logs, firefly jars. Blocks: grass, dirt, stone, sand near water.
Creatures: Sheep (common), Monkey (40% of chunks).
Desert YELLOW
Sandy dunes with saguaro cacti, mud huts, and walled compounds. Three variants of structures: small hut, medium house, walled compound with corner towers.
Blocks: sand surface, stone underneath, sandstone and clay in structures, desert lamps for light.
Creatures: Desert Sheep, Scorpion (30% of chunks).
Tundra WHITE
Snow-covered landscape with conifer trees, ice spikes, ice crystals, and rare igloos with domed roofs and entrance tunnels.
Water freezes to ice at this latitude. Igloos are built from pure snow with ice crystal centerpieces.
Creatures: Penguin.
Enchanted Forest PURPLE
Indigo ground with giant mushroom trees (5 cap shapes), magic logs, glowing magic leaves, hanging vines, and witch huts on stilts with thatch roofs.
Mushroom tree caps have 3 shape variants: dome, flat disc, drooping. Caps spawn leaves with occasional hanging vine droops.
Creatures: Fox, Wizard (50% of chunks).
Alien Planet TEAL
Vivid acid-teal ground with magenta rocks, orange spires, bioluminescent flora, and rare crashed ships with exposed engine cores. Occasional portals stand as obsidian frames with portal block fill.
Crashed ships include cockpits with cyber-window glass and energy-core exhaust.
Creatures: Alien Jellyfish (floating), Tripod (50% of chunks).
Ruins TAN
Cracked concrete ground with collapsed archways, partial stone rooms, rusted metal frames, and crumbling pillars.
Creatures: Sentinel (stone head, stares at you), Wraith (40% of chunks, translucent ghost).
Cyberpunk CYAN
Dark asphalt with glowing cyan grid lines, neon roads, and randomly generated skyscrapers with windows, energy cores, and crystal spires. Three skyscraper variants: slim (3×3), wide (5×3), L-shaped (5×5).
Creatures: Drones (patrol pattern with scan beams).
Ocean BLUE
Submerged biome below water level. Features coral clusters, kelp forests, shipwrecks with broken masts, underwater stone ruins, and sand mounds.
Shipwrecks are L-shaped plank structures on their sides. Underwater ruins are 3×3 brick/stone with some collapsed walls.
Creatures: Blue Jellyfish, Anglerfish (50% of chunks, glowing lure).
Terrain Features
Floating Islands
Rare (~3% of chunks) sky islands with a top surface, conical underside, biome-matched blocks, occasional trees, and 60% chance of waterfalls streaming down to the ground. Some hang a lantern from the underside for a floating lamp effect.
Underground Caverns
About 15% of chunks contain 1-2 hidden spherical cave rooms underground, buried at least 4 blocks below the surface. Each cave contains biome-themed emissive loot scattered on the floor.
Cave loot tables: Plains=fireflies, Desert=lamps, Tundra=ice crystals, Enchanted=magic leaves+crystals, Alien=spires+cores, Ruins=warning lights+lanterns, Cyberpunk=neon+cores, Ocean=coral+lanterns.
Water Level
Sea level is at Y=10. Any terrain below this floods with water in Plains and Ocean biomes, or ice in Tundra biomes.
Sand appears on beaches where plains terrain meets water. Plains/tundra chunks with low terrain (h < 10) fill with water/ice up to level 10.
Procedural Signs
Hidden signs containing Bitcoin and cypherpunk quotes are seeded inside enclosed structures throughout the world — ~2% chance per eligible column. 25+ different quotes from Satoshi, Hal Finney, and others.
Signs are placed only in structure interiors (floor + walls on 2+ sides, non-natural blocks).
Bitcoin-Reactive World
The world responds to live Bitcoin blockchain data. Polled every 30 seconds from the inscription host.
Day/Night Cycle — Block Parity
Even-numbered Bitcoin blocks = night, odd-numbered blocks = day. The sun and moon arc across the sky over the ~10-minute block window, with smooth dawn/dusk transitions.
Block height drives dayNightTarget (0 or 1). Camera sky color, fog, ambient light, and sun/moon positions interpolate smoothly. Block height is displayed on the sun/moon face.
Weather — Average Fee Rate
The current block's average_fee_rate drives weather intensity:
| < 1 sat/vb | Clear skies |
| 1-3 sat/vb | Light rain (150 particles) |
| 3-6 sat/vb | Moderate rain (350 particles) |
| 6-10 sat/vb | Heavy rain (600 particles) |
| > 10 sat/vb | Thunderstorm (900 particles, lightning flashes) |
Tundra biome always shows snow instead of rain. Desert/ocean never show precipitation.
Cloud Density — Transaction Count
The current block's transaction_count maps to cloud coverage. Empty blocks give sparse clouds, full blocks give overcast skies.
Maps 1000-10000 txs to noise threshold 0.80 → 0.25. Cloud mesh rebuilds when threshold changes by more than 4%.
Creature Behavior — Block Nonce
Each Bitcoin block's 32-bit nonce re-seeds creature RNG. On a new block, every creature picks different walk targets, flee decisions, beam timers, magic cast intervals, etc.
Shooting Stars — New Blocks
When a new Bitcoin block arrives, the sky flashes and 20-50 shooting stars streak across. Hard-capped at 60 simultaneous stars to prevent lag spikes (e.g., from tabs refocusing after many blocks elapsed).
Seasons — 100-Block Cycle
Every 100 Bitcoin blocks, biomes shift through a subtle color cycle:
- Ruins darken and gain more cracks
- Magic leaves shift pink → deep purple
- Cyberpunk neon shifts cyan → magenta
- Alien flora pulses green → violet
- Tundra snow shifts white → blue
- Desert sand shifts warm → cool
- Sky background warms slightly at peak season
Override with the Season Cycle slider in Options.
Live Fee Rate Display
The Fee Rate block (ID 73) renders the current Bitcoin fee rate as text on all faces. Updates whenever the fee rate changes.
Multiplayer
How It Works
Multiplayer runs over WebRTC through an server-hosted relay. Every client opens one WebRTC datachannel to the same relay box and joins rooms there.
Relay address (IP, port, ICE creds, DTLS fingerprint) is anchored on a Bitcoin sat (25483050881520); clients fetch the latest config from /r/sat/<sat>/at/-1/content, so the relay can be rotated without touching the piece. Server is Pion (Go) on a Hetzner box.
What Syncs
- Player position and yaw + pitch (10 Hz) — peers see your head tilt when you look up or down
- Player name, color, and skin texture
- Block placements and breaks (broadcast through the relay)
- Chunk operations (reset/erase/erase-floor — owner only)
- Chat messages and emotes
Each loaded chunk subscribes to its own relay room (mp:chunk:cx,cz). Edits are buffered server-side for ~72 hours; players who join a chunk room receive the buffered history as replay events so late-joiners see existing builds.
Wave Emote
Press H to wave hello. Your avatar's right arm raises and wags side-to-side for two seconds. The emote is broadcast as a one-shot message on the global room so every peer plays the same animation on your avatar.
Emote messages aren't persisted, so reconnects don't re-trigger stale waves on chunks you visited before.
Chat Bubbles
When a player sends chat, the most recent message floats over their head for 5 seconds. Latest message replaces the prior one; the bubble fades on its own.
Your own messages also show above your third-person avatar so what you say matches what others see.
Offline Fallback
If the relay is unreachable, your edits save to browser localStorage instead. They still appear locally across reloads, just not to other players.
The true "source of truth" for all changes is always the child chunk inscriptions. Multiplayer is a quality of life addition on top of this, but the core world will always remain on-chain via parent-child.
Marketplace
Live ord.net listing and recent-sale data is pulled through the relay at boot and surfaced in three places: two sky billboards in chunk (0,0), the cyberpunk ad blimps drifting overhead, and the chunk-info HUD when you walk into a listed chunk.
Listings & Sales Endpoint
The engine calls two relay actions at boot:
bf-listings — current live listings: floor price, total listed count, plus each entry's inscription ID, chunk name, price in sats, and listing URL on ord.net.bf-recent-sales — last 10 ord.net sales: inscription ID, sale price (sats + USD), buyer, seller, and timestamp.
Both relay actions are server-side GETs against blockforgebtc.com/api/blockforge/{listings,recent-sales}; the relay proxies the JSON over the data channel because ordinals.com's CSP blocks the in-game client from calling our backend directly. Boot fetch is best-effort — if either call fails, the corresponding billboard/blimp stays hidden but the rest of the world is unaffected.
Chunk (0,0) Billboards
Two canvas-textured sky panels mounted below the floating "BLOCKFORGE" energy-core text in the welcome chunk:
- RECENT SALES — 10 most recent sales with chunk tag, age (e.g. "5h ago"), and sat price.
- LOWEST LISTINGS — 10 cheapest live listings with chunk tag and sat price, plus floor + total listed in the subtitle.
Each panel is double-sided (two coplanar planes facing opposite ways) so the text is readable from either approach.
Cyberpunk Ad Blimps
Three slow-drifting blimps circle the world at varied altitudes, each carrying a side-mounted screen that reuses the same billboard textures (one upload to the GPU; multiple meshes reference it).
- Sleek dirigible (cyan trim, low altitude) — tapered cigar hull with a gondola, vertical antenna, red blinking beacon. Carries listings.
- Industrial freighter (magenta trim, mid altitude) — boxy stepped hull, magenta engine thrust pods, yellow caution lights. Carries sales.
- Drone scout (cyan trim, high altitude, counter-rotating) — compact hull with four corner ducted-fan housings, green nose sensor. Carries listings.
Aesthetics chase the cyberpunk biome palette (dark metal hull, neon road / neon panel / energy core accent colours). Beacons blink on per-blimp phases so the trio doesn't strobe in sync.
In-World Buy Hint
When you walk into a chunk that has a live listing, the chunk-info HUD adds a line:
◆ Listed on ord.net: 41,000 sats (Press B to Buy)
Press B to open that chunk's ord.net inscription page in a new tab. The hint and keybind are no-ops on chunks that aren't listed.
The chunk lookup is built from the listings response by parsing chunk coordinates out of each listing's name field ("BlockForge #N - Chunk (cx, cz)"). Lookup is O(1) per HUD refresh.
Technical
Inscription Structure
The parent inscription contains the full game HTML. 1000 child inscriptions represent the individual chunks (some are mega-chunks spanning 2×2 sub-chunks).
When a player edits their chunk, they inscribe a JSON diff as a child of their chunk piece. On page load, all recent child inscriptions are fetched and applied as world edits.
Chunk JSON Format
Edit format for inscriptions:
{
"t": "edit",
"cx": 3, "cz": -2,
"a": [[x, y, z, "blockname"], ...],
"r": [[x, y, z], ...],
"tx": [{"iid": "abc...i0", "name": "myblock"}],
"signs": {"x,y,z": "sign text"},
"bh": 945000,
"author": "MDV"
}
See /blockforge/spec for the full AI-ready build spec.
Deterministic World Gen
Every aspect of the base world (terrain, biomes, structures, caves, chest contents) is deterministic from the fixed WORLD_SEED. This means every player loading the game sees the exact same procedural world, so builds can only deviate from a shared baseline.
Note on Inscriptions #1–100 Biome Traits
The first 100 BlockForge inscriptions (the initial airdrop batch) were generated using an older biome-calculation script that didn't match the final engine. As a result, ~78 of those 100 carry a Primary Biome trait that doesn't match what the engine actually renders for that chunk.
The engine's in-world rendering is canonical truth. If you stand in a chunk and see Cyberpunk, that chunk is Cyberpunk regardless of the listed trait. Inscriptions #101–#1000 use the corrected biomes that match the engine exactly.
We considered fixing this with a re-derived seed or per-chunk overrides, but both approaches would have either changed the world for everyone (breaking existing builds and the visual continuity of the map) or made the HUD lie about the actual environment. Trait noise on 7.8% of the first batch was the smaller cost. Going forward, every new piece is self-consistent: the trait you see on the marketplace matches the biome you'll see when you walk into that chunk.
Rendering
Three.js WebGPU renderer with TSL (Three.js Shader Language). Uses MRT (Multiple Render Targets) to render scene color, normals, and emissive separately for post-processing.
Chunk mesh uses 4 buckets: opaque, alpha (cutout), emissive, and water. Face culling skips faces touching identical or solid neighbors. Emissive bucket has depth-write enabled so depth tests work correctly.
Texture Atlas
All block textures pack into a single 1024×1024 canvas in a 16×16 grid of 64×64 slots. Supports up to 256 blocks.
Skin Format
Standard Minecraft 64×64 skin layout. UV regions for head, body, arms, legs, and overlay layers.