Picture Block Puzzle 2D

Overview

Picture Block Puzzle 2D is a sliding picture-assembly puzzle where players drag colour-coded image pieces across a grid to reconstruct the original pictures before the timer runs out. Each block has a “zero” anchor piece that defines where the assembled image should sit; the remaining pieces must be placed at their solved offsets relative to that anchor. The game ships with a time-limit countdown, four boosters, axis-constrained pieces with a visible arrow overlay, a visual level editor, an automatic level generator, and a 500+ starter pack of generated JSON levels.

Getting Started

Requirements

• Unity 6 or newer
• Universal Render Pipeline (URP)
• TextMesh Pro (included with Unity)
• Input System package (the template uses both legacy and the new Input System)

Installation

1. Import the Picture Block Puzzle 2D 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/Picture Block Puzzle 2D/Scenes/GameNew.unity
4. Press Play to test the first level. To author or batch-create levels, use Tools > Picture Block Puzzle 2D > Level Editor or … > Auto Level Generator

Quick Test

Once in Play mode, drag any movable block on the grid to an empty cell. When every non-zero piece of a block sits at its solved offset from that block's zero anchor, the picture completes automatically and the star particles burst. Clear all pictures before the countdown reaches 0 to win the level. On win the next level loads automatically; on time-out the lose panel appears.

Folder Structure

Gameplay

Core Mechanics

Each level displays a grid of cells, a set of multi-cell blocks (each painted with a color and carrying a piece of a larger picture), and a visible countdown. The player drags blocks to empty cells; physics colliders prevent overlap. A block is considered assembled when every non-zero piece of its color sits at zeroHead + (pieceHead − zeroPieceHead) — i.e. the picture is reassembled in its authored orientation. Swapping two same-colored pieces does not count; the exact offsets must match.

• Drag to slide — Touch or click a block and drag it across the grid; it snaps to the nearest free cell on release. The dragged piece darkens to ~70% brightness while held and restores its original tint on release so the player always sees which piece is live
• Shape footprints — Blocks occupy multi-cell shapes; CanApplyShapeToGrid ensures every target cell is empty before the move is accepted
• Axis-constrained movement — Individual pieces may carry a moveAxis of Horizontal or Vertical, restricting drag to that single axis. A double-headed arrow overlay is rendered on top of the piece showing which axis is allowed
• Zero-piece anchor — Each block has one “zero” piece marked isZeroPos: true; the solved image is computed from where the zero piece currently sits
• Picture merge — When all pieces of a block are in place, their sprites fade into the finished picture, the star particles burst, and the matching goal icon pops with a scale-bounce animation
• Countdown timer — Every level has a timeLimit in seconds; reaching 0 triggers the lose panel. The Time Freeze booster pauses the countdown for 10 seconds and shows an on-screen FrozenImage indicator while active
• Obstacles — Static wall cells (obstacles in the JSON) cannot be entered by any block. Wall density scales with difficulty on generated levels
• Progression — On win, LevelManager.AdvanceLevel() runs before the scene reloads; on lose, the same level reloads

Block Colours

Seven predefined block colours, defined in Ecolor.cs and mapped to RGB in MyUtils.GetColor / JsonLevelData.cs → BlockColors:

Win & Lose Conditions

• Win — Every non-zero piece is at its solved offset for every color in the level. The stars burst on the completed pictures, SoundManager.Instance.PlayLevelClear() fires, the level index advances, and the next level loads automatically.
• Lose — The countdown reaches 0 before the last picture completes. The FrozenImage (if active) is dismissed, the lose panel appears, and the Retry button reloads the current level.

Animations & Feedback

Blocks use 2D rigidbodies with snap-to-grid placement for drag feedback. Completed pictures fade their ghost sprites into the final image and emit a star particle burst. The Hint booster spawns a translucent ghost of a displaced piece at its solved position and pulses it for ~2.2 seconds while also briefly scaling the real piece so the player can see which piece should move where. The Shuffle booster reseats blocks with an explicit no-overlap validation pass.

Scripts Reference

Runtime scripts use the PictureBlockPuzzle2D.Scripts namespace. Editor scripts use the PictureBlockPuzzle2D.Editor and PictureBlockPuzzle2D.EditorTools namespaces. Shared helpers (SoundManager, DeveloperSettingsController, LoseWinPanelManager) live under HypercasualGameEngine.

Core Scripts

Utility Scripts

Engine Scripts (HypercasualGameEngine namespace)

Editor Scripts

Level Editor

Opening the Level Editor

In the Unity menu bar, go to Tools > Picture Block Puzzle 2D > Level Editor. This opens a dedicated Editor window — no need to enter Play mode.

Layout

• Left panel — Level list with add, duplicate, reorder (▲ / ▼), and delete-with-confirm buttons; Save All Levels (writes JSON to Resources/Levels/PictureBlockPuzzle2D/); Reload from Disk; and Refresh Sprites (re-scans Resources/BlockIcons/ for new artwork).
• Right panel — Level properties (cols, rows, time limit, all four booster counts), tool bar, tool-specific options, the visual grid, and the Blocks list (with mini previews + inline per-piece editing).

Visual Parity with Runtime

The grid renders pieces exactly the way the running game does:

• Multi-cell pieces drawn fully — L-shapes and 1×2 pieces show every cell they occupy (the older paint-mode editor only drew the head cell).
• Sliced sprite per cell — the icon sprite is centered on the block's geometric center, contain-fit-scaled to the block's bounds with a 10% padding, and clipped to each piece's cell. This mirrors Block.cs's SpriteMask + iconSpriteRenderer composition, so what you see in the editor is what you'll see in Play mode.
• Movement axis overlay — pieces with a non-Any moveAxis show the same horizontal / vertical arrow sprite the runtime renders.
• Selected block highlight — selected block's pieces get a yellow border across all their cells.
• Zero piece marker — the isZeroPos: true piece's head cell is labelled 0.

Tools

Building a Multi-Piece Block

Every Place Pattern click creates a single-piece block. To assemble several pieces into one logical multi-piece block (so they share one picture / sprite):

1. In Place Pattern mode, drop each piece in its solved (adjacent) layout — e.g. for a 2×2 block built from two 1×2 horizontal pieces, click 1x2 at (3,4) and again at (3,5).
2. Switch to Select / Move and click one of the placed pieces to select it as the destination block.
3. In the Blocks list, click the “↪ merge” button on every other block you want to fold in. Each merge:
   • Computes the bounding box of every cell of every piece in both blocks.
   • Sets the destination block's blockSize to that bounding box.
   • Rewrites every piece's headPosition to its slot inside the bounding box.
   • Keeps the destination block's color, sprite, and zero-piece flag (extras are demoted; piece 0 is promoted if no zero remains).
   • Removes the now-empty source block.
4. Optionally switch back to Select / Move and drag pieces around to scramble them. Drag changes startPos only — headPosition stays put, so the picture mapping survives the scramble.

The merge button is greyed out when nothing is selected or when you'd be merging a block into itself.

Block Properties

Every block row in the Blocks list exposes:

• Mini preview canvas on the left (color + sprite slice in solved layout).
• Color picker — one of the seven palette keys (yellow / red / magenta / purple / blue / mint / lime).
• ↪ merge / X — merge into selected block, or delete the entire block.
• Block size — (cols, rows) of the assembled picture; bigger sizes display the icon at a larger scale.
• Block axis — legacy whole-block MoveAxis (kept for old JSONs; per-piece axis is the source of truth at runtime).
• Icon sprite — dropdown of every sprite under Resources/BlockIcons/, with a thumbnail preview and a drag-drop slot.
• Inline pieces editor — one row per piece showing shape name, startPos, headPosition, moveAxis, zero-piece toggle, and a per-piece delete. Promoting a piece to zero auto-clears the others so exactly one zero remains.

Level Storage

All levels are stored as individual JSON files in Assets/Picture Block Puzzle 2D/Resources/Levels/PictureBlockPuzzle2D/ with the naming convention Level_1.json, Level_2.json, … The runtime loader uses Resources.LoadAll<TextAsset>("Levels/PictureBlockPuzzle2D") and sorts by the trailing number in each filename. Save All Levels wipes the existing files in that folder and writes a fresh set, numbered by their order in the level list — reorder the list before saving if you want a specific numbering.

Automatic Level Generator

The Automatic Level Generator is an Editor tool that batch-generates playable picture-assembly levels. It controls grid size, block count, scramble moves, time budget, booster allowances, axis-constraint chance, and wall density — all scaled along a front-loaded difficulty curve so hard levels arrive earlier in the batch. Generated levels always satisfy the shape-footprint / occupancy invariants used by the runtime; the in-game Shuffle, Hint, Undo, and Grid Expander boosters give players a way out of any stuck state (a forward-BFS solvability check is intentionally not run — it was rejecting harder scrambles and producing levels where pieces landed conveniently close to their solved positions).

Opening the Tool

In the Unity menu bar, go to Tools > Picture Block Puzzle 2D > Auto Level Generator. This opens a settings window where you can configure all parameters before generating.

Settings

How It Works

1. Configure settings — adjust all parameters in the Editor window
2. Click “Generate Levels” — the tool detects existing levels and appends new ones
3. For each level, the generator:
   • Randomises grid size, block count, scramble depth, wall density, and axis-constraint chance within your ranges, all scaled by a front-loaded difficulty curve (t = pow(levelIndex / total, 0.55)) so the player reaches hard levels sooner
   • Places blocks using the curated tiling-pattern library (2×2 with two stacked 1×2s, 2×3 / 3×2 with three 1×3s, L-shape + 1×1 combos, etc.) to guarantee clean footprints close to 1:1 aspect ratios
   • Marks one piece per block as the zero-anchor and records the remaining pieces' solved offsets
   • Scrambles non-zero pieces via random legal slides, biased toward destinations far from each piece's solved head so pieces actually travel rather than wobble around their goal
   • Assigns at most one piece per block a moveAxis constraint (Horizontal or Vertical) when the chance roll succeeds — only on pieces whose scrambled → solved delta is already purely along that axis, to keep the constraint self-consistent
   • Scatters wall obstacles across empty cells at increasing density with difficulty (up to ~28% of grid area at the hardest) with a minimum floor that rises with difficulty to produce that “cramped” hard-level feel
   • Writes the JSON level file to Resources/Levels/PictureBlockPuzzle2D/Level_N.json

Boosters

The game includes four booster abilities that players can activate during gameplay. Each booster has a configurable number of uses per level (set in the level JSON data) and an optional first-use tutorial popup. Each booster unlocks at a specific level so new players learn one mechanic at a time.

Booster Buttons

Booster buttons live in the scene under GameHUD_Panel/BottomHolder. 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 ("lvl N") if still locked
• Lock by level — defaults: Time Freeze at level 1 (index 0), Hint at level 2 (index 1), Shuffle at level 3 (index 2), Grid Expander at level 4 (index 3). All four fields are public on BoosterManager and can be tuned in the Inspector per-project
• First-use popup — the scene carries four inactive Booster-Popup-1/2/3/4 GameObjects; the first use of each booster fades its popup in and out. Keys are stored in PlayerPrefs (BoosterPopupShown_Undo, BoosterPopupShown_Hint, BoosterPopupShown_Shuffle, BoosterPopupShown_GridExpand)

Cheat Mode

Press the U key during gameplay to unlock all boosters and refill their usage counts (wrapped in #if UNITY_EDITOR || DEVELOPMENT_BUILD so it's stripped from release builds). The hotkey reads both the legacy Input.GetKeyDown and the new-Input-System Keyboard.current.uKey so it works regardless of which backend owns focus. It calls BoosterManager.DebugUnlockAndRefillAll(), a self-healing variant that re-hooks scene button references if the scene hasn't yet initialised.

Press Right Arrow / Left Arrow during gameplay to jump to the next / previous level (wraps at the ends). Handled by PictureBlockPuzzle2DGameManager.Update().

The Developer Settings Panel also ships with Next Level / Previous Level / Reload buttons.

Customization Guide

Adding New Colours

To add a new block colour (the game already ships with seven — yellow, red, magenta, purple, blue, mint, lime):

1. Open Ecolor.cs and add a new entry to the EColor enum:
   public enum EColor { None, Yellow, Red, Magenta, Purple, Blue, Mint, Lime, // Add your custom colour: Teal }
2. Open MyUtils.cs and add the RGB for the new entry to GetColor. Open JsonLevelData.cs and mirror it in the BlockColors dictionaries (colors, toEnum, toKey, AllKeys)
3. Open LevelGeneratorWindow.cs and add the new key to the COLOR_KEYS array so the generator picks from it
4. Regenerate or hand-author a level that uses the new colour key

New colours are automatically available in the Level Editor, Auto Level Generator, and at runtime.

Adjusting Grid Visuals

The grid layout is controlled by GridManager.cs. Key Inspector properties:

• cellSpace — Spacing between grid cells in world units
• tilePrefab — The visual prefab placed at each grid cell
• shapeData — Lookup that maps shapeType integers in the JSON to concrete Block prefabs
• starParticlePrefab — The burst VFX played when a picture completes
• borderRoot — Optional invisible Border with 4 collider walls; repositioned to the current grid size at runtime if assigned

Modifying Block Visuals

Block rendering is driven by Block + per-piece sprites under Resources/BlockIcons/. To retheme:

• Replace the sprites in Resources/BlockIcons/ (keep the same filenames to avoid retagging every level JSON)
• Update the Block prefabs' SpriteRenderer defaults if you want a new fallback tint
• Edit the color palette in JsonLevelData.cs → BlockColors to change the tint of every block of that color

Audio

Audio lives on a single SoundManager singleton. Replace any clip on the SoundManager GameObject in the scene to retheme a specific event. Add a new clip field + matching PlayX() method if you introduce a new gameplay event — the existing pattern is documented inside SoundManager.cs.

Adding New Boosters

New boosters can be added by following the existing pattern in BoosterManager.cs:

1. Add booster state fields (use count, unlock level, UI references)
2. Wire up the button in HookUpExistingBoosters() by adding a fourth named child (Booster-Button-4) to the scene and matching it by string
3. Implement the booster logic in a new click handler method (e.g. OnMyBoosterClicked())
4. Add a count field to JsonLevelData / LevelData and populate it in BoosterManager.Init()
5. Update UpdateBoosterUI() to draw the new button's lock / unlock / count display

JSON Level Format

Each level is a JSON file with the following structure:

The blocks array defines multi-piece pictures. Each block has a colorKey (one of yellow / red / magenta / purple / blue / mint / lime), a blockSize, a spriteName (resolved from Resources/BlockIcons/), and a list of pieceDatas. Each piece has:

• startPos — where the piece spawns on the grid (x, y in 0-indexed grid coords, (0,0) at top-left)
• headPosition — the piece's offset inside the assembled picture, with (0,0) reserved for the zero piece
• shapeType — index into the shape library (0: 1×2 horizontal, 1: 1×2 vertical, 2: L top-right, 3: L bottom-left, 4: 1×1 single)
• isZeroPos — exactly one piece per block must be true — that piece is the solved-image anchor
• moveAxis — per-piece movement constraint: 0 = Any, 1 = Horizontal, 2 = Vertical. When non-zero the piece renders a double-headed arrow overlay and drags lock to that axis

Note on field name: undoBoosterCount is the legacy serialised name kept for save-file compatibility; at runtime it drives the Time Freeze booster.

Note on moveAxis placement: the per-block moveAxis field is legacy — at runtime the per-piece moveAxis inside pieceDatas is authoritative. The generator only constrains one piece per block (on an axis where that piece's scrambled → solved delta is already purely along that axis) so levels stay self-consistent.

Support

Common Issues

Tips

• Use the Developer Settings Panel (gear icon) in Play mode to quickly navigate levels, trigger win / lose, unlock boosters, and reset popups
• Press Right Arrow / Left Arrow during gameplay to jump to the next / previous level
• Press U to unlock and refill all boosters for testing
• The Auto Level Generator is the fastest way to populate your game with content — generate 100+ levels in seconds and then hand-tune Levels 1–5 in the Level Editor
• For a hand-built multi-piece block in the Level Editor: place each piece in its solved (adjacent) layout with Place Pattern, select one of them, then click “↪ merge” on the rest to fold them into a single block
• Back up your Resources/Levels/PictureBlockPuzzle2D/ folder regularly
• The Welcome Popup can be permanently dismissed via the “Do not show this popup again” checkbox

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!