Fit Blast

Overview

Fit Blast is a drag-and-drop color-fit puzzle where players pull tetromino-shaped colored blocks from a queue at the bottom of the screen and snap them onto pedestals on the board. Each pedestal clears when two conditions are met at the same time: every cell is filled, and every block on it is the same rendered color. Clear every pedestal to win the level. The game ships with 500 pre-made unique levels on a progressive difficulty curve, a visual level editor, an automatic level generator, three boosters, and a developer debug panel.

Getting Started

Requirements

• Unity 6 or newer
• Universal Render Pipeline (URP)
• TextMesh Pro (included with Unity)
• Input System package (the project uses the New Input System for touch + mouse)
• Active Input Handling set to Both (legacy UI raycasts + new Input System)

Installation

1. Import the Fit Blast package into your Unity project
2. Ensure the project is set to use the Universal Render Pipeline (check Edit > Project Settings > Graphics)
3. Open the game scene at Assets/Fit Blast/Scenes/GameNew.unity
4. Press Play to test the first level

Quick Test

Once in Play mode, pick up any piece from the bottom queue (the start grid) and drag it onto a pedestal. Valid placements snap into position and the piece animates into its destination cells; invalid placements return to the queue. When a pedestal becomes fully filled with blocks that share a single rendered color, particles burst, the pedestal slides off, and any pedestals above it drop down into the freed slot. Clear the last pedestal to win the level.

Folder Structure

Gameplay

Core Mechanics

Each level features a set of pedestals (2×3 or 3×3 grids) on the board and a start grid at the bottom of the screen that holds the queue of playable pieces. The goal is to clear every pedestal by filling it with blocks that all share a single color.

• Drag and fit — Touch a piece in the start grid OR on any pedestal, drag it onto any pedestal; valid placements snap into the closest free cells, invalid ones bounce back.
• Rearrange the queue — Pieces can also be dragged back into the start grid and repositioned within it, so the queue isn't one-way. Drop candidates inside the start grid honor the gridStartBlockYOffset baked in at level load, and the top row is clamped to the authored ceiling (plus the optional DoNotCrossTop marker if present).
• World-space snap — The drop-target search compares the piece's world position against each candidate cell's world position, so it works correctly across parent-scale mismatches (e.g. the tablet scaler on All).
• Pedestal hover highlight — While dragging, the pedestal that would accept the release tints toward a soft green and a translucent ghost of the piece appears at the exact landing cell. Moves with the cursor and clears when the drag ends or the piece wouldn't fit anywhere.
• Shape-aware placement — Each piece occupies a specific set of cells (derived from its BlockType); it must fit entirely inside the target pedestal with no collision.
• Color match to clear — A pedestal clears when two conditions are met together: every cell is occupied, and every block on it is the same rendered color.
• Gravity-up queue — After a piece leaves the start grid, remaining pieces rise into the freed slots up to a shape-aware ceiling so the queue visually settles upward. Skipped when a piece lands in the queue so the player's chosen slot isn't yanked away by gravity.
• Pedestal gravity-down — When a pedestal clears, any pedestals above it in the same column slide down one slot.
• Pre-placed blocks — Levels can start with blocks already in a pedestal, committing that pedestal to a specific color from the opening move.
• Decoys — The auto generator can seed pedestals with off-color blocks that the player must work around or smash with Hammer. Decoyed pedestal count is capped at the level's Hammer charge so every level stays provably solvable.

DoNotCrossTop ceiling marker

Optional Transform on the GameLevel component. If a scene GameObject named DoNotCrossTop exists (typically parented under the queue's Depestal(Clone) backdrop), any start-grid drop whose shape cells would land above the marker's world Y is rejected before the snap distance is even checked. Auto-discovered by name at Start() if the Inspector slot is empty. Leave the marker out to fall back to the shape-aware cell-grid ceiling alone.

Block Colors

The game supports thirteen predefined colors defined in the ColorType enum. Each is mapped to a render color by ColorData:

The palette is defined by ColorData.asset; the hex values above are the reference look used by the shipped art. Colors that share a rendered RGB (e.g. two custom hues that both resolve to white) are treated as the same color by the match check — match logic compares rendered RGB, not enum value.

Block Shapes

Pieces are authored as tetromino-like shapes in BlockData.asset. The shipping set includes 14 distinct shapes (Block1 through Block14), ranging from single cells to three-cell L / I / T variants. Each shape has an origin cell and a list of offset cells relative to the origin; placement validity and the sibling-Z render order are derived from this offset list, so you can add or edit shapes without touching gameplay code.

Win & Lose Conditions

• Win — All pedestals have cleared (only the start grid remains). The win panel appears, the current level index advances via LevelManager.AdvanceLevel(), and the next level loads automatically.
• Lose — The player can still drag pieces, but a queue of pieces where none fit any remaining pedestal is effectively lost. The lose path is routed through FitBlastGameManager.TriggerLose() — call it from your own heuristic (e.g. an explicit "give up" button) or wire in a move-limit, timer, or stuck-state detector. The lose panel has a Retry button that reloads the current level.

Animations

All animations are hand-rolled coroutines — no DOTween or LeanTween. Pieces ease into position on drop via MoveBlockTo; pedestals slide off-screen via MoveImageTo; the queue settles upward via LevitateStartGrid. Particle bursts fire via the single shared ParticleSystem reference on the GameLevel. The Hammer booster pulses every pedestal's tint on a sine curve while armed, and the Hint booster instantiates a translucent ghost of the suggested piece at the target cells for ~2.2s.

Scripts Reference

Gameplay scripts live under Assets/Fit Blast/Scripts/ in the FitBlask.Scripts namespace. Reusable engine scripts live in the same folder under the HypercasualGameEngine namespace.

Core Gameplay

Engine Scripts (HypercasualGameEngine)

Editor Scripts

Level Editor

Opening the Level Editor

In the Unity menu bar, go to Tools > Fit Blast > Level Editor. This opens a dedicated Editor window — no need to enter Play mode.

Features

• Visual board — Every pedestal and the start-grid queue are drawn as real cell grids. Placed blocks render with their actual ColorData color and occupy their BlockData shape cells. What you see in the editor is exactly what loads at runtime.
• Paint / Erase toolbar — Toggle between Paint (place the palette piece on the clicked cell) and Erase (remove whatever block owns the clicked cell) above the board.
• Block palette — Row of shape thumbnails drawn directly from BlockData.blockMappings; click one to pick the active paint shape. The standard dropdown is also there.
• Color palette — Row of swatches drawn from ColorData.colorMappings; click to pick the paint ColorType. Unmapped enum values aren't shown so you can't accidentally paint white-renders.
• Board layout — Pedestals are arranged on the authored gridSizeX × gridSizeY grid. Empty slots show a + add pedestal placeholder that clicks to drop in a new 3×3 pedestal at that grid position.
• Per-pedestal header — 2×3 / 3×3 size toggles (auto-prune out-of-bounds blocks) and a red × to remove the whole pedestal.
• Start-grid editor — Shows the queue at the bottom of the right pane with width / height numeric fields. The drawn range expands to cover every cell any authored piece touches (the queue routinely has pieces at negative Y) plus a one-row margin so you can extend downward.
• Level List — Browse, add, duplicate, reorder (up / down), and delete levels in the left panel.
• Booster Counts — Per-level starting counts for Hammer, Shuffle, and Hint, in the header above the board.
• Save All to Disk — Serialises every level in-memory back to Assets/Fit Blast/Resources/Levels/Level_N.json.

Click model

• Paint a block — In Paint mode, click the cell you want the block's origin at. If the shape fits (no collision, inside the pedestal bounds for pedestals, inside the X bound only for the start grid) it's added. Otherwise the click is a no-op.
• Erase a block — In Erase mode, click any cell belonging to the block; the whole block is removed.
• Add a pedestal — Click the empty slot at the desired (x, y) on the board.
• Resize a pedestal — Use the 2×3 / 3×3 buttons in its header. Existing blocks that would fall out of bounds are pruned automatically.
• Remove a pedestal — Red × in its header.

Level Storage

All levels are stored as individual JSON files in Assets/Fit Blast/Resources/Levels/ with the naming convention Level_1.json, Level_2.json, etc. They are loaded in the editor directly from the hard-coded absolute path (bypassing Unity's Resources system to avoid cross-contamination with other Resources/Levels/ folders), and in built players via strict sequential Resources.Load<TextAsset>("Levels/Level_" + i).

Automatic Level Generator

The Automatic Level Generator is an Editor tool that batch-generates playable color-fit levels procedurally. It uses an exact-cover tiling algorithm for pedestal solutions, pre-places a difficulty-driven fraction of the solution for visual scaffolding, optionally seeds off-color decoy blocks, and emits one JSON file per level.

Opening the Tool

In the Unity menu bar, go to Tools > Fit Blast > Auto Level Generator.

Settings

How It Works

1. Configure settings — adjust all parameters in the Editor window
2. Click "Append Levels to Disk" — the tool detects existing levels and appends new ones starting at the next free index
3. For each level, the generator:
   • Interpolates difficulty from the level's position in the batch (plus a small jitter)
   • Picks a pedestal count, a color palette, and per-pedestal colors
   • Solves each pedestal as an exact-cover tiling with block shapes from the allowed set
   • Pre-places a difficulty-dependent fraction of the solution on the pedestal
   • Places the remaining pieces on the start grid (overflowing to the owning pedestal if the queue runs out of space)
   • Optionally seeds decoy pieces on pedestals
   • Writes the Level_N.json file

Solvability guarantee

Every generated level is solvable by construction. The invariants the generator maintains:

• Each pedestal's cells are exactly covered by its solution set (backtracking exact-cover tiling).
• Every non-pre-placed solution piece sits in the start grid (enforced by a paranoid end-of-phase check).
• The number of pedestals that receive decoys is capped at the level's Hammer charge. Because the start grid is not a legal drop target, decoys can only relocate to another pedestal — which pollutes that pedestal's color and forces a Hammer clear. Capping at Hammer count means the player can always hammer every decoyed pedestal outright, and the remaining pedestals are trivially drag-solvable from the queue.

Boosters

The game includes three booster abilities that players can activate during gameplay. Each booster has a configurable number of uses per level (set in the level JSON) and a first-use tutorial popup keyed in PlayerPrefs.

Booster Buttons

Booster buttons are found in the GameHUD_Panel/BottomHolder in the scene UI. BoosterManager locates them by the literal names Booster-Button-1, Booster-Button-2, Booster-Button-3 — do not rename them. Each button has:

• A background overlay (Bg) that shows/hides based on availability
• A use count badge (PowerUpCountText) showing remaining uses, or the unlock level if still locked
• An armed-mode tint (amber) while Hammer is waiting for a target
• Lock by level — boosters unlock at configurable levels (default: Hammer at level 1, Shuffle at level 2, Hint at level 3)

First-Use Popups

The first time a player taps each booster, a one-time tutorial popup appears explaining it. BoosterManager.HookUpExistingBoosters searches the active scene for Booster-Popup-1/2/3 (including inactive objects, since they're serialized as m_IsActive: 0 by default) — in the shipping scene these are Popup_Powerup_Picker prefab instances parented under Games / #5 / WorldCanvas. If the scene has no match for a name, a simple centered card with a dark scrim + TMP text is built at runtime as a fallback (scrim-click dismisses).

Popups auto-hide after 2.5 s so the player never gets stuck, and runtime cards can be tapped away sooner via the scrim Button. The "seen" flag is keyed in PlayerPrefs as BoosterPopupShown_Hammer, BoosterPopupShown_Shuffle, BoosterPopupShown_Hint. Use the dev panel's Reset Popup Prefs button to re-test the popups.

Dev Cheat Controls

During Play mode, open the Developer Settings panel (gear-icon button in the top-right) to unlock every booster, refill usage counts, trigger win/lose, jump levels, and reset popups. Hotkeys while the panel is open: Shift+U (unlock + refill), Shift+W (win), Shift+L (lose), Shift+R (reload level). Level navigation with Left Arrow / Right Arrow works regardless of whether the dev panel is open because it lives on FitBlastGameManager.

Customization Guide

Adding a New Block Color

To add a new block color:

1. Open ColorData.cs and add a new entry to the ColorType enum:
   public enum ColorType { Red, Green, Blue, Yellow, Cyan, Magenta, Orange, Purple, Brown, Gray, Black, White, Pink, // Add your custom color: Teal }
2. Open ColorData.asset in Assets/Fit Blast/Datas/ and append a Color entry for Teal. Unmapped enums default to white at runtime, so forgetting this step silently breaks the match check.
3. Re-save levels via Tools > Fit Blast > Level Editor > Save All to Disk (or let the Auto Generator re-generate) so the JSON files reference the new color by its integer enum value.

The new color is automatically available in the Level Editor, Auto Generator, and at runtime.

Adding a New Block Shape

To add a new piece shape, open BlockData.asset in the Inspector. Add a mapping entry: pick the next BlockType enum value (or extend the enum in LevelData.cs first), drag a sprite for the shape, and fill in the list of cell offsets relative to the origin. The custom BlockDataEditor draws a visual cell-grid editor so you can paint offsets click-by-click. Placement validity, pedestal-match detection, and the gravity-up settle all follow from this offset list — no gameplay code changes required.

Replacing Art

• Block sprites — replace the sprites in Art/Sprites/Blocks/ and re-reference them on each BlockData mapping entry.
• Pedestal containers — replace the 2×3 / 3×3 container sprites under Art/Sprites/ and wire them into GameLevel.pedestalSprites.
• Particles — the single shared ParticleSystem on GameLevel drives every clear burst. Edit its material or curves in the Inspector.
• HUD / Popup — GameHUD_Panel.prefab and Popup_Powerup_Picker.prefab are standalone UI prefabs; edit their children freely as long as you preserve the load-bearing names Booster-Button-1/2/3, Booster-Popup-1/2/3, PowerUpCountText, Bg.

Replacing Audio

SoundManager.cs exposes one serialized AudioClip field per event (see the sfxBoosterHammer / sfxBlockMatch / sfxLevelWin / … list) plus four random-pick arrays (successClips, failClips, popClips, switchClips). Drop in your own AudioClips by filename from Assets/Fit Blast/Audio/; the shipping clips are already wired up on the SoundManager component in GameNew.unity.

Changing the Booster Set

1. Rename the fields on LevelData — e.g. hammerBoosterCount → rotateBoosterCount — if you are adding a new booster that needs per-level tuning. Rerun the Auto Generator after renaming to refresh the JSON files.
2. Update the three On<Name>Clicked click handlers in BoosterManager.cs and the matching Apply<Name> entry points on GameLevel.
3. Point the three HookUpExistingBoosters slot findings at Booster-Button-1/2/3 exactly as before — the HUD prefab's GameObject names are load-bearing.
4. Swap the button icons on the HUD prefab to match the new booster art.

JSON Level Format

Each level is a JSON file with the following structure:

The gridItems array lists every pedestal on the board; each has a width, height, position on the level's gridSizeX/gridSizeY layout, and a list of pre-placed blocks. The gridStart object is the bottom queue — a single grid holding the player's initial pieces. blockType is an integer index into the BlockType enum (0-based), and colorType is an integer index into ColorType. positionInGrid is the origin cell of the piece inside that grid.

Support

Common Issues

Build Notes

• Scripting Backend: IL2CPP (Android + iOS).
• API Compatibility Level: .NET Standard 2.1.
• Color Space: Linear.
• Active Input Handling: Both.
• Scripting Define Symbols: none required. The template has no ads, no analytics, and no conditional features.
• Only Assets/Fit Blast/Scenes/GameNew.unity should be enabled in EditorBuildSettings.
• WebGL input: InputManager reads Pointer.current (the Input System's cross-device abstraction) before falling back to an active-touch scan and then Mouse.current. This is necessary because WebGL's runtime creates a virtual Touchscreen device even on desktop browsers; a naive Touchscreen.current.touches.Count > 0 check always wins and silently blocks mouse input. The current flow works identically on Standalone, mobile, WebGL-desktop, and WebGL-mobile.

Tablet aspect scaler

Assets/Fit Blast/Scripts/TabletAspectScaler.cs (attached to the All GameObject). On Awake it reads Screen.width / Screen.height, computes short / long aspect, and if it's at or above tabletAspectThreshold (default 0.65) overrides the transform's uniform local scale to tabletScale (default 0.3452272). Phone aspects (~0.45–0.56) fall below the threshold so the authored phone scale is left intact. Both values are Inspector-tunable.

What This Template Does NOT Include

By design — to keep the package tight and focused:

• No ads / AdMob / monetization SDK
• No haptics / vibration
• No analytics SDK (Unity dashboard analytics only if you enable it)
• No IAP / coins / shop
• No background music (SFX only)
• No settings menu / main menu / pause menu
• No DOTween / LeanTween (hand-rolled coroutines)
• No assembly definitions for game code (by design — see systems/14-assembly-definitions.md)
• No cloud save / localization

Tips

• Use the Developer Settings Panel (gear icon) in Play mode to quickly navigate levels, trigger win/lose, and unlock boosters
• Press Right Arrow / Left Arrow during gameplay to jump to the next/previous level
• Press Shift+U while the dev panel is open to unlock and refill all boosters for testing
• The Auto Level Generator is the fastest way to add more content on top of the 500 shipped levels — generate hundreds more in seconds
• Every generated level is solvable by construction: each pedestal's solution is pre-computed as an exact-cover tiling before any decoys are seeded
• Back up your Resources/Levels/ folder regularly
• The Welcome Popup can be permanently dismissed via the "Do not show this popup again" checkbox

Changelog

Contact Us

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