Cup Stack Jam

Overview

Cup Stack Jam is a colour-sorting puzzle. A honeycomb pile of stacked plastic cups sits above two tray slots, each fed by its own queue of coloured trays. Tapping a cup stack merges it with every touching stack of the same colour and feeds the whole group into a matching tray. Cups with nowhere to go park on the pegs — and the pegs are the only thing standing between a careless tap order and a jam.

The whole game is one deterministic, physics-free state machine. Nothing falls, nothing collides, and a level plays out identically every time — which is what lets a headless solver prove every shipped level winnable before it is written to disk.

Getting Started

Requirements

• Unity 6000.0.62f1 or newer
• Universal Render Pipeline (URP) 17.0.4
• Input System package 1.14.2 (the project ships configured for it)
• Linear colour space, portrait orientation

Installation

1. Import the package into a Unity 6 URP project.
2. Import TextMesh Pro's essential resources if the project has never had them: Window > TextMeshPro > Import TMP Essential Resources. Every label in the menu uses TMP, and without them the menu installer fails with a NullReferenceException that does not mention TextMesh Pro at all.
3. Let Package Manager finish resolving. The kit needs com.unity.ugui, com.unity.purchasing, com.unity.mobile.notifications and the built-in com.unity.modules.screencapture.
4. Open Assets/CupStackJam/Scenes/CupStackLevel.unity.
5. Press Play.

Quick Test

With the gameplay scene open, press Play and tap a cup stack in the pile. Every touching stack of the same colour swells, merges into the one you tapped, and starts feeding cups into a matching tray. Deliver every cup and the level is won.

To play the campaign rather than a single level, make Assets/HyperCasualLiveOpsKit/StarterMenu/Scenes/HLK_MainMenu.unity build scene 0 and press Play from there.

Folder Structure

The two folders are separate products. CupStackJam holds this game's mechanic and content; HyperCasualLiveOpsKit holds the menu, economy, ads, IAP and minigames, and is documented in its own Documentation.html.

Gameplay

Core Mechanics

• The pile is a honeycomb grid of cup stacks. Each cell holds a number of cups of one colour, and the number is printed on the top cup.
• Tapping a stack flood-fills every touching stack of the same colour into one merged group, which then feeds cups out one at a time. Where you tap decides how big the merge is — that is the whole puzzle.
• Two tray slots sit at the far end of the board, each fed by its own queue of coloured trays. A tray holds dimple rows × dimple columns cups.
• A cup flies to a tray of its colour if one has room. If not, it parks on a peg. Pegs drain automatically the moment a tray of that colour arrives.
• A full tray seals, sparkles, flies away, and the next tray in that queue slides forward.

Palette Colours

Colours live in Settings/CupStackJamPalette.asset. Each entry carries an id character, a display name, four colours (cup body, lit cap, tray top and tray dimple) and a default tray capacity. The id character is what the level files use, so adding a colour can never renumber the levels already on disk.

Win & Lose Conditions

• Win: every cup in the level has been delivered into a tray.
• Lose: the board deadlocks — cups are still owed but nothing can move, because every remaining cup's tray is unreachable and the pegs are full.

Because a level is only ever lost to a jam, the peg count is the game's tightest difficulty lever — and the reason the Extra Peg booster exists. Across the shipped campaign the pile grows while the peg grid shrinks.

Balance

A level is balanced when, for every colour, the cups in the pile exactly equal the total capacity of the trays that accept them. The economy is zero-slack by design: a cup with nowhere left to go is a loss, not a rounding error. An unbalanced level is unwinnable by construction, and no amount of searching discovers that — which is why the editor checks balance before it runs the solver.

Scripts Reference

Core Scripts

Utility Scripts

Editor Scripts

Level Editor

Opening the Level Editor

Menu path: Tools > Cup Stack Jam > Manual Level Editor

Layout

Two panels. The left lists every level in the campaign, with buttons to add, duplicate, delete and reorder. The right shows the level you have selected: the pile grid on top, the two tray queues below it, and the per-level properties beneath those.

Editing

• Click a pile cell to paint it with the currently selected tool — a colour, a cup count, a cut-out, or a mystery marker.
• Click a queue position to set that tray's colour, or to lock it behind a countdown.
• Undo works with Ctrl+Z and with the Undo button in the toolbar. Both go through Unity's own undo stack, so an edit here behaves like every other edit in the editor.

Validation

• Check Balance reports, per colour, how many cups the pile supplies against how much tray capacity wants them. It runs first because an unbalanced level is unwinnable by construction and the solver would only report "gave up".
• Validate plays the level headlessly and tells you whether it can be won, how many taps it took, how close the pegs came to filling, and how many turns offered a real choice.
• Validate All does the same for the whole campaign and lists every level that fails. File existence is never validation.

Automatic Level Generator

Opening the Generator

Menu path: Tools > Cup Stack Jam > Auto Level Generator

Settings

Seeds

Generation is deterministic. The same seed and the same settings produce a byte-identical campaign, and each level's seed is derived from its own number — so level 250 is the same board whether you generated 250 levels or 500, and re-rolling one level does not shift every level after it.

How a level is built

Backwards, from the trays. The generator chooses the trays first and then fills the pile to match, so the zero-slack balance holds by construction rather than by luck. Rolling a board first and hoping makes an unwinnable level the common case.

The three-stage ladder

No level is ever written without being solved. When one cannot be, the generator degrades in a defined order and names the stage in its report:

The run report lists the loosened and last-resort counts, the duplicate rate, each family's measured first occurrence, and the difficulty trend per fifty-level band. A report that only said "500 written" would hide every one of those.

Boosters

Boosters are catalogue-driven. Each one is a PowerUpDefinition asset in Assets/CupStackJam/PowerUps/ that owns its inventory, persistence, tutorial, arming, sound, haptics and unlock level; the game supplies only what the effect does to the board.

Refusals cost nothing

Every effect returns whether it actually changed something, and the framework consumes a charge only when it did. Shuffling a board with nothing queued, or pressing Unlock with nothing locked, refuses and spends no charge. Reports success and changes nothing is the worst failure a booster can have.

Pull Forward deliberately refuses a locked tray rather than quietly opening it — that is Unlock's job, and doing two boosters' work in one would make both harder to reason about.

Adding a fifth booster

1. Add an IPowerUpEffectHandler to CupStackJamPowerUpAdapter and register it in Awake (and unregister in OnDestroy).
2. Author a PowerUpDefinition asset for it.
3. Raise StarterMenuConfig > Authored Gameplay UI > Booster Slot Capacity and re-run the gameplay UI factory rebuild. The bar's socket count is authored, not dynamic — skip the rebuild and the fifth booster is catalogued, tested and unreachable.

Level Variation

What makes level 90 different from level 9 is not more cups — it is that the content changes. Four families ship, and every one of them is introduced inside the first ten levels, because a player who stops before then would never find out the game has it.

The peg count is a fifth axis and is present from level 1: it is the level's scarce resource, and the campaign tightens it as the pile grows.

Reading the real first occurrence

The generator's thresholds are floors. To find out when a family actually first appears, read Artifacts/Levels/campaign-report.txt, which measures the level files on disk. Configured and measured are routinely different by a level or two.

Customization Guide

Re-skinning the colours

Open Settings/CupStackJamPalette.asset. Each entry has four colours: the cup body, the lit cap, the tray top and the tray dimple. They are separate fields rather than shades of one because the reference art shifts hue differently per colour — one shared darkening factor cannot produce all of them.

Retuning the feel

Open Settings/CupStackJamStyle.asset. Everything about timing, geometry, shading and the camera lives there, shared by every level — so you can retune the whole game without regenerating a single level file.

Framing the board

The style asset carries two reserves: the fraction of screen height the HUD owns at the top, and the fraction the booster shelf and banner own at the bottom. The camera fits the board into the band those leave. They are measurements taken from a played build, not preferences — if you move the HUD, re-measure them.

Replacing the art

Cups, caps, trays, dimples, pegs and hex cells are ordinary prefabs in Prefabs/, each backed by an FBX in Meshes/. Swap the mesh and the game re-measures itself around it: cup height, radius and nesting step are all read off the mesh rather than typed in.

Level Format

One JSON file per level, at Assets/CupStackJam/Resources/Levels/Level_N.json, numbered from 1 with no gaps. The loader walks upward until a file is missing, so a gap silently truncates the campaign — reordering in the editor renumbers the files on disk rather than keeping a separate order list.

Fields

Example

{
    "levelNumber": 2,
    "levelName": "Level 2",
    "boardColors": [ "GGG", "BBGG", "GGB", "BBBG", "GGB" ],
    "boardStacks": [ "233", "2223", "322", "2232", "223" ],
    "defaultStackDepth": 2,
    "trayRows": 2,
    "trayColumns": 2,
    "trayBoxes": [ "GB", "GB" ],
    "trayCapacities": [ "", "" ],
    "trayDimpleRows": 3,
    "trayDimpleColumns": 4,
    "bufferSlotCount": 12,
    "pegCapacity": 4,
    "accessMode": 0,
    "shuffleCount": 3,
    "extraSlotCount": 2
}

The board above is illustrative. Every shipped level is balanced — each colour's cup total equals the capacity of the trays that take it — and has been solved.

Support

Common Issues

Tips

• Keep the opening level as level 1. It is the board the mechanic was derived from and the fixture the tests compare against.
• A locked tray's countdown must cost more than its queue position, or it opens before the tray reaches the front and the lock is decoration.
• Every mystery stack needs at least one ordinary neighbour, or nothing can ever reveal it.
• Re-run Validate All after any bulk edit. File existence is not validation.

Contact Us

If you get stuck or have any issues, feel free to reach out to us at satisvizion@gmail.com. We are happy to help!