The game formula

Game themes are not skins. A skin recolors buttons; a game theme turns platform work into a play loop — and it works because the underlying activities are already game-shaped. You claim territory (zones), you build and launch things (apps), things grow (capacity, fleets), and sometimes things explode (Failed). This page explains why the theme specification's game profile is shaped the way it is, so theme authors — human or AI — make good choices inside it.

TL;DR

A theme has one job: attract your engineers onto the platform. Pick a concept they'll actually enjoy, then let Claude Code build it:

Build a theme contract game theme called reef-run where zones are coral reefs and
apps are fish. Read https://konstruct.civo.com/docs/konduit/theme-spec and
https://konstruct.civo.com/docs/konduit/creating-a-theme first, and start
from https://github.com/konstructio/theme-starter — keep
static/theme.js byte-for-byte. Write theme-manifest.yaml before any code,
keep the metaphor honest (a Failed app is always one click from its logs),
make the ship moment skippable, and work through every item in the spec's
checklist. Then create a project named reef-run in our GitLab group
<your-org/group> and push it.

Swap the name and metaphor for whatever your team is into, register the repository from Themes, and the platform builds and serves it.

Why this works on this audience

The goal of a theme is to attract your engineers onto the platform. Coming up with a concept that entertains them, or that cares about their actual interests and immediate needs, is the fastest way to win immediate favor — pick the world your team already jokes about at standup and they'll launch the theme just to look around, then stay because their real work lives there.

That audience grew up on Minecraft, SimCity, Mario, and Lego — pixel art and isometric city builders feel like home, not like a gimmick. The same audience has a strong nonsense detector: the moment a metaphor hides real state or a mechanic wastes their time, the theme is dead to them. The formula threads that needle: real work, honestly represented, wrapped in a world worth caring about.

Three simple needs do most of the work: I'm getting better, I choose how, and others can see it. A good theme feeds all three from real platform activity — shipping apps is real progress; picking your metaphor and cosmetics is the choosing; the universe view is what the rest of the team sees.

People also play differently: some chase progress, some poke into corners, some just want a world worth showing off. A theme rewards all three at once — visible progress, hidden things to find, a shareable world — and the formula's levers cover that mix by design.

Ship It!, deconstructed

The reference game theme does five things worth copying:

1. The launch cinematic is the payoff. Shipping an app — the platform's most valuable action — is the theme's biggest moment: countdown, ignition, liftoff. The celebration is proportional to the value of the act. This is "juice": the game answers your action with more feedback than strictly necessary, and the action feels great.
2. The metaphor maps, it doesn't hide. Planets are zones with real capacity; rockets are apps with real phases. Failed is "splashed down" — playful, still obviously wrong, and one click from the build logs.
3. The character is yours. You name the hero and dress them — species, helmet, suit, cape, gadget. Naming and tending something creates attachment far out of proportion to the pixels involved (the same effect that makes people love a Tamagotchi or their Animal Crossing island — and effort invested makes people value the result more).
4. Progress is permanent and global. XP lives on the platform character, not in the theme. Play Ship It! for a month, open a different theme, and you're still level 12.
5. The galaxy grows. Every planet claimed and rocket launched adds to a screen that looks better every week you work.

The seven levers

Every lever maps to a manifest section. Pull the ones the theme declares; pull them honestly.

Lever	What it is	Manifest home
Progression	XP, levels, quests that walk the player through real platform features	progression
Customization	A character you name and dress; cosmetics with sources (free, quest, level)	character
Spectacle	The ship moment — the theme's signature celebration	shipMoment
Collection	Cosmetics, unlocks, inventory — things to have and display	character.cosmetics
Building	A world that visibly accretes as real infrastructure grows	universeView.growthRule
Surprise	Easter eggs, ambient events, scenery that changes when you don't expect it	surprises
Showing off	One screen composed to be worth showing to someone else	universeView

Three design notes on the subtle ones:

Surprise is the cheapest fun per line of code. A night race on a Friday ship. A blimp on your tenth deploy. Weather. Developers have loved hidden things since the Konami code — an easter egg respects the player's curiosity, and an undocumented one gives them a story to tell. That is why the spec has an easterEggBudget and forbids documenting them.

Building is the lever that compounds. Achievements plateau; a world that grows never does. The universe view must obey one rule: it only accretes. The player who returns after a month must see a visibly bigger world than the one they left — that difference is the reason to keep shipping here rather than anywhere else.

Showing off is the quiet one. Wordle's share grid, a Strava map, a Factorio megabase screenshot — the artifact is clean, legible, and flattering to its maker, and it takes one tap to produce. The universe view's data overlay defaults off for exactly this reason: the default frame is the beautiful one.

The invariants

These are the plain-English versions of the checklist's requirements — the spec gives the exact wording; this list is the why:

• Every theme has a metaphor, and the metaphor never lies — Failed is always findable.
• Shipping is always celebrated, in every profile — and a Friday ship is always a big deal.
• Every phase transition has a word in the theme's vocabulary.
• The world only gets bigger.
• There is always something free in the shop.
• There is always at least one thing the player didn't expect.
• XP only goes up, and it belongs to the player, not the theme.

If the invariants compress to one sentence: the fun must be honest (tied to real work), respectful (never blocking, always off-switchable), earned (spectacle scaled to achievement), and ownable (you built it, you named it, you can show it off).

Anti-patterns

Gamification fails in predictable ways — points, badges, and leaderboards bolted onto a chore make software feel more like work, not less. In a theme contract theme:

• No grind. XP comes from real platform actions at honest rates. Never add busywork whose only purpose is XP.
• No function behind fiction. Everything purchasable with real money maps to real capacity (zones, upgrades) at rate-card prices; everything cosmetic is free, quested, or leveled. Never gate a platform capability behind game progress.
• No blocking spectacle. Celebrations are skippable, never stand between the player and their next action, and can be turned off entirely. A deploy pipeline that makes you watch a cutscene is a deploy pipeline you disable — give the player that switch before they go looking for it.
• No metaphor fog. If an operator can't answer "which app is down and why" within one interaction from anywhere in the theme, the metaphor has failed.
• No patronizing. This audience knows it's being gamified. Wink at them — tech in-jokes, honest numbers on demand, an escape hatch to the plain view (eject is always there).
• No dark patterns. No streak anxiety, no FOMO timers, no daily-login rewards. The theme should be a reason to enjoy shipping, never a reason to feel bad about not shipping.

Calibrating a new theme

When designing (or generating) a theme, prefer:

• Build-something metaphors — racing empires, lego cities, minecraft villages, space colonies — over combat or competition. Building matches what the platform actually does and gives the universe view its growth.
• Aesthetics from home — pixel art, isometric builders, terminal retro — or konstruct-native styling that matches the platform's own design language when the theme is meant to feel professional.
• Short, dense celebration over long animation. Six seconds of great beats twenty seconds of good. Borrow Peggle's trick: a brief beat of anticipation before the payoff makes the same payoff land harder.
• Spectacle scaled to rarity. Routine successes get a light touch; the full fireworks are reserved for the genuinely big moments — a first zone, a Friday ship, a hundredth deploy. A fanfare that plays every time is a fanfare that means nothing.
• Metaphor words that survive standup. "The storefront car is in the gravel trap" must be sayable by an adult in a meeting. If the vocabulary would embarrass the player in front of a colleague, soften it.

What's next

1. Theme specification — the spec these principles feed
2. Creating a theme — the authoring guide