Dev Blog

BalloonBlox started as a pitch to Party City: their web 'balloon bouquet builder' let you compose a bouquet in 2D — we thought it would be better in 3D, in Roblox, where the bouquet appears tied to your character's hand as you build it on the web. Party City filed for bankruptcy; the prototype survived on a Linode box that has since gone dark.

The original repo is a time capsule: PHP endpoints, a jQuery UI drag-and-drop cart, and a Roblox place file with a single server script doing all the work. Step one of the rebuild was extracting the Lua from the binary .rbxl place files (via Lune's roblox library) and reading everything.

The good ideas worth keeping

Change detection by hash: the game polled get_cart_hash.php (an md5 of the cart contents) every few seconds and only re-fetched the full cart when the hash moved. Cheap and effective — we keep the idea, but as a monotonic integer version column instead of md5-of-serialized-PHP-array.

Physical shopping: stand in the red zone for 10 seconds and a red balloon is added to your cart — in the database, and in your hand, tied with a visible RopeConstraint and floated with an anti-gravity force. Walk into the yellow zone to let everything go. That's the soul of the thing and it survives intact.

The parts that did not survive review

function createSCTable($conn, $robloxUserName) {
    $query = "CREATE TABLE $robloxUserName (id int not null auto_increment,
              item_name varchar(255), primary key (id))";
    ...
}

function addToShoppingCart($conn, $robloxUserName, $item_name) {
    $sql = "insert into $robloxUserName (item_name) values ('$item_name')";
    ...
}

Every user got their own MySQL table, created on first sight of a username typed into a form with zero auth — and every query string-interpolates that username. SQL injection as a feature. The new backend is one carts row per player, parameterized queries via Drizzle, and a link-code flow so only someone standing in the game can claim a player's cart.

local playerName = ""

game.Players.PlayerAdded:Connect(function(thisPlayer)
    playerName = thisPlayer.Name  -- last player to join wins!
    _G.pl = getPlayerFromName(playerName).Character
end)

One global playerName for the whole server: whoever joined last owned everyone's balloons. The rebuild is server-authoritative and per-player from the ground up — every cart, zone timer, and balloon bundle is keyed by UserId.

Also not making the cut: two drivable cars (A-Chassis), a mansion, and in-car radios preloaded with several hundred copyrighted songs. The new place is a focused balloon shop with original, generated music.

The new backend is a Next.js App Router app deployed to Vercel at balloonblox.com, with Neon Postgres (provisioned through Vercel's marketplace) and Drizzle ORM. Five tables: balloon_types, carts, cart_items, link_codes, and a dormant orders table for a future Stripe checkout.

export const carts = pgTable("carts", {
  id: uuid("id").primaryKey().defaultRandom(),
  robloxUserId: bigint("roblox_user_id", { mode: "number" }).notNull().unique(),
  username: text("username").notNull(),
  // Monotonic change counter — the game's cheap change-detection signal
  // (replaces the legacy md5-of-cart hash). Bumped in the same transaction
  // as every mutation.
  version: integer("version").notNull().default(0),
  ...
});

Every mutation — web click, in-game zone add, clear — runs in a transaction that bumps version. Change detection is then a single integer comparison, and it can never collide the way a hash can.

Sync: one request per server, not per player

The legacy game made two HTTP calls per player every ~7 seconds. The new game server sends one batched POST with every present player and the last version it applied; the API returns full item lists only for carts that moved. A 20-player server is still one request per tick, comfortably inside Roblox's HttpService budget.

const Body = z.object({
  players: z.array(z.object({
    robloxUserId: z.number().int().positive(),
    version: z.number().int().min(-1), // -1 = "never synced, always send"
  })).max(100),
});

// ...returns { updates: [{ robloxUserId, version, items: [{ slug, stringLength }] }] }
// only for carts whose version differs from what the game reported.

Identity: a code you can only get in-game

The old site asked for a Roblox username — any username. Now the game kiosk issues a 6-character code (alphabet without 0/O/1/I, 15-minute expiry) via an API-key-authenticated endpoint, the player types it on the site, and the session cookie binds to their UserId. Claims are rate-limited per IP. Nobody edits your bouquet but you.

Game endpoints authenticate with an x-game-key header (timing-safe comparison) that only lives in ServerStorage on the Roblox server — it never replicates to clients and never appears in the repo.

The Roblox half is rebuilt as a set of server modules: ApiClient (authenticated HTTP with retry), CatalogService, CartService, BalloonService, ZoneService, DisplayWallService, MusicService, bootstrapped from one Main script. Clients get exactly two remotes: a GetLinkCode RemoteFunction (rate-limited server-side) and a CartChanged event they can only listen to. There is no code path where a client tells the server what's in a cart.

local function pollOnce()
    local body = { players = {} }
    for _, player in ipairs(Players:GetPlayers()) do
        local s = state[player]
        if s then
            table.insert(body.players, { robloxUserId = player.UserId, version = s.version })
        end
    end
    local res = ApiClient.post("/api/game/sync", body)
    -- apply only the carts whose version moved
end

Balloons themselves are spawned by the server: cloned templates (or procedural glossy spheres as fallback), tied to the player's right hand with a visible RopeConstraint, floated with a VectorForce at ~1.05× gravity. The deprecated BodyForce from the legacy scripts is gone. Walk-in zones are CollectionService tags with per-player dwell timers — a countdown billboard ticks over the pad, and at zero the server round-trips the mutation through the API before spawning anything.

Physical zone adds apply optimistically: the server already knows what changed, so the balloon appears in your hand immediately while the version from the API response keeps the next poll from double-applying. The web builder finds out on its next 5-second refresh — both surfaces converge on what Postgres says.

Secrets never touch the repo or the client: the API base URL and game key live as attributes on a ServerStorage folder, which doesn't replicate.

The world is built by scripts through the Studio MCP bridge — no manual part-dragging. Future lighting technology with a dusk grade (Atmosphere, Bloom, ColorCorrection), a storefront with a glowing sign, string lights, eight neon add-pads (one per balloon type), a yellow release pad on the plaza, the link kiosk, and a display stage in back.

Music and SFX are generated, not licensed: a Lune pipeline composes a ~90s whimsical instrumental loop and four effects (inflate, pop, link chime, UI plop) with ElevenLabs, uploads them through Roblox Open Cloud, and regenerates the AssetManifest module the game reads. The old place shipped radios with several hundred copyrighted tracks; this one ships zero.

$ lune run pipeline/01_gen_music.luau
composing ambient... saved data/music/ambient.mp3 (1439078 bytes)
ambient -> rbxassetid://121861298036785
$ lune run pipeline/02_gen_sfx.luau
add -> rbxassetid://119206267483682
clear -> rbxassetid://78609005578430
link -> rbxassetid://111366381781731
ui -> rbxassetid://129814984824621

The star balloon got an AI-generated mylar mesh (five-pointed, foil look) via Studio's mesh generation, normalized to balloon size and welded onto the standard knot + attachment rig so the rope code doesn't care which balloon it's tying.

The first flight

With the API live at balloonblox.com, a play session in Studio linked via kiosk code, and four balloons added on the web — they materialized on rope strings within one 4-second poll: HUD shows the bouquet and total, and the display stage mirrors it when you stand on the purple pad.

The reverse direction works too: stand on the blue pad for ten seconds and 'blue' shows up in the web cart; stand on the yellow pad and both sides empty out. Same versioned-cart contract in both directions, zero trust in the client anywhere.

Three new rare balloon types went into the catalog — gold, rainbow, diamond — but you can't buy your way in. Each is locked behind a challenge built next to the shop: a procedurally-generated hedge maze, a lava-hopping course, and a 110-stud climbing tower with moving platforms. Win once and the balloon is unlocked for your account forever, recorded in Postgres, usable in-game and on the web builder.

Wins the server can believe

Everything about a run is server-side: standing on a start pad begins it (and despawns your balloons — ropes and buoyancy forces have no business inside a maze), checkpoints are invisible 10-stud volumes that only count in order, and the finish is valid only after every checkpoint plus a minimum humanly-possible time. Leave the course bounds or move faster than physics allows and the run silently ends. There isn't a single client→server remote in the whole system — the client just watches.

-- All checkpoints, in order, and a humanly-possible time.
if run.nextCheckpoint <= cfg.checkpointCount then return end
local elapsed = os.clock() - run.startedAt
if elapsed < cfg.minRunSeconds then return end
-- ...and the API applies its own minimum-time floor again server-side.

The API applies the same skepticism: POST /api/game/unlock rejects run times below a per-challenge floor, and the add-to-cart endpoints 403 any rare balloon the player hasn't earned — the web UI's padlocks are decoration, not enforcement.

The first legitimate win

The end-to-end test walked the maze for real — through both checkpoints to the center plinth in 1:08. Confetti, a light beam, an oversized gold balloon released skyward, and a fanfare (freshly generated and uploaded alongside checkpoint and locked-buzz effects).

The Rare Vault sits at the plaza's north edge: three pedestal pads that work exactly like the shop pads — if you've earned them. Lock state renders client-side from replicated player attributes, because your padlocks aren't my padlocks.

Honest feedback arrived in the form of a screenshot: the Link button floated awkwardly beside the code input looking permanently disabled, the logo sat in a hard black box, and the drag-and-drop builder was bordered boxes with balloons on white squares. All true.

Three fixes

First, the assets: every balloon PNG and the logo went through an edge-connected flood-fill pass — only background pixels reachable from the image border become transparent, so the white balloon and the shine highlights inside the gold one survive. (A naive luminance key ate holes in everything; the flood fill was the fix.)

Second, the link form: the button is gone entirely. Six segmented character boxes driven by one hidden input — paste works, mobile keyboards work, and it auto-submits the instant the sixth character lands. Errors shake.

Third, the builder: a sticky glass header, a 'balloon wall' of backdrop-blurred cards with per-color glows — and the tray is dead. In its place, a live bouquet stage: each balloon in your cart is positioned along a deterministic fan, an SVG underlay draws its string to a single convergence point at the ✋, the whole cluster sways gently as one (balloons and strings together, so nothing detaches), and clicking a balloon releases it.

Zero new dependencies — Tailwind and a handful of CSS keyframes. The cart logic didn't change at all; only the presentation did, so the 5-second game sync and optimistic updates carried straight over.

Addendum: the splash stopped shouting

Round two of feedback: the link-code form dominated the splash page. Now the hero leads with the bouquet itself and two buttons — the form lives in a compact section at the end of the story, and it no longer steals focus (literally: its autofocus was yanking the scroll position). The site also grew a proper identity for sharing: an AI-generated OG banner and a red-balloon favicon, so links to balloonblox.com unfurl with balloons instead of a gray box. Meanwhile in-game: every challenge got exit pads and a 'give up' button on the run timer, and the Lava Hop's jump gaps were retuned after its first jump turned out to be a physics exam.

Two more pieces of playtest feedback: the text floating over every stand-here pad was clipping into the pads themselves, and the world was — quote — 'a maze and obby in the middle of nowhere.' Fair. The challenges were placed on an infinite gray baseplate with all the atmosphere of a parking lot.

Labels first

All nineteen pad labels got one shared treatment: raised well above head height, put on a rounded translucent pill instead of naked stroked text, and size-capped so distant labels don't balloon (sorry). The zone countdown got the same pill and now floats above the name label instead of fighting it.

Then, a world

The park generator (roblox/build/build_park.luau) rebuilds the whole setting in one run: a terrain hill ring with a tree line for a horizon, a pond, cobbled paths from the plaza to every challenge, lamp posts with warm globes and sagging string lights, balloon clusters on every other pole, bunting in brand colors, benches, a marble fountain with a particle spray, forty-odd procedural trees (with exclusion zones so none spawn inside the maze — or, as discovered on the first run, inside the shop), pastel townhouse facades glowing behind the shop, and a sky full of drifting hot-air balloons and clouds riding the existing moving-platform service at very slow periods. Plus a proper sunset skybox.

The web side got personal too: the builder now shows your actual Roblox avatar (public thumbnail API, no auth) in the header and holding your bouquet at the string convergence point — plus a Play-on-Roblox button on the splash, whose logo now always leads home.

New players were dropped into Balloon Park with no idea what the pads, kiosk, or vault meant. Now a first-join tutorial walks them through it — and because this is a balloon game, the guide arrow is literal: a golden balloon bobbing over each target with a pulsing ring beneath it, connected to your hand by a curved string beam. Follow the string.

End on the dopamine

The step order is deliberate: grab a basic balloon, link the web builder, peek at the Rare Vault's padlocked pedestals — and then the finale isn't a lecture, it's a win. The new Starter Hop is five friendly platforms just past the vault, beatable in ~30 seconds by anyone, and it awards a brand-new rare: the chrome Silver Balloon, through the exact same server-validated challenge machinery as the maze, lava, and tower (a tags-and-config addition — zero new challenge code).

Completion persists in Postgres next to the unlocks (one extra field on the same join-time fetch), so returning players never see the tutorial again — verified by winning the hop, rejoining, and watching nothing happen. The whole flow was E2E-tested in a live session: dwell-add → link signal → vault visit → a legitimately-walked Starter Hop run → silver in the database, on the vault pad, and in the web builder.

The link-code flow asks players to read a URL off an in-game modal and type it into a browser within 15 minutes. balloonblox.spmhresearch.org was a mouthful; balloonblox.com is now the canonical address. The old domain still routes here, so nothing breaks — but every user-facing surface now shows the short one.

That meant touching every place a human reads the URL: the kiosk link modal (one shared Config.WEB_URL constant in the game — changed once, shown everywhere), the tutorial's 'link the web builder' step, the empty-cart HUD hint, and the site's own OG metadata so shared links unfurl under the new name. The game-to-API sync calls didn't change at all — servers don't care how long a hostname is.