Block Blaster Jam - Documentation

Overview

Block Blaster Jam is a cannon-based puzzle game where players load colored cannons into slots and shoot projectiles at a grid of color-matched blocks. Destroy all blocks and obstacles to clear the level. The game features dynamic grid sizes, stacked floor blocks, 2×2 obstacles, a queue-based cannon system, a built-in level editor, an automatic level generator, a booster system, and full AdMob ad integration.

Cannon & Slot System

Tap queue cannons to load them into firing slots. Shoot colored projectiles at matching blocks on the grid. Strategic slot management is key to winning.

Level Editor

Full Unity Editor window for designing levels with visual grid painting — place colored blocks, set floor stacks, configure cannons, obstacles, and locked slots.

Auto Level Generator

Batch-generate hundreds of levels with configurable difficulty curves, grid sizes, color pools, floor stacking, hidden cannons, and obstacle densities.

Booster System

Three in-game boosters — Shuffle, Bomb, and Unlock — with tutorial popups, usage tracking, and progressive unlocking.

AdMob Integration

Ragendom Monetization module with banner, interstitial, and rewarded video ads. Includes a Dummy provider for editor testing.

50 Levels Included

Ships with 50 pre-generated levels with a progressive difficulty curve, ready to play out of the box. Generate hundreds more with one click.

Getting Started

Requirements

Unity 6 or newer
TextMesh Pro (included with Unity)

Installation

Import the Block Blaster Jam package into your Unity project
Open the game scene at Assets/Block Blaster Jam/Scenes/GameNew.unity
Press Play to test the first level

Quick Test

Once in Play mode, tap a cannon in the queue area to load it into an empty slot. Then tap a block on the grid that matches the cannon's color to fire a projectile. When all blocks and obstacles are destroyed, the level is cleared and the next level loads automatically. Use arrow keys to skip between levels during testing.

Folder Structure

Block Blaster Jam/ │ ├── Art/ │ ├── Materials/ — Shared materials (Ground.mat) │ ├── Meshes/ — Smooth cube FBX models (cube-smooth-1 to 4) │ └── Textures/ — UI textures (booster icons, panel backgrounds, etc.) │ ├── Audio/ — All sound effects (.wav) │ ├── Documentation/ — This documentation file │ ├── Editor/ — Editor-only scripts (excluded from builds) │ ├── BlockBlasterJamWelcomePopup.cs — Welcome popup on project open │ ├── LevelEditorWindow.cs — Visual level designer │ └── LevelGenerator.cs — Automatic batch level generator │ ├── PostProcessing/ — Post-processing profile assets │ ├── Prefabs/ — All prefabs (UI panels, HUD, developer tools) │ ├── GameHUD_Panel.prefab │ ├── GameOverPanel.prefab │ ├── LevelClearedPanel.prefab │ ├── LoseWinPanel.prefab │ ├── Popup_Powerup_Picker.prefab │ └── DeveloperModeButton.prefab │ ├── Scenes/ │ └── GameNew.unity — Main game scene │ ├── Shaders/ │ └── OutlineOnly.shader — Block outline shader │ └── Scripts/ — All runtime scripts ├── BlastGameManager.cs — Main game controller & state machine ├── BlastBoardManager.cs — Grid, gravity, reserves, block management ├── BlastSlotManager.cs — Cannon slots, queue system, locked slots ├── BlastBlock.cs — Block entity (colors, floors, damage, animation) ├── BlastCannon.cs — Cannon entity (ammo, firing, hidden reveal) ├── BlastProjectile.cs — Projectile flight & impact ├── BlastObstacle.cs — 2×2 obstacle entity (HP, damage, gravity) ├── BlastMeshHelper.cs — Smooth cube mesh loading & caching ├── BlastParticleManager.cs — Explosion & effect particles ├── BoosterManager.cs — Shuffle, Bomb, Unlock booster logic ├── LevelData.cs — Data structures, BlockType enum, BlastColors ├── LevelManager.cs — Level loading, progression, persistence ├── SoundManager.cs — Audio system (singleton) ├── LoseWinPanelManager.cs — Win/Lose UI panel controller ├── CameraSwitcher.cs — Multi-game camera switching ├── DeveloperModeButton.cs — Dev panel toggle button └── DeveloperSettingsController.cs — Dev panel controls (level nav, ads) Resources/ — Unity Resources folder (loaded at runtime via Resources.Load) ├── Levels/ — 50 level JSON files (Level_1.json ... Level_50.json) ├── cube-smooth-3.fbx — Runtime-loaded smooth cube mesh └── lock-icon.png — Lock overlay texture for locked slots

Gameplay

Core Mechanics

Each level is a grid of colored blocks with cannons in a queue below. The goal is to destroy every block and obstacle on the grid by shooting color-matched projectiles from cannons.

Queue & Slots — Tap a cannon in the queue to load it into an empty firing slot. Manage your limited slots strategically.
Color matching — Tap a block on the grid that matches the cannon's color. The cannon fires a projectile that destroys the block on impact.
Gravity — After a block is destroyed, blocks above fall down. Reserve blocks spawn from the top to fill empty columns.
Floor stacking — Some blocks have 2–5 stacked floors. Each hit removes one floor. The block is destroyed when all floors are gone.
Obstacles — Gray 2×2 merged blocks with HP. Any cannon color can target obstacles as a fallback when no matching blocks exist.
Hidden cannons — Some queue cannons show "?" until they reach the front of the queue, adding a surprise element.
Locked slots — Some slots start locked and require the Unlock booster to open.

Block Colors

The game supports ten block colors:

BlockType	Color	Approximate Hex
`Red (1)`	Red	#FA5258
`Yellow (2)`	Yellow	#FCD626
`Blue (3)`	Blue	#3D8CF5
`Green (4)`	Green	#4DD966
`Orange (5)`	Orange	#FF9926
`Purple (6)`	Purple	#9E52F0
`Pink (7)`	Pink	#FF78A8
`Cyan (8)`	Cyan	#2ED6E0
`Lime (9)`	Lime	#ADF533
`Magenta (10)`	Magenta	#E640B8

Win & Lose Conditions

Win — All blocks and obstacles are destroyed. The level index advances and the next level loads automatically.
Lose (Out of Ammo) — All cannons are out of ammo, no projectiles are in flight, and blocks remain on the grid.
Lose (Deadlock) — All slots are full with dead cannons, no cannon can fire, and no queue cannons remain.

Block Destruction Animation

When a projectile hits a matching block, the block shrinks to zero scale over 0.2 seconds while spawning colored explosion particles. Neighboring blocks receive a shake effect for visual feedback. Stacked-floor blocks lose one floor per hit, with each floor being removed individually before the block dies.

Scripts Reference

All scripts use the HypercasualGameEngine namespace.

Core Scripts

Script	Description
`BlastGameManager`	Main game controller. Loads level data, manages game state (Playing/Won/Lost), handles input (tap-to-fire), checks win/lose conditions, and coordinates all managers. Attached to the root game object.
`BlastBoardManager`	Manages the block grid with dynamic rows/columns. Handles gravity (blocks fall to fill gaps), reserve blocks spawning from the top, obstacle grid tracking, block accessibility checks, and bomb-radius destruction.
`BlastSlotManager`	Controls cannon firing slots and the queue system. Handles loading cannons from queue to slots, locked slot mechanics, slot unlock animations, cannon input, and Fisher-Yates queue shuffling.
`BlastBlock`	Individual block entity. Manages block color, floor stacking (1–5 floors), HP, damage/death, gravity fall animation with landing bounce, neighbor shake effects, and bomb-targeting flash.
`BlastCannon`	Cannon entity with ammo count, color type, firing logic, and hidden/reveal mechanics. Shows "?" when hidden until moved to the front queue row.
`BlastProjectile`	Projectile flight from cannon to target block or obstacle. Handles arc trajectory, impact detection, and damage dealing.
`BlastObstacle`	2×2 merged gray block with HP. Occupies 4 grid cells, displays HP text, takes damage from any cannon color as fallback, and has its own gravity system.
`BoosterManager`	Manages three boosters (Shuffle, Bomb, Unlock) with progressive unlocking, use counts, tutorial popups, and button UI states (locked/active/depleted).
`LevelData`	Serializable data structures for levels: grid data, floor data, reserves, queue columns, cannon info, obstacles, locked slots, and booster counts. Includes `BlockType` enum and `BlastColors` palette.
`LevelManager`	Static class that loads level JSONs from `Resources/Levels/`, tracks the current level index via PlayerPrefs, and provides methods to advance, go back, or jump to any level.
`SoundManager`	Singleton audio system with named methods: `PlayBlockDestroy()`, `PlayObstacleHit()`, `PlayFloorRemove()`, `PlayCannonFire()`, `PlayCannonPlace()`, `PlayCannonDead()`, `PlayLevelWin()`, `PlayLevelFail()`, `PlayBoosterUse()`, `PlaySlotUnlock()`, `PlayButtonClick()`.
`LoseWinPanelManager`	Manages the Win and Lose UI panels. Auto-finds child panels by name. Supports auto-loading the next level after a configurable delay on win.

Utility Scripts

Script	Description
`BlastMeshHelper`	Static utility that loads the smooth-cube FBX mesh from Resources, caches it, and provides `CreateMeshObject()` for procedural block creation.
`BlastParticleManager`	Manages colored explosion and effect particles spawned on block/obstacle destruction.
`CameraSwitcher`	Switches the camera between multiple parent transforms (for multi-game setups). Persists the selected index via PlayerPrefs.
`DeveloperModeButton`	Toggles a developer settings panel on click. Auto-finds a child named `DeveloperSettingsPanel` if no reference is assigned.
`DeveloperSettingsController`	Developer panel with buttons for level navigation (next, previous, reload, trigger win/lose) and ad testing (show/hide banner, show/request interstitial, show/request rewarded).

Editor Scripts

Script	Description
`LevelEditorWindow`	Unity Editor window (`Tools > Blast Level Editor`) for visually designing levels with a grid painter.
`LevelGenerator`	Unity Editor window (`Tools > Blast Auto Level Generator`) for batch-generating levels with configurable parameters.
`BlockBlasterJamWelcomePopup`	Welcome popup that appears once per editor session with Asset Store review link and cross-promotion. Has a "don't show again" toggle.

Level Editor

Opening the Level Editor

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

Features

Level List — Browse, add, duplicate, reorder, and delete levels in the left panel
Grid Painter — Click cells on the grid to paint blocks with the selected color and floor count
Color Selection — Choose from 10 block colors (Red, Yellow, Blue, Green, Orange, Purple, Pink, Cyan, Lime, Magenta)
Floor Stacking — Set floor count (1–5) for painted blocks to create multi-hit blocks
Reserves — Configure reserve blocks per column that spawn from above during gameplay
Queue Columns — Set up cannon queues with color, ammo count, and hidden flag
Obstacles — Place 2×2 obstacles with configurable HP
Locked Slots — Set how many cannon slots start locked
Booster Counts — Configure uses per level for Shuffle, Bomb, and Unlock boosters
Save / Reload — Save all levels to disk as JSON, or reload from disk

Grid Painting

Setting	Effect
Paint Type (1–10)	Select which BlockType color to paint on the grid
Paint Floors (1–5)	Set the floor stack height for painted blocks
Click Cell	Place a block with the selected color and floor count, or click an existing block to clear it

Level Storage

All levels are stored as individual JSON files in Assets/Resources/Levels/ with the naming convention Level_1.json, Level_2.json, etc. They are loaded at runtime via Resources.LoadAll.

Automatic Level Generator

The Automatic Level Generator is an Editor tool that batch-generates levels procedurally with a configurable difficulty curve that interpolates from easy to hard across the batch.

Opening the Tool

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

Settings

Setting	Description
Levels to Generate	How many new level files to create. New levels are appended after existing ones (never overwrites).
Grid Cols / Rows (Min & Max)	Range for randomizing the grid dimensions (default: 5–9 cols, 5–12 rows).
Color Pool	10 toggleable colors (R, Y, B, G, O, P, Pk, C, L, M). Select which colors can appear. Colors per level: 2–5.
Empty Cell % (easy → hard)	Percentage of grid cells left empty. Easy: 5% → Hard: 0%. More empty = easier.
Reserves per Column (easy → hard)	Reserve blocks that spawn from above. Easy: 6 → Hard: 2.
Ammo per Cannon (easy → hard)	Shots each cannon gets. Easy: 25 → Hard: 8.
Slot Count (easy → hard)	Number of cannon slots available. Easy: 2 → Hard: 5.
Locked Slots (easy → hard)	Slots that start locked. Easy: 0 → Hard: 2.
Floor Stack Chance (easy → hard)	Probability of multi-floor blocks. Easy: 0% → Hard: 40%. Floor range: 1–3.
Hidden Cannon Chance (easy → hard)	Probability that queue cannons are hidden. Easy: 0% → Hard: 50%.
Obstacle Count (easy → hard)	Number of 2×2 obstacles. Easy: 0 → Hard: 3. HP range: 3–10.
Booster Uses (easy → hard)	Uses per booster per level. Easy: 2 → Hard: 1.
Queue Columns / Cannons per Column	Queue layout: 3–4 columns, 2–4 cannons each.

How It Works

Configure settings — adjust all parameters in the Editor window
Click "Generate Levels" — the tool detects existing levels and appends new ones
For each level, the generator:
- Randomizes grid size, color selection, and cannon counts within your ranges
- Interpolates difficulty settings based on position in the batch (t=0 easy, t=1 hard)
- Fills grid cells with colored blocks from the selected color pool
- Applies floor stacking based on the stack chance
- Places 2×2 obstacles with randomized HP
- Generates cannon queues with ammo and optional hidden flags
- Sets booster use counts and locked slot count
- Exports a JSON level file to Resources/Levels/

Non-Destructive

The generator never overwrites existing level files. It always starts numbering from the next available index (e.g., if Level_50 exists, new levels start from Level_51). Use the "Delete All Levels" button (with confirmation) to clear all levels before regenerating.

Boosters

The game includes three booster abilities that players can activate during gameplay. Each booster has a configurable number of uses per level and an optional tutorial popup that appears on first use. Boosters are progressively unlocked as the player advances through levels.

Booster	Unlock	Effect	Activation
Shuffle	Level 1	Randomizes all cannons across queue columns using Fisher-Yates shuffle. Useful when cannon colors don't match accessible blocks.	Tap the shuffle button. Instant effect.
Bomb	Level 2	Destroys all blocks within a 0.8-unit radius of the tapped cell. Ignores color matching. Great for clearing clusters.	Tap the bomb button to enter targeting mode (button highlights blue). Then tap a cell on the grid. Press Escape to cancel.
Unlock	Level 3	Unlocks the next locked cannon slot (left to right). Opens up more firing positions.	Tap the unlock button. Instant effect with unlock animation. Only visible if the level has locked slots.

Booster Button States

Locked — Shows "lvl X" text, button disabled, glow hidden
Available — Shows remaining use count, glow background visible
Active (Bomb only) — Button highlighted blue (#86BFFF) while waiting for target selection
Depleted — Darkened to 35% brightness when all uses consumed

Cheat Mode

Press the U key during gameplay to unlock all boosters immediately. This is useful for testing.

AdMob Ads

This project includes a Ragendom Monetization module for integrating AdMob ads (banners, interstitials, and rewarded videos). The ad system supports both real AdMob ads on device and a built-in Dummy ad provider for testing in the Unity Editor.

Documentation

Full setup and configuration instructions for the ad system are provided in a separate documentation file located at:

Assets/RagendomAds/Documentation/Documentation.html

That documentation covers AdMob app IDs, ad unit IDs, UMP/GDPR consent, test devices, and all monetization settings.

Video Tutorial

If you prefer a video walkthrough over reading documentation, watch the full ads setup tutorial here:

▶ Watch Ads Setup Tutorial on YouTube

Quick Overview

The ad system consists of the following key components in the scene:

[Monetization Init] — A GameObject with the MonetizationInitModule component. It initializes the ad system on Awake using the assigned MonetizationSettings asset.
MonetizationSettings — A ScriptableObject asset at Assets/RagendomAds/Modules/Monetization/MonetizationSettings.asset. Contains all ad provider configuration, timing, and consent settings.
AdsSettings — A sub-asset inside MonetizationSettings that controls which ad provider is used for each ad type (Banner, Interstitial, Rewarded Video). Defaults to the Dummy provider for editor testing.

Ad Types

Ad Type	Description
Banner	A small ad strip displayed at the top or bottom of the screen. Show and hide at any time.
Interstitial	A full-screen ad. Must be requested (loaded) first, then shown when ready. Supports cooldown timers and conditions.
Rewarded Video	A full-screen video ad that grants a reward on completion. Must be requested first, then shown. Always available regardless of no-ads purchases.

Testing in the Editor

By default, the ad system uses the Dummy provider, which displays test UI overlays in the Editor (a green "TEST BANNER" bar, dark "TEST INTERSTITIAL" overlay, and blue "TEST REWARDED VIDEO" overlay). This lets you verify the ad flow without needing a real device or AdMob account.

The Developer Settings Panel (accessible via the gear icon in-game) includes ad control buttons for testing: Show/Hide Banner, Show/Request Interstitial, and Show/Request Rewarded Video.

Customization Guide

Adding New Block Colors

Open LevelData.cs and add entries to both the BlockType enum and the color arrays in BlastColors:

public enum BlockType
{
    Red = 1, Yellow = 2, Blue = 3, Green = 4, Orange = 5,
    Purple = 6, Pink = 7, Cyan = 8, Lime = 9, Magenta = 10,
    // Add your custom colors here:
    Teal = 11,
}

// Then add matching entries in BlastColors:
// - mainColors[] (the block face color)
// - darkColors[] (the outline/accent color)
// - Labels[] (short label for editor, e.g. "T")
// - Names[] (display name, e.g. "Teal")
// - Increment COUNT
            

New colors are automatically available in the Level Editor and Auto Level Generator.

Adjusting Grid Visuals

The grid, blocks, and board are rendered procedurally in BlastBoardManager.cs. Key settings:

blockSize — Size of each block in world units (default: 0.28)
blockSpacing — Gap between blocks (default: 0)
fallSpeed — Gravity fall speed (default: 8 units/sec)
Board background color defined in BlastGameManager

Modifying Block Visuals

Block rendering uses smooth-cube meshes loaded from BlastMeshHelper. You can customize:

Mesh — Replace cube-smooth-3.fbx in Resources/ with your own mesh
Material — BlastMeshHelper.GetDefaultMaterial() creates a URP/Lit material with 0.759 smoothness
Floor stacking — Floor visuals are stacked vertically in BlastBlock.Init()
Death animation — Shrink duration, particle count in BlastBlock.Die()

Adding New Boosters

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

Add booster state fields (uses count, active flag, button reference)
Find the button in the HUD hierarchy (GameHUD_Panel/BottomHolder/Booster-Button-N)
Add an OnXxxClicked() handler method
Add tutorial popup support with a PlayerPrefs key
Add count fields to LevelData and update both editors

JSON Level Format

Each level is a JSON file with the following structure (simplified):

{
    "rows": 8,
    "cols": 6,
    "slotCount": 3,
    "lockedSlots": 1,
    "gridData": [0, 1, 2, 3, 0, 1, ...],   // row-major, 0=empty, 1-10=BlockType
    "floorData": [1, 1, 2, 1, 1, 3, ...],  // parallel to gridData, 1-5 floors
    "reserves": [3, 2, 4, 1, 2, 3],        // reserve blocks per column
    "queueColumns": [                       // cannon queues
        { "cannons": [
            { "type": 1, "ammo": 15, "hidden": false },
            { "type": 3, "ammo": 10, "hidden": true }
        ]}
    ],
    "obstacles": [                           // 2x2 obstacles
        { "row": 2, "col": 3, "hp": 5 }
    ],
    "shuffleBoosterCount": 3,
    "bombBoosterCount": 3,
    "unlockBoosterCount": 3
}
            

Grid data is flattened row-major: index = row * cols + col. gridData[0] is the top-left cell. BlockType values 1–10 correspond to the enum (Red=1 through Magenta=10), 0 = empty.

Support

Common Issues

Issue	Solution
No levels load / blank grid	Ensure JSON level files exist in `Assets/Resources/Levels/` with the naming convention `Level_1.json`, `Level_2.json`, etc. Use the Auto Level Generator to create levels.
Blocks appear as plain cubes (no smooth mesh)	Ensure `cube-smooth-3.fbx` exists in `Assets/Resources/`. The fallback is a primitive cube.
Locked slots show no lock icon	Ensure `lock-icon.png` exists in `Assets/Resources/`.
Purple/missing materials on WebGL	The game uses URP/Lit shaders. Ensure the `OutlineOnly` shader and URP pipeline assets are included in your build settings.
Dev panel buttons don't respond	If you added a `Canvas` component to the panel (e.g., for sorting order), you must also add a `GraphicRaycaster` component to the same object.
Level Editor shows empty grid	Click "Reload from Disk" in the Level Editor, or ensure the `Resources/Levels/` folder exists.

Tips

Use the Developer Settings Panel (gear icon) in Play mode to quickly navigate levels, trigger win/lose, and test ads
Press Right Arrow / Left Arrow during gameplay to jump to the next/previous level
Press U to unlock all boosters for testing
The Auto Level Generator is the fastest way to populate your game with content — generate hundreds of levels in seconds
Back up your Resources/Levels/ folder regularly

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!