Yarn Bounce — Documentation

Important: Template / Starting Point

This asset is a template and starting point for your own game. It provides the mechanic, the level pipeline, 500 ready levels and a full LiveOps backend, and it is expected that you customise, extend and rebrand it. It is not a finished, ready-to-publish product — the store listing, artwork, ad unit IDs, signing keys and store products are yours to supply.

Overview

Yarn Bounce is a colour-matching puzzle. Each level is a picture made of polyomino patches, and a row of glass dispensers holding coloured spools. The player empties the dispensers into the picture, one volley at a time, until every patch is sewn.

Everything that differs between levels lives in a single ScriptableObject. The machine, camera, lighting, VFX and animation all come from shared prefabs, so a new level is a new asset and zero lines of code.

Two editor tools — curate levels by hand, or generate them in bulk with ranged settings.
Verified levels — nothing is written to disk until a solver has proved it can be cleared.
LiveOps included — economy, ads, IAP, daily rewards, quests, battle pass, minigames and more, through the kit documented below.

Getting Started

Requirements

Unity 6 or newer
Universal Render Pipeline (URP), Linear colour space
TextMesh Pro (included with Unity)

Installation

Import the Yarn Bounce package into your project.
When prompted, import TMP Essential Resources (Window › TextMeshPro).
Open Assets/YarnBounce/Scenes/YarnBounce_Game.unity for the gameplay scene, or the kit's Starter Menu scene for the full app flow.
Press Play.

Quick Test

In Play mode, tap a dispenser whose top spools share a colour. They roll onto the plunger. Tap the plunger to fire. Each spool homes to a matching uncovered patch cell and sews it. Clear every patch to win the level.

The plunger chamber is strictly single-colour. Tapping a second colour while it is loaded is refused — that is the core constraint the puzzle is built on.

Folder Structure

YarnBounce/
├── Editor/                    the three buyer-facing tools plus their engine
│   ├── YarnLevelEditorWindow.cs          Manual Level Editor
│   ├── YarnAutoLevelGeneratorWindow.cs   Auto Level Generator
│   ├── YarnWelcomePopup.cs               Welcome
│   └── YarnLevelCatalogEditor.cs         level engine (no menu item)
├── Levels/                    the golden showcase board, kept untouched
├── Materials/  Meshes/  Textures/  Shaders/
├── PowerUps/                  power-up definitions
├── Prefabs/                   YarnMachine, YarnSpool, VFX
├── Resources/Levels/          the 500 shipped levels + the catalogue asset
├── Scenes/                    YarnBounce_Game.unity
├── Settings/                  palette + machine themes
└── Scripts/
    ├── Board/                 grid, shapes, layer peeling
    ├── Core/                  game root, level manager, input, LiveOps adapter
    ├── Data/                  level asset, generator, solver, balancer, palette, theme
    ├── Mechanics/             dispensers, plunger, homing, socket row
    ├── PowerUps/              power-up adapter
    └── Visuals/               camera rig, HUD, VFX, themed parts

Gameplay

Core Mechanics

Dispensers — vertical glass tubes of spools. Tapping one rolls its top run of same-coloured spools onto the plunger.
Plunger — a single-colour chamber. Tap it to fire a volley.
Homing — each spool flies to a matching, uncovered patch cell and sews it.
Layers — patches can be stacked, and a patch can only be sewn once nothing physically covers it, so a layered picture peels top-down. The 500 levels that ship are all single-layer; layers are an authoring feature you can use, set per patch in the Manual Level Editor. See Level Variation.
Mystery patches — start blacked out with "?" marks and reveal their real colour once uncovered.
Holes — a spool with no valid target plugs a hole in the socket row.

Win & Lose Conditions

Win — every patch on the board is sewn.
Lose — every hole in the socket row is plugged.

Two per-level rules soften this, both editable in the Manual Level Editor: Guard Impossible Taps blocks tapping a dispenser whose colour has no reachable patch, and Recycle Unmatched Spools rolls a spool with no target back into the chamber instead of plugging a hole.

Scripts Reference

All game scripts use the YarnBounce namespace; editor tools use YarnBounce.EditorTools.

Core Scripts

Script	Description
`YarnGameRoot`	Owns a running level: builds the board, wires the machine, routes taps, raises the gameplay events.
`YarnGameManager`	Binds the campaign level, settles win/lose exactly once, credits the reward and shows the results overlay.
`YarnLevelManager`	Facade over the kit's progression keys — selected level, completed levels, unlock state.
`YarnLiveOpsAdapter`	Bridges gameplay to the LiveOps backend (quests, battle pass, analytics).
`YarnLevelAsset`	One level: grid, patches, dispensers, rules. Also validates itself.
`YarnLevelGenerator`	Procedural board builder used by the Auto Level Generator.
`YarnLevelSolver`	Proves a board can actually be cleared. Nothing ships unsolved.
`YarnLevelAutoBalancer`	Rebuilds dispenser supply so it exactly matches patch demand.
`YarnLevelCatalog`	The ordered campaign, stored as level asset names.

Utility Scripts

Script	Description
`YarnCameraRig`	Frames the board for any aspect ratio, reserving bands for the HUD and the ad banner.
`YarnPalette` / `YarnMachineTheme`	Spool colours, and the machine's visual identity.
`YarnPowerUpAdapter`	Implements the four power-up effects against the running board.
`YarnHaptics`, `YarnTween`, `YarnEase`	Small helpers for feel.
`YarnVfxPool`, `YarnVfxBurst`, `YarnThreadTrail`	Pooled effects for sewing, clearing and revealing.

Editor Scripts

Script	Description
`YarnLevelEditorWindow`	Manual Level Editor — `Tools › Yarn Bounce › Manual Level Editor`.
`YarnAutoLevelGeneratorWindow`	Auto Level Generator — `Tools › Yarn Bounce › Auto Level Generator`.
`YarnWelcomePopup`	Welcome window — `Tools › Yarn Bounce › Welcome`.
`YarnLevelCatalogEditor`	The engine both level tools are built on. No menu item.

Manual Level Editor

Opening the Manual Level Editor

In the Unity menu bar, go to Tools › Yarn Bounce › Manual Level Editor. This opens a dedicated editor window — no need to enter Play mode.

Features

Campaign list — browse, duplicate, delete and reorder levels in the left panel.
Clickable board — the level is edited by clicking cells, not by typing coordinates.
Patch inspector — layer, colour swatches, mystery toggle, and a warning when a patch is split into disconnected pieces.
Dispenser view — every tube's spools drawn in order, with a live demand-vs-supply readout.
Auto-Balance Supply — rebuilds the tubes so supply exactly matches the patches on the board.
Rules — plunger capacity, tap guarding, spool recycling, cabinet recolour.
Validate — runs the full structural check and the solver, and reports in the window.
Finished fabric preview — a small picture of the level with every patch sewn.
Undo — Ctrl+Z (Cmd+Z on macOS) steps back through every edit; Ctrl+Shift+Z redoes. A whole drag counts as one step.

Undo covers the board, not the file. Ctrl+Z reverses edits to the level you are looking at — painting, erasing, latching, adding or deleting a patch, Auto-Balance, the rules and booster fields. It does not reverse Save All, Delete from the campaign list, or Reload from Disk, all of which touch the files themselves.

Edit Modes

Mode	Click Action
Select	Click a patch to select it. Its colour, layer and mystery flag appear below.
Patch	Click cells to add them to the selected patch, or click its own cells to remove them. Drag to paint a run; the whole drag undoes as one step.
Wall	Click a cell to make it a wall — no patch may occupy it.
Erase	Click to remove a wall, or a cell from the patch that owns it.
Latch	Click a patch to latch or unlatch it. A latched level must grant UNPICK — see Level Variation.
Mystery	Click a patch to hide or reveal its colour.

Painting a cell that another patch already owns on the same layer is refused with a message naming the patch that owns it, rather than silently creating an overlap the validator would reject later.

Level Storage

Levels are ScriptableObjects in Assets/YarnBounce/Resources/Levels/, named YarnLevel_001.asset, YarnLevel_002.asset and so on, loaded at runtime through Resources. Pressing Save All renumbers the assets on disk to match the order in the list, so the campaign's order is the file numbering. The catalogue asset beside them is rewritten from that result.

There is deliberately no "generate the whole campaign" button in this window. Bulk creation lives in the Auto Level Generator, behind its own confirmation dialog.

Automatic Level Generator

Batch-creates levels. Every setting is a min/max range and each level rolls its own value inside those bounds, which is what makes one press produce a varied campaign rather than N copies of the same board.

Opening the Tool

In the Unity menu bar, go to Tools › Yarn Bounce › Auto Level Generator.

Settings

Setting	Description
Levels to generate	How many levels this run produces.
Colours (Min/Max)	Palette colours per level. More colours means more dispenser reading, which is the real skill.
Grid Width / Height (Min/Max)	Playable board size in cells.
Layers (Min/Max)	How many stacked layers the picture peels through.
Patch Cells (Min/Max)	Size of each polyomino patch. Smaller patches pack more colours into the same area.
Mystery Patches (Min/Max)	How many patches start hidden.
Tube Capacity (Min/Max)	How many spools a dispenser holds.
Board Fill % (Min/Max)	How much of the grid height the picture occupies.
Mirror Symmetry % (Min/Max)	Chance a board is mirrored left/right. Symmetry reads as "composed".
Walls % (Min/Max)	Share of the grid painted as walls — cells no patch may occupy. Rises with difficulty.
Latched Patches % (Min/Max)	Share of patches that ship latched. Rises with difficulty, and every level that latches also grants the UNPICK that answers it. See Level Variation.
Difficulty Curve	How fast the ramp climbs across the run. 1.0 is linear; the default 0.4 climbs faster early, because a linear ramp spends most of a long campaign being too easy.
Seed	Seeds the whole run. The same seed with the same settings and the same included themes reproduces the same campaign — which is how you get back a set you liked after pressing Generate again. Randomise draws a new one.
Mode	Append adds to the end of the campaign. Replace deletes every existing level first, and asks you to confirm with the real counts before it does.

The line above the green Generate Levels button always names both numbers — how many levels this run writes, and how many are on disk right now — so you can see whether you are about to append or to destroy before you press it.

How It Works

Themes are the sources. Every machine theme in Assets/YarnBounce/Settings/ is listed with a colour swatch and an include toggle, so you can see what will be used and exclude individual themes before pressing anything. Generated levels take a theme in turn.
Each level rolls its own settings inside your min/max ranges.
The board is generated, and its dispenser supply is balanced against patch demand.
It is then verified — structure first, then the solver. A board that cannot be cleared is re-rolled, and after enough failures it falls back to a guaranteed-clearable board and says so in the run report. The re-rolls are drawn from the run seed, so the whole run stays reproducible.
Duplicates are rejected. A board whose content fingerprint already exists in the campaign is thrown away and re-rolled rather than shipped as filler.
Only then is it written, and numbering is assigned on success, so a skipped level never leaves a hole in the sequence.

A run reports in the window: how many levels were written, how many were skipped and why, and how many duplicates were re-rolled. Nothing is ever saved with a warning.

Append or Replace

Choose between append mode, which adds levels after the existing ones, and replace mode, which deletes every level asset currently in the campaign first. Both ask for confirmation before doing anything. Use append to add content safely.

Power-Ups

Three power-ups ship with the game. None of them can make a board unwinnable, and an invalid use consumes nothing.

Power-Up	Effect
Hole Punch `yarn_hole_punch`	Clears plugged holes out of the socket row, undoing wasted yarn.
Re-Spool `yarn_respool`	Reshuffles dispenser contents so a new colour becomes reachable.
Unload `yarn_unload`	Empties the plunger chamber, returning its spools to the dispensers.

Each shows a tutorial on first use, checks an eligibility gate, and is consumed exactly once on a valid use. Counts and tutorial state persist through the kit's save system.

Adding a Power-Up Adapter

Add a power-up definition asset under Assets/YarnBounce/PowerUps/ with a new id.
Register a handler for that id in YarnPowerUpAdapter, alongside the three existing ones.
Return a refusal reason when the effect cannot apply — that is what stops the count from being consumed.

Level Variation

A five-hundred-level campaign needs level 400 to feel different from level 4, and that difference comes from three families, introduced one at a time. The numbers below are measured from the level assets on disk, not read off a generator setting — a generator threshold is a floor, not a promise about what was actually written.

Family	First shipped level	What changes	Counter-booster
Mystery patches	Level 8 in 492 of the 500	The patch starts blacked out under a "?" and reveals its real colour only when nothing covers it. You cannot plan a volley for a colour you cannot see yet.	— none needed; the reveal is free
Latched patches	Level 18 in 474 of the 500	The patch is latched shut and refuses yarn until it is unpicked, so the peel order is forced rather than chosen.	UNPICK, unlocked at level 4
Walls	Authoring only no shipped level uses them	Cells no patch may occupy, so the picture is cut into separate regions. Paint them with the Wall tool, or raise Walls % in the Auto Level Generator.	—

The counter-booster always unlocks before the mechanic it answers. UNPICK is available from level 4 and the first latched patch appears at level 18. If you move the latch ramp earlier — by regenerating with a higher Latched Patches % at low difficulty, or by painting a latch into an early level by hand — move UNPICK's unlock with it. A latched patch on a level that grants no UNPICK has no counter-move, and the Manual Level Editor refuses to validate it.

How the ramp is produced

The Auto Level Generator lerps every min/max pair across the run, shaped by Difficulty Curve (default 0.4, deliberately sub-linear — a linear ramp spends most of a long campaign being too easy). Mystery Patches and Latched Patches % are the two ramps that produce the families above; both start at zero, which is why the opening levels are plain.

The first eight levels are a stated table, not a curve. A level's size is a product — region width × region height — so nudging the ranges lands the total wherever the product happens to fall, which is how a campaign ends up with a tutorial the same size as level 300. The shipped campaign states those eight sizes outright and the rest of the run ramps from there. If you regenerate, the opening is regenerated from the same table.

Because the ramp is a probability and not a schedule, the first level a family actually appears on is whatever the generator wrote. After regenerating, re-measure it rather than quoting the setting — and re-check the unlock levels of the boosters that answer it.

Layers

Patches carry a layer (1–4) and a higher layer physically covers a lower one, so a layered picture has to be peeled top-down. Every level in the shipped campaign is single-layer; the field is there for you. Set it in the Manual Level Editor's Selected Patch panel, and remember that a covered patch cannot be sewn — the solver will reject a board whose lower layers can never be reached.

Customization Guide

Day Two: the first things to change

Identity — product name, company and bundle id in Player Settings.
Colours — edit YarnPalette_Main in Assets/YarnBounce/Settings/. Every level indexes into it, so one edit repaints the whole campaign.
Machine look — duplicate a YarnTheme_* asset, change its colours, and it appears in the Auto Level Generator's source list automatically.
Levels — generate a fresh campaign, or curate the shipped one.
Backend — work through the kit sections below for economy, ads, IAP and LiveOps.

Adding a Level

Open Tools › Yarn Bounce › Manual Level Editor.
Select a level close to what you want and press Duplicate.
Paint the patches, set colours and layers, press Auto-Balance Supply.
Press Validate This Level until it reports valid and solvable.
Press Save All.

Adjusting Difficulty

More colours and more layers are the two strongest difficulty levers.
Smaller Patch Cells pack more distinct patches into the same board.
A smaller Plunger Capacity forces shorter volleys and more planning.
Turning off Guard Impossible Taps makes wasted yarn possible, which is much harsher.

Changing Audio

Sound is played through the kit's audio engine from a single sound bank asset. Swap a clip in the bank and every cue that uses it changes; see Audio Engine.

Level Format

A level is a YarnLevelAsset ScriptableObject. The fields that matter:

levelLabel      "Level 12"
gridSize        (6, 8)          playable grid in cells, origin bottom-left
boardOffset     (0.24, -0.38)   shifts the board inside the cabinet

shapes[]                        the picture, one entry per patch
  label       "Patch 3"
  layer       1                 1 = bottom of the stack
  colorIndex  2                 index into YarnPalette_Main
  mystery     false             starts blacked out with "?" marks
  cells[]     [(2,3), (3,3)]    grid cells this patch covers

tubeCapacity    12              spools per dispenser
tubes[]                         element 0 is the BOTTOM of the tube
  spools[]    [2, 2, 0, 1]      palette indices

launcherCapacity        6       plunger chamber size (single-colour)
guardImpossibleTaps     true
recycleUnmatchedSpools  true
cabinetAccentBlend      0..1    0 keeps the painted cabinet, 1 recolours it
paletteOverride / themeOverride  optional per-level look

Supply must exactly match demand: the total spools across all tubes must equal the total patch cells on the board, per colour. Auto-Balance Supply in the Manual Level Editor enforces this for you.

Yarn Bounce — Common Issues

Issue	Solution
No levels load, or only one level appears	Check that level assets exist in `Assets/YarnBounce/Resources/Levels/` alongside the catalogue asset. Use the Auto Level Generator to create more.
Pink / magenta machine	The project must use URP with a URP asset assigned in Project Settings › Graphics. Yarn Bounce ships URP shaders.
Text is missing or shows boxes	Import TMP Essential Resources: Window › TextMeshPro › Import TMP Essential Resources.
Manual Level Editor shows an empty list	Press Reload from Disk, and confirm the catalogue asset exists in `Resources/Levels/`.
Auto Level Generator lists no themes	It scans `Assets/YarnBounce/Settings/` for machine theme assets. Press Refresh after adding one.
A generated level was skipped	The solver could not clear it within the attempt budget. Widen the ranges — more colours with very small patches is the usual cause.
Level says supply does not match demand	Press Auto-Balance Supply in the Manual Level Editor.

Support

Stuck on something this manual doesn’t cover? Reach out — real answers from the developer, usually within two business days.

Email: satisvizion@gmail.com

To get the fastest turnaround, include:

Unity version, target platform, and render pipeline;
the level number and, where relevant, the level asset involved;
whether it reproduces from the Manual Level Editor, the Auto Level Generator, or in play;
console output around the failure.

Questions about the menu, ads, in-app purchases, boosters, daily rewards or any other backend system belong in the HyperCasual LiveOps Kit manual, which ships alongside this one.