# Glitch Bomb Documentation

> Official Glitch Bomb documentation covering gameplay, game rules, ranked rewards, staking, referrals, contracts, and common questions.

## Contracts

Glitch Bomb is fully onchain: the game engine, the token, staking, and governance are Cairo contracts built with [Dojo Engine](https://dojoengine.org) on [Starknet](https://starknet.io). The source lives in the [cartridge-gg/glitchbomb](https://github.com/cartridge-gg/glitchbomb) repository under `contracts/`.

### Systems

| Contract       | Role                                                                                                                                 |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| **Play**       | The game engine: create a game, pull orbs, buy/burn/refresh in the shop, enter levels, cash out, claim rewards                       |
| **Setup**      | Admin configuration: entry price, vault revenue share, starter pack registration                                                     |
| **Token**      | The **GLITCH** ERC-20 reward token, minted on reward claims                                                                          |
| **Vault**      | The staking vault: an ERC-4626 vault issuing **vGLITCH** shares, distributing a share of game revenue to stakers, with vote tracking |
| **Governor**   | OpenZeppelin governor using vGLITCH voting units, with delay, period, and quorum settings                                            |
| **Treasury**   | Timelock controller executing approved governance proposals and holding protocol funds                                               |
| **Collection** | ERC-721 collection — each ranked game is a token                                                                                     |
| **Faucet**     | Test USDC faucet used on test networks                                                                                               |

### Game state

The full game state fits in a single compact model, updated on every action:

* the **bag** is a packed list of orb ids (up to 50 orbs)
* **pulled orbs** are tracked as a bitmap — one bit per orb slot; the Bomberang's bit is never set, which is what makes it "sticky"
* **curses** are bit flags on the game
* the **shop** packs its 6 offers, the burn/refresh flags, and per-orb purchase counters into one field

Every pull, purchase, and level transition is emitted as an event and indexed by [Torii](https://dojoengine.org/toolchain/torii), which is what the game client renders in real time.

### Randomness

Ranked pulls are seeded by [Cartridge VRF](https://docs.cartridge.gg/vrf/overview), a verifiable random function whose output is proven onchain — see [Randomness](/game-rules/randomness).

### Determinism and the practice engine

The game rules are deterministic given a seed, which allows the client to embed a TypeScript mirror of the Cairo engine for free practice games — same milestones, prices, and bag mechanics, no transactions required.


## FAQ

### Playing

#### How do I win?

Complete the level 7 milestone. But "winning" isn't the only good outcome — most successful runs end with a well-timed **cash out**. Your final score is your moon rock balance, however the run ends.

#### What happens when I die?

At 0 HP the run ends immediately. Your current points are lost, but you keep all the moon rocks you collected during the run — that balance is your final score.

#### Should I cash out or continue?

Continuing converts your points into bits (shop money) instead of moon rocks (score), costs an entry fee, and exposes you to new curses. The [reward curve](/game-rules/rewards) is steeply exponential, so deep runs pay disproportionately — but a bust near the end can leave you below where a safe cash out would have. That tension is the game.

#### Why did a bomb come back after I pulled it?

That's the **Bomberang** — a sticky bomb that returns to the bag after every pull. It's added to your bag by the level 6 curse. See [Bombs & curses](/game-rules/bombs-and-curses).

#### Why did my multiplier reset?

The multiplier resets to 1.00x every time you leave the shop, along with your health being restored. Multipliers are a per-level resource — build them early in each level.

#### My whole bag came back — is that a bug?

No: when every non-sticky orb has been pulled, the bag regenerates and everything becomes pullable again for the rest of the level.

### Ranked & rewards

#### What does it cost to play ranked?

Entries are sold as starter packs: tier `N` costs `N × $2` USDC and pays rewards at roughly `N`x. A free pack is available by completing a social task. See [Rewards](/game-rules/rewards).

#### Who can play ranked?

Ranked mode requires being **18+** and located in an eligible region — the app verifies eligibility before purchase. Practice mode is open to everyone.

#### What's the minimum score that pays out?

**65 moon rocks.** Below that, the reward is zero. You start with 100, so a run that ends early can absolutely finish below the payout floor.

#### Do my runs expire?

Yes — a ranked game must be finished within **24 hours** of starting.

#### What is GLITCH?

The game's ERC-20 reward token on Starknet. It's minted when you claim game rewards, and it can be [staked](/staking) to earn a share of game revenue.

### Support

#### Where do I get help?

* Discord: [discord.gg/cartridge](https://discord.gg/cartridge)
* X: [@cartridge\_gg](https://x.com/cartridge_gg)

#### Where's the code?

Everything — contracts, client, and these docs — is open source at [github.com/cartridge-gg/glitchbomb](https://github.com/cartridge-gg/glitchbomb).


## Referral program

Invite new players to Glitch Bomb and earn a fee on what they spend.

### How it works

* every player gets a personal **referral link**, available from the referral screen in the game client
* when someone buys a starter pack through your link, you earn **5% of the purchase price**, paid in the purchase currency
* the fee applies to every eligible purchase your referrals make — not just their first

### Tracking your earnings

The referral screen in the client shows:

* **Players** — how many players joined through your link
* **Games** — how many games they have played
* **Total earned** — your accumulated referral fees, with a detailed payment history

### Sharing your link

Copy your link from the referral screen and share it anywhere. The referral is attached when the new player opens the game through your link and makes a purchase.

:::tip
Pair your referral link with the free social starter pack: new players can try ranked play for free, and your fee kicks in as soon as they buy their first paid pack.
:::


## Release notes

Notable changes to Glitch Bomb, newest first.

### Current release

* Full onchain ranked mode on Starknet, with practice and tutorial modes playable free everywhere
* 7-level runs with milestones, curses, and the shop
* 21 orb types, including the Bomberang and dynamic point orbs
* Starter packs (tiers 1–10) with reward multipliers, plus a free social pack
* GLITCH staking vault and referral program
* iOS App Store shell

*Check back here after each update for gameplay and balance changes.*


## Staking

GLITCH holders can stake their tokens in the **vault** to earn a share of game revenue.

### How it works

The vault is an [ERC-4626](https://docs.openzeppelin.com/contracts/5.x/erc4626) vault:

* **deposit GLITCH**, receive **vGLITCH** shares representing your stake
* a percentage of every ranked game entry is routed to the vault in the payment token (USDC)
* rewards accrue to stakers **pro-rata to their vGLITCH balance**
* **claim** your accrued rewards at any time the vault is open
* **withdraw** your GLITCH by redeeming vGLITCH shares — an exit fee applies, which stays in the vault and is redistributed to the remaining stakers

:::note
**Vault status and time lock.** Deposits, withdrawals, and claims are only available while the vault is open, and positions are subject to a time lock. Check the staking screen in the app for the current status of your position.
:::

### Voting power

vGLITCH is also the game's **governance token**: your staked balance counts as voting units in the Glitch Bomb governor. Staking is how you get a say in treasury and protocol decisions — see [Contracts](/contracts) for the governance architecture.

### Where to stake

Staking is available directly in the game client, from the staking screen on the home page. It shows your balance, your share of the vault, accrued rewards, and the claim and withdraw actions.


## Bombs & curses

Bombs are the price of greed. Every pull that isn't a bomb makes the next pull more dangerous — and the deeper you go, the more the game stacks the bag against you.

### Bombs

| Bomb        | Damage                    |
| ----------- | ------------------------- |
| Single Bomb | −1 HP                     |
| Double Bomb | −2 HP                     |
| Triple Bomb | −3 HP                     |
| Bomberang   | −1 HP, returns to the bag |

Your health starts at **5 HP** and is fully restored every time you leave the shop. If it reaches 0, the run is over: your points are lost, but you keep the moon rocks collected so far.

:::note
**Bombs are pulled, not disarmed.** A pulled bomb stays out of the bag for the rest of the level (except the Bomberang) — so surviving a bomb makes the remaining pulls safer, and feeds your Point Bomb 4 orbs.
:::

#### Bomberang

The Bomberang is a **sticky bomb**: unlike every other orb, it is never set aside after being pulled. It deals 1 damage and immediately returns to the pullable bag, so it can hit you again and again for the entire level. It also never leaves the bag when the bag regenerates — once cursed with a Bomberang, it's yours for the rest of the run.

### Curses

Curses are permanent afflictions applied to your run as you climb levels. They come in two flavors:

**Rule curses** change how the game plays:

| Curse        | Effect                               |
| ------------ | ------------------------------------ |
| Double Draw  | Every pull draws **2 orbs** at once  |
| Demultiplier | All multiplier boosts are **halved** |

**Bag curses** inject a hostile orb directly into your bag:

| Curse          | Orb added                                      |
| -------------- | ---------------------------------------------- |
| Normal Bomb    | Single Bomb                                    |
| Double Bomb    | Double Bomb                                    |
| Sticky Bomb    | Bomberang                                      |
| Score Decrease | Curse Score Decrease (−20% points when pulled) |

### Curse schedule

Curses are applied automatically when you enter certain levels:

| Entering level | Curse applied              |
| -------------- | -------------------------- |
| 4              | +1 Double Bomb in your bag |
| 6              | +1 Bomberang in your bag   |
| 7              | +1 Double Bomb in your bag |

:::tip
Plan your shop purchases around the schedule: stock up on health before level 6, and remember that the Bomberang makes long point streaks much riskier in the final levels.
:::


## Game rules

Glitch Bomb is a risk-reward game: pull orbs from your moon bag, collect points, avoid bombs, and decide when to bank your winnings.

### Starting a run

Every run starts with:

| Resource   | Starting value   |
| ---------- | ---------------- |
| Health     | 5 HP (maximum 5) |
| Moon rocks | 100              |
| Bits       | 0                |
| Points     | 0                |
| Multiplier | 1.00x            |
| Level      | 1 of 7           |

Your starting moon bag contains **11 orbs**:

* 2× Single Bomb, 1× Double Bomb, 1× Triple Bomb
* 3× Point 5
* 1× Multiplier +1x
* 1× Point Orb 1
* 1× Point Bomb 4
* 1× Health

### The loop

<div className="docs-flow">
  <div className="docs-flow__step">
    <div className="docs-flow__num">1</div>

    <div className="docs-flow__content">
      <strong>Pull an orb.</strong> Each pull draws a random orb from the orbs remaining in your bag and applies its effect immediately. Pulled orbs are set aside and can't be drawn again this level — except the Bomberang, which always goes back in.
    </div>
  </div>

  <div className="docs-flow__step">
    <div className="docs-flow__num">2</div>

    <div className="docs-flow__content">
      <strong>Score points.</strong> Point orbs earn <em>base points × your current multiplier</em>. Multiplier orbs raise the multiplier for the rest of the level.
    </div>
  </div>

  <div className="docs-flow__step">
    <div className="docs-flow__num">3</div>

    <div className="docs-flow__content">
      <strong>Reach the milestone.</strong> Each level has a point threshold. Once your points reach it, the level is complete and you choose what happens next.
    </div>
  </div>

  <div className="docs-flow__step">
    <div className="docs-flow__num">4</div>

    <div className="docs-flow__content">
      <strong>Cash out or continue.</strong> <em>Cash Out</em> converts your points into moon rocks and ends the run. <em>Continue</em> converts your points into bits, opens the shop, and starts the next level — for a moon rock entry fee.
    </div>
  </div>
</div>

### Ending a run

* **Defeat** — your health hits 0. The run ends immediately; your points are lost, but the moon rocks you collected along the way are kept.
* **Cash out** — you bank your points as moon rocks and stop on your own terms.
* **Victory** — you complete the level 7 milestone. The game cashes out automatically.

Your **final score is your moon rock balance**. In ranked games it determines your token reward — see [Rewards](/game-rules/rewards).

:::note
**Bag refresh.** When every non-Bomberang orb has been pulled, the bag automatically regenerates: all orbs become pullable again for the rest of the level.
:::

:::note
**Run expiration.** An onchain game must be finished within **24 hours** of starting.
:::

### Learn more

* [Orbs](/game-rules/orbs) — every orb and its effect
* [Bombs & curses](/game-rules/bombs-and-curses) — what hurts you
* [Levels & milestones](/game-rules/levels) — thresholds and entry fees
* [Shop](/game-rules/shop) — build a stronger bag between levels
* [Practice](/game-rules/practice) — free mode, no stakes
* [Rewards](/game-rules/rewards) — how scores convert into tokens
* [Randomness](/game-rules/randomness) — how draws stay fair


## Levels & milestones

A run spans up to **7 levels**. Each level has a **milestone** — the number of points you must score to complete it — and an **entry fee** in moon rocks paid when you continue past the previous level.

### Milestones and entry fees

| Level | Milestone (points) | Entry fee (moon rocks) |
| ----- | ------------------ | ---------------------- |
| 1     | 12                 | Free                   |
| 2     | 18                 | 1                      |
| 3     | 28                 | 2                      |
| 4     | 44                 | 4                      |
| 5     | 70                 | 6                      |
| 6     | 100                | 9                      |
| 7     | 150                | 13                     |

### Completing a level

Once your points reach the milestone, the level is complete and pulling stops. You then choose:

* **Cash Out** — your points are converted into moon rocks (`moon rocks += points`) and the run ends. Your final score is your moon rock balance.
* **Continue** — your points are converted into **bits** (`bits += points`, points reset to 0), you pay the next level's entry fee in moon rocks, and the [shop](/game-rules/shop) opens.

:::tip
Overshooting a milestone is pure profit: every point above the threshold still converts 1:1 into moon rocks (cash out) or bits (continue). A big multiplier pull right before finishing the level is often worth the risk.
:::

### Entering a new level

When you leave the shop and enter the next level:

* your level increases and a new milestone is set
* your health is **fully restored to 5 HP**
* your multiplier **resets to 1.00x**
* all pulled orbs return to the bag (the discard pile is cleared)
* the level's [curse](/game-rules/bombs-and-curses#curse-schedule) is applied, if any

### Winning

Completing the **level 7** milestone wins the run: the game automatically cashes out your points into moon rocks. There is no level 8 — level 7 survivors sit at the very top of the [reward curve](/game-rules/rewards).


## Orbs

Everything in your moon bag is an orb. Some orbs score points, some boost your multiplier, some restore health, some grant currencies — and some explode. This page lists every orb in the game with its effect and its shop price (in bits) when it can be bought.

### Point orbs

Point orbs earn **base points × your current multiplier**. Points reset to 0 whenever you enter the shop (they are converted into bits) or when you cash out (they are converted into moon rocks).

| Orb          | Effect                                               | Shop price |
| ------------ | ---------------------------------------------------- | ---------- |
| Point 5      | Gain 5 points                                        | 5 bits     |
| Point 6      | Gain 6 points                                        | —          |
| Point 7      | Gain 7 points                                        | 8 bits     |
| Point 8      | Gain 8 points                                        | 11 bits    |
| Point 9      | Gain 9 points                                        | 13 bits    |
| Point Orb 1  | Gain 1 point for each orb still pullable in your bag | —          |
| Point Bomb 4 | Gain 4 points for each bomb pulled this level        | 6 bits     |

:::tip
**Point Orb 1** rewards a full bag — it shines early in a level. **Point Bomb 4** rewards surviving explosions — pulled after a few bombs, it can outscore any flat point orb.
:::

### Multiplier orbs

Multiplier orbs permanently raise your score multiplier **for the current level**. The multiplier starts at 1.00x and resets when you leave the shop.

| Orb              | Effect                         | Shop price |
| ---------------- | ------------------------------ | ---------- |
| Multiplier +0.5x | Boost your multiplier by +0.5x | 9 bits     |
| Multiplier +1x   | Boost your multiplier by +1x   | 14 bits    |
| Multiplier +1.5x | Boost your multiplier by +1.5x | 16 bits    |

### Health orbs

Health orbs restore HP, up to the maximum of **5**.

| Orb           | Effect                  | Shop price |
| ------------- | ----------------------- | ---------- |
| Health        | Restore 1 health point  | 9 bits     |
| Double Health | Restore 2 health points | —          |
| Triple Health | Restore 3 health points | 21 bits    |

### Currency orbs

| Orb         | Effect             | Shop price |
| ----------- | ------------------ | ---------- |
| Moonrock 15 | Gain 15 moon rocks | 8 bits     |
| Moonrock 40 | Gain 40 moon rocks | 23 bits    |
| Bits 15     | Gain 15 bits       | 5 bits     |

Moon rocks are your **score and meta currency** — they pay level entry fees and determine your final reward. Bits are the **shop currency**, spent between levels.

### Bombs and curse orbs

The dangerous side of the bag — bombs deal damage and curse orbs sabotage your score:

| Orb                  | Effect                                                  |
| -------------------- | ------------------------------------------------------- |
| Single Bomb          | Lose 1 health point                                     |
| Double Bomb          | Lose 2 health points                                    |
| Triple Bomb          | Lose 3 health points                                    |
| Bomberang            | Lose 1 health point — and it goes **back into the bag** |
| Curse Score Decrease | Lose 20% of your points                                 |

These orbs cannot be bought — they get added to your bag by curses as you progress. See [Bombs & curses](/game-rules/bombs-and-curses) for details.

### Rarity

Shop orbs come in three rarities, which determine where they appear in the shop lineup:

* **Common** — Point 5, Point 7, Point Bomb 4, Bits 15, Moonrock 15, Multiplier +0.5x, Health
* **Rare** — Point 8, Point 9, Multiplier +1x, Multiplier +1.5x
* **Cosmic** — Moonrock 40, Triple Health


## Practice

Glitch Bomb can be played in two modes: **practice** and **ranked**.

### Practice mode

Practice is completely free and runs the exact same rules as ranked play:

* no entry fee, no rewards — nothing at stake
* available to everyone, everywhere, with no age or region restriction
* runs **locally in your browser**: pulls are simulated client-side instead of onchain
* includes an interactive **tutorial** that walks you through pulls, points, bombs, multipliers, milestones, the shop, and cashing out

Use it to learn the bag, test shop strategies, and get a feel for when to cash out — before putting moon rocks on the line.

:::tip
The practice engine mirrors the onchain game logic orb for orb: milestones, curse schedule, shop prices, and bag behavior are identical. What you learn in practice transfers 1:1 to ranked.
:::

### Ranked mode

Ranked games are played **onchain**. Each game costs an entry fee (see [Rewards](/game-rules/rewards)) and your final score converts into token rewards.

Because ranked play involves real money, it is restricted:

* you must be **18 or older**
* you must be located in an **eligible region** — the app checks your eligibility before you can buy an entry

If ranked play isn't available where you are, practice mode remains fully playable.


## Randomness

Every pull in Glitch Bomb is random — and in ranked mode, verifiably so.

### Ranked games: verifiable randomness

Onchain games use [Cartridge VRF](https://docs.cartridge.gg/vrf/overview) (Verifiable Random Function) to seed each pull:

* the random seed is produced by the VRF provider and **verified onchain** before the pull executes
* neither the player, nor the game developers, nor the sequencer can predict or manipulate which orb comes out of the bag
* anyone can audit the draws after the fact — the entire game state lives onchain

The draw itself removes an orb uniformly at random from the orbs still pullable in your bag. No weighting, no pity timers, no hidden odds: if 3 of the 12 remaining orbs are bombs, your bomb odds are exactly 3 in 12.

### Practice games: local randomness

Practice mode runs entirely in your browser and uses a local pseudo-random generator. The draw logic is identical — same uniform selection over the remaining bag — but there is no onchain verification because nothing is at stake.

:::note
**The bag is the odds.** Because draws are uniform over the remaining orbs, your bag composition fully determines your risk at any moment. Counting what's left in the bag — and shaping it in the shop — is the core skill of the game.
:::


## Rewards

In ranked mode, your final score — your **moon rock balance** when the run ends — converts into **GLITCH** token rewards. The curve is steep: doubling your score multiplies your reward far more than 2x.

### Entering a game

Ranked entries are sold as **starter packs**, in tiers 1 through 10:

* a tier `N` pack costs `N × $2` USDC (tier 1 = $2, tier 5 = $10, tier 10 = $20)
* a tier `N` pack plays with an `N`x base reward multiplier, **boosted by +N%** at purchase (tier 3 plays at 3.09x, tier 10 at 11x)
* a **free starter pack** can also be unlocked by completing a social task (following [@glitchbombgame](https://x.com/glitchbombgame) on X)

A share of every entry goes to the [staking vault](/staking), and the rest to the game treasury.

### The reward curve

The base reward (in GLITCH, for a 1x multiplier) depends on the score tier you reach:

| Score     | Base reward |   | Score    | Base reward |
| --------- | ----------- | - | -------- | ----------- |
| 524 (max) | 1000        |   | 130      | 77          |
| 428       | 720         |   | 124      | 69          |
| 356       | 530         |   | 118      | 61          |
| 300       | 395         |   | 112      | 54          |
| 256       | 300         |   | 106      | 46          |
| 222       | 230         |   | 100      | 40          |
| 196       | 182         |   | 94       | 34          |
| 176       | 147         |   | 88       | 25          |
| 160       | 121         |   | 78       | 13          |
| 148       | 100         |   | 65       | 1           |
| 138       | 88          |   | below 65 | 0           |

Your reward is the highest tier your score reaches: a score of 150 pays the 148 tier, a score of 64 pays nothing.

:::note
**Break-even starts at 65.** Remember you start with 100 moon rocks and spend them on level entry fees — a run that dies early can finish below its starting balance. Cashing out at the right time is the whole game.
:::

### Multipliers

The final payout is:

```
reward = base(score) × multiplier
```

where the multiplier is fixed at purchase time from:

* **your pack tier** — tier `N` with its `+N%` boost
* **a supply factor** — rewards scale down as the circulating GLITCH supply approaches its target: the factor is `(2 × target − supply) / target`, i.e. 1x at target supply, down to 0x at twice the target. This keeps the reward pool sustainable.

### Claiming

When a ranked run ends (cash out, victory, or death), the reward for your final moon rock balance can be **claimed** from the game — GLITCH tokens are minted straight to your wallet.


## Shop

The shop opens every time you continue past a completed level. It's where your points — converted into **bits** — buy a stronger bag for the levels ahead.

### Offers

Each visit, the shop displays **6 orbs**:

* **3 common** — drawn from: Point 5, Point 7, Point Bomb 4, Bits 15, Moonrock 15, Multiplier +0.5x, Health
* **2 rare** — drawn from: Point 8, Point 9, Multiplier +1x, Multiplier +1.5x
* **1 cosmic** — drawn from: Moonrock 40, Triple Health

Every purchased orb is added to your bag permanently for the rest of the run. Base prices are listed on the [Orbs](/game-rules/orbs) page.

### Price scaling

Buying the same orb type repeatedly gets more expensive. Each purchase raises the price of that orb type by **+20% of its base price**, rounded up:

```
price = ceil(base_price × (100 + 20 × purchases_so_far) / 100)
```

Purchase counts are tracked **per orb type across the whole run** — leaving the shop doesn't reset them. For example, Point 5 (base 5 bits) costs 5, then 6, then 7, then 8 bits…

### Shop actions

Besides buying orbs, two actions are available, each costing **4 bits** and usable **once per shop visit**:

* **Burn** — permanently remove one orb from your bag. Bombs cannot be burned — you can't buy your way out of a curse.
* **Refresh** — reroll the shop's 6 offers.

:::tip
Burning is one of the strongest long-term investments in the game: removing a weak Point 5 from your bag increases the odds of every future pull for the rest of the run.
:::

### What persists, what resets

|                                         | On leaving the shop        |
| --------------------------------------- | -------------------------- |
| Bag contents (purchases, burns, curses) | **Persist**                |
| Purchase counters (price scaling)       | **Persist**                |
| Bits balance                            | **Persists**               |
| Shop offers                             | Reset                      |
| Burn / Refresh availability             | Reset (one each per visit) |
| Health                                  | Restored to 5 HP           |
| Multiplier                              | Reset to 1.00x             |