Technical Overview

Toolkit The Hypercasual Game Engine is a modular framework designed for rapid development of puzzle and arcade mechanics. It provides a standardized architecture where game-specific logic is decoupled from core engine systems.

Core Design Patterns:

• Singleton Managers: Centralized control for game states and audio.
• Data-Driven Levels: Separation of level design (JSON/Assets) from game logic.
• Namespace Isolation: All scripts reside within HypercasualGameEngine or HypercasualGameEngine.{GameName} to prevent conflicts.

Getting Started

Opening the Main Scene

The primary game scene is located at:

Assets/Hypercasual Game Engine/Core/Scenes/Games-v4.0.unity

Open this scene to access all 20 game modules. Previous version scenes (Games.unity, Games-v2.0.unity) are also available in the same folder for reference.

Where to Find Level Editors

All level editor tools are located under the Unity Tools menu in the top menu bar. There is no separate "Hypercasual" tab. To open any level editor, go to:

Tools > #{number} {Game Name} Level Editor

For example: Tools > #1 Arrows Level Editor, Tools > #11 HoleLoopJam Level Editor, etc.

Project Structure

Understanding the directory layout is crucial for extending the engine.

Global Core (Assets/Hypercasual Game Engine/Core)

Game Modules (Assets/Hypercasual Game Engine/Games)

Each game folder is self-contained, including its own Scripts, Editor, Prefabs, and Levels. The folder naming convention is #{number}_{GameName}, for example: #1_Arrows, #7_ConveyorSort, #11_HoleLoopJam.

Scenes (Assets/Hypercasual Game Engine/Core/Scenes)

The current main scene is Games-v4.0. This is the scene you should open to play or test any of the 20 game modules.

#1 Arrow Escape

A logic puzzle where players must clear a grid of arrows. Arrows can only move in their pointed direction and are blocked by others.

Main Scripts:

#2 Block Associations

A drag-and-drop matching game. Players must organize items into sets to clear the board.

Main Scripts:

#3 Color Block Jam

A spatial puzzle where players move groups of blocks to clear paths. Blocks are constrained by their color-coded groups.

Main Scripts:

Setup Guide:

Levels are built using Prefabs. To create a new level:

1. Place GroundTile prefabs to form your floor.
2. Add ColorBlock prefabs and group them under an empty GameObject with DraggableBlockGroup.
3. Assign a Color to the group; all children will automatically inherit it.

#4 Jigsaw Puzzle

A classic jigsaw mechanic. It uses a custom masking system to allow any image to be turned into a puzzle piece.

Main Scripts:

#5 Drop the Dog Jam

A physics-and-timing game. Players must navigate dogs into holes by removing blocks in the correct order.

Main Scripts:

#6 Pixel Shooter 3D

A color-matching puzzle-shooter. Players manage a conveyor belt of "pigs" that automatically shoot colored bullets at same-colored blocks on a grid. The challenge lies in strategic pig selection and resource management.

Main Scripts:

Key Mechanics:

• Tray/Trace System: Limited number of trays control how many pigs can be launched onto the belt. Trays animate from a stack to an equip position.
• Belt Path: Pigs move along a smooth curved path defined by 4 corner transforms with Bezier-blended corners.
• Holding Slots: After completing a belt run, pigs are stored in holding slots. If all slots fill up, the game is lost.
• Abilities:
  • Hand Picker — Select any pig from the deck, not just the front of the line.
  • Shuffle — Randomize the pig deck column order.
  • Super Shoot — Spawns a special pig with 25 ammo that shoots any block.
  • Extra Tray — Adds one additional tray/trace to the supply.

#7 Topic Stack

A sorting puzzle where players move themed items between conveyor columns. Items must be grouped by category to lock in columns and clear the board.

Main Scripts:

Key Mechanics:

• Selection: Clicking a column selects all consecutive top items of the same category. They levitate with a bobbing animation.
• Movement: Clicking a different column moves selected items if space is available. Items fly in a smooth arc to their new slots.
• Lock-In: When a column is full with matching items, it locks with a visual squash effect and becomes unselectable.
• Win Condition: All non-empty columns must be locked.
• Categories: Kitchen (orange), Ice Cream (light blue), Winter (blue), School (green).

#8 Solitaire Associations

A card-based puzzle combining solitaire mechanics with category matching. Players drag cards from the tableau and draw pile onto foundation slots to complete category sets within a limited number of moves.

Main Scripts:

Key Mechanics:

• Foundations: Each slot starts empty. Place a category card first, then fill it with matching item cards. Cards are locked once placed in a foundation.
• Hints: Prioritized system — first checks foundation moves, then productive tableau moves (ones that reveal face-down cards), then suggests drawing from the deck.
• Undo: Full move reversal including card state restoration, face-down re-hiding, and move refund.
• Win Condition: All foundation slots completed. Each completed category plays a scale-up/shrink animation and disappears.
• Lose Condition: Running out of moves (when maxMoves > 0).

#9 Coffee Go

A conveyor-based sorting puzzle. Players tap trays to eject mismatched coffee cups onto a conveyor belt, which automatically routes them to the correct color-matched tray.

Main Scripts:

Key Mechanics:

• Sorting Flow: Tap a tray to send wrong-colored coffees to the conveyor. The conveyor auto-delivers them to matching trays.
• Parabolic Paths: Coffees travel in smooth arc trajectories (5-point parabolic curves) between trays and the conveyor.
• Win Condition: All trays are filled with their matching color.
• Lose Condition: The conveyor stays at max capacity for a configurable countdown duration.
• Level Data: JSON-based with configurable conveyor settings (max slots, speed, countdown) and per-tray definitions (color, slot count, initial coffees).

#10 Bricky Bounce

A 3D brick-breaking puzzle. Players select colored boxes from a board to launch balls through a conveyor system at a multi-layered brick grid. Balls seek out same-colored bricks and destroy them with physics-based break effects.

Main Scripts:

Key Mechanics:

• Board & Dock: Click a box on the board to move it to a dock slot. Boxes must have a valid exit path (validated via BFS through neighboring canExit boxes).
• Ball Routing: Balls travel through a conveyor path, then navigate the brick grid using A*-style pathfinding to reach the furthest matching-color brick.
• Brick Destruction: On impact, bricks play an elastic squash animation followed by a physics explosion with randomized radial force, torque, and gradual debris fade.
• Win Condition: All bricks destroyed (countBricks <= 0).
• Lose Condition: All dock slots are full and no matching-color bricks remain in the grid for any occupied dock color.
• Data-Driven: Levels use ScriptableObjects (GameData) with board rows, grid layers, color assignments, and per-box properties (ball count, hidden state, exit permissions).

#11 Hole Loop Jam

A conveyor-loop puzzle where players tap colored pots from a spawn queue to send them onto a grid-based loop system. Matching-colored blocks on the grid automatically pathfind and jump into passing pots. Once a pot is fully filled, it's destroyed with a particle effect. Win by filling and destroying all pots before the loop runs out of dock space.

Main Scripts:

Key Mechanics:

• Grid-Based Pathfinding: Uses BFS (Breadth-First Search) to find the shortest path from any block to the pot location on the grid.
• Conveyor Loop: Pots move through a series of ApplyState positions in a continuous loop around the grid, collecting matching blocks as they pass.
• Color Matching: Only blocks matching a pot's color will pathfind and jump into that pot with a parabolic arc animation.
• Pot Destruction: When a pot reaches its target fill count, it shrinks and explodes with particle effects.
• Blocking Mechanics: Obstacle blocks can block paths; hidden blocks are revealed when obstacles are removed.
• Win Condition: All pots have been filled and destroyed.
• Lose Condition: A pot completes its loop and there's no available dock to return it to.
• Level Data: JSON-based with configurable grid dimensions, per-cell block definitions (color, hidden, obstacle), and ordered pot data lines.

#12 Coffee Color Block

A color-matching puzzle where players drag shaped blocks onto a grid to position them near conveyors. Conveyors spawn colored coffee cups that automatically transfer into matching-colored blocks when they overlap. Each block has multiple slots (holes) that must be filled with cups. When all slots on a block are filled, the block clears with a slide-out animation. Complete all blocks before time runs out to win.

Main Scripts:

Key Mechanics:

• Block Dragging: Players click and drag blocks with physics-based movement. Blocks slide along obstacles and snap to the nearest grid position on release.
• Coffee Conveyors: Multiple conveyors spawn sequences of colored coffee cups. Each conveyor can have multi-color sequences that advance as cups are consumed.
• Color Matching: Coffee cups only transfer from a conveyor to a block when their colors match. The conveyor's active color changes as each color sequence completes.
• Block Filling: Each block has multiple cup slots. Cups arc-animate into slots one at a time. When all slots are filled, the block clears automatically.
• Block Clear Animation: Filled blocks pull back slightly, then slide off-screen with a rotation effect.
• Grid Occupancy: Blocks use shape definitions to occupy multiple grid cells, preventing overlap with other blocks.
• Win Condition: All blocks have been filled and cleared.
• Lose Condition: The countdown timer expires before all blocks are cleared.
• Level Data: JSON-based with configurable grid dimensions, spacing, timer, block definitions (color, rotation, position, shape offsets, cup slots), and ordered conveyor queue.

#13 Color Brick Loop

A casual puzzle game where players click on colored boxes to push bricks onto a circular conveyor belt path. Bricks move around the conveyor, and a cannon at the end fires at matching-colored goal bricks on the top board. Players must clear all goal colors in sequence to win the level.

Main Scripts:

Key Mechanics:

• Box Clicking: Clicking a box slides it forward onto the conveyor path. The lid flies open with animation and bricks spawn at predefined positions inside.
• Conveyor Circulation: Bricks move step-by-step around a circular path. Movement is blocked if the next node is occupied or if bricks are still spawning.
• Cannon & Color Matching: When a brick of the current goal color reaches the tunnel node, a bullet is fired at the corresponding goal brick on the top board, which pops with a scale animation.
• Goal Sequence: Players must eliminate all bricks of the first goal color, then the second, and so on until all goals are cleared.
• Win Condition: All goal colors have been eliminated successfully.
• Lose Condition: The conveyor becomes completely full and none of the bricks match the current goal color.
• Level Data: JSON-based with a color grid (rows x columns of EColor values) and an ordered goal color sequence.

#14 Good Swipe

A swipe-based sorting puzzle where players swipe the grid in four directions to move boxes and arrange items. The goal is to group matching items (Can, Ice, Duck) within the same box. When all 4 items in a box match, the box clears and fills collection targets. Complete all targets to win.

Main Scripts:

Key Mechanics:

• Swipe System: Detects mouse swipes (50-pixel minimum) and moves all boxes in that direction to fill gaps in the grid.
• Item Swapping: After movement, the system attempts optimal swaps between adjacent boxes to match item types together.
• Box Clearing: When all 4 items in a box match the same type, the box vanishes with animation and collection counters decrement.
• Grid Refactoring: After each swipe, boxes move, items swap, boxes clear, and new boxes spawn randomly in empty slots with a bounce effect.
• Point System: Awards points for item arrangements (1 item = 1pt, 2 = 5pts, 3 = 20pts, 4 = 100pts) with combo bonuses.
• Win Condition: All collection targets reach zero.
• Lose Condition: Grid fills completely with no valid adjacent swaps possible.
• Level Data: JSON-based with configurable grid dimensions, fill targets (item type + required count), and box definitions (grid position + item list).

#15 Drop Marbles

A marble-sorting puzzle where players click on colored boxes to release marbles that scatter in all directions. The released marbles roll onto a conveyor belt that routes them toward color-matched target slots (FillBoxes). Fill all target slots to win before the conveyor becomes overloaded.

Main Scripts:

Key Mechanics:

• Marble Release: Clicking a box releases all marbles inside in a circular spread pattern using physics impulse forces. Marbles scale up as they scatter.
• Conveyor Belt: An active conveyor rotates marbles along a fixed path. Marbles move to the next position each cycle with smooth interpolation.
• Color Matching: Marbles must match the exact color of their target FillBox to be accepted. Mismatched colors pass through.
• FillBox Completion: When a FillBox receives 3 matching-colored marbles, it's marked full and removed. Remaining boxes animate upward to fill the gap.
• Win Condition: All FillBoxes have been filled and removed.
• Lose Condition: All conveyor slots are filled and no active marbles can reach available matching targets.
• Level Data: JSON-based with configurable grid dimensions, box item definitions (color per marble), and fill column definitions (ordered target colors).

#16 Sand Flow Puzzle

A color-matching puzzle where players manage sand flow through buckets and a conveyor belt. Click colored buckets on a grid to send them onto a moving belt, where they automatically absorb matching-color sand from an 80x80 pixel art display. Fill each bucket to clear it, and empty all the sand to win.

Main Scripts:

Key Mechanics:

• Sand Gravity: Sand pixels fall and spread using cellular automaton rules with randomized sub-steps for natural behavior.
• Bucket Suction: Belt buckets extract matching-color pixels from the bottom of the sand display as they pass over it, with flying block particle effects.
• Boosters: Slot (+1 belt capacity), Shuffle (randomize grid bucket positions), Magic Wand (click any bucket regardless of neighbor rules).
• Win Condition: All sand pixels cleared from the display and no particles remaining.
• Lose Condition: All belt slots full and every bucket has completed a full loop without extracting any sand.

#17 Snake Out

A grid-based puzzle where players drag colored snakes to guide them into matching-color holes. Snakes can be moved from either their head or tail, and must navigate around obstacles and other snakes to reach their exit.

Main Scripts:

Key Mechanics:

• Bidirectional Movement: Snakes can be dragged from either their head or tail, allowing strategic repositioning.
• Grid Pathfinding: Movement is validated against grid boundaries, obstacles, and other snake segments.
• Color Matching: Each snake must enter a hole of the same color. Mismatched holes are blocked.
• Time Limit: Configurable per level (default 120 seconds).
• Win Condition: All snakes have entered their matching holes.
• Lose Condition: Time runs out before all snakes are matched.

#18 Donut Master

A matching and assembly puzzle where players arrange colored donuts on a top-down board to match target shapes. Donuts arrive in boxes via conveyor lines and must be dragged onto the board to fill designated patterns.

Main Scripts:

Key Mechanics:

• Shape Matching: Donut boxes come in various shapes (2x2, 1x1, 1x2, L-shapes) that must fit target patterns on the board.
• Conveyor Lines: Multiple lines deliver boxes sequentially. Completing a box advances the line.
• Color System: 4 donut colors (Purple, Cyan, Pink, Yellow) that must match target positions.
• Win Condition: All target positions on the top board are filled with correctly colored donuts.

#19 StackFill

A 3D block-stacking puzzle where players fill a three-dimensional grid with colored blocks according to wall constraints. Tap to place blocks from a dock into valid positions defined by colored walls on XY and YZ planes.

Main Scripts:

Key Mechanics:

• 3D Grid: Fully three-dimensional playfield with configurable X, Y, Z dimensions.
• Wall Constraints: Colored walls on XY (horizontal) and YZ (vertical) planes define which colors can be placed in each position.
• Tap-to-Place: Select a block from the dock and tap a valid grid position to place it.
• Win Condition: All grid positions filled according to wall constraints.

#20 Crowd To Bus

A color-sorting puzzle where players move groups of colored people on a grid to match them with bus compartments. Drag people groups to valid grid positions and guide them onto buses with matching-color slots.

Main Scripts:

Key Mechanics:

• Color Matching: 6 people colors (Yellow, Red, Green, Orange, Purple, Blue) that must match bus compartment colors.
• Grid Movement: Drag people groups to valid positions on the grid, respecting placement constraints.
• Pedestal System: Visual markers indicate valid placement positions on the grid.
• Win Condition: All people groups matched to their corresponding bus compartments.

Core Systems & Utilities

LoseWinPanelManager

A global UI controller. It listens for events from any LevelManager and triggers the appropriate overlay. It is designed to be "Plug and Play" — just drop the prefab into your scene's Canvas.

Animation System

The engine includes a lightweight animation system (PositionAnimation.cs, ScaleAnimation.cs, RotationAnimation.cs) that allows for tween-like behavior without external dependencies.

Ads Monetization

The Hypercasual Game Engine ships with a complete ad monetization system powered by RagendomAds. It supports Banner, Interstitial, Rewarded Video, and App Open Ad formats out of the box, with Google AdMob integration ready to go.

Documentation

Full setup instructions, API reference, and configuration guides are available in the dedicated RagendomAds documentation:

Assets/RagendomAds/Documentation/Documentation.html

Video Tutorial

Watch our setup walkthrough to get ads running in your project:

Watch on YouTube

Key Features:

• All ad formats: Banner, Interstitial, Rewarded Video, and App Open Ads.
• Provider-agnostic: Swap between AdMob and Dummy providers via a ScriptableObject — no code changes needed.
• Frequency capping: Built-in cooldown and level-interval settings for interstitials.
• No-ads purchase support: A single method call disables banners and interstitials while keeping rewarded videos available.
• Editor testing: Dummy ad provider shows simulated ad UIs directly in the Unity Editor.

Development Guide

Creating a New Game Module:

1. Folder Setup: Create Assets/Hypercasual Game Engine/Games/#X_Name.
2. Manager: Create a script inheriting from LevelManager.

   public class MyGameManager : LevelManager { ... }

3. UI Integration: Ensure your scene has an EventSystem and a Canvas with the LoseWinPanel prefab.
4. Namespace: Wrap all code in namespace HypercasualGameEngine.YourGameName { ... } or a dedicated namespace like namespace YourGameName { ... }. Games #1-5 use the shared HypercasualGameEngine namespace; games #6-15 use the HypercasualGameEngine.{GameName} sub-namespace convention; standalone games (#16-20) use their own top-level namespaces (e.g. SandFlowPuzzle, SnakeOut).

Support

Need help with the engine? Have questions about a specific mechanic or want to report a bug?

We aim to respond to all support inquiries within 24-48 hours. Please include your order number and a detailed description of your issue for faster assistance.

Version History

v4.0 - Major Update (Current)

The fourth major release adds 5 brand new game modules, bringing the total to 20. This update introduces 3D gameplay mechanics, image-based level generation, and two new standalone Asset Store titles:

• #16 Sand Flow Puzzle: Sand physics puzzle with conveyor belt suction, 80x80 pixel art displays, and 3 booster types. Visual level editor with image quantization and bucket grid painting. Also available as a standalone asset.
• #17 Snake Out: Grid-based snake pathfinding puzzle with bidirectional drag movement, color-matched holes, and animated snake characters. Level editor with grid painter. Also available as a standalone asset.
• #18 Donut Master: Shape-matching assembly puzzle with multi-line conveyors delivering donut boxes in various shapes (2x2, L-shaped, etc.) onto a target board. Visual level editor for conveyor and board layout.
• #19 StackFill: 3D block-stacking puzzle with wall constraints on XY and YZ planes. Tap-to-place mechanics in a fully three-dimensional grid. Level editor window with JSON save/load and custom inspector with XY/YZ grid editors.
• #20 Crowd To Bus: Color-sorting puzzle where players move 6-color people groups on a grid to match them with bus compartments. Two-panel level editor with grid painter, box management, and car column configuration. Also available as a standalone asset.

Price: $99

v3.0 - Major Update

The third major release adds 5 brand new game modules, bringing the total to 15. All new games include custom level editors with JSON-based level management and a unified two-panel editor layout:

• #11 Hole Loop Jam: Conveyor-loop puzzle with BFS pathfinding and pot-filling mechanics. Level editor with visual grid painter and pot data line builder.
• #12 Coffee Color Block: Color-matching conveyor puzzle where coffee cups fill shaped blocks on a grid. Level editor with block shape editor, conveyor queue builder, and Capture from Scene support.
• #13 Color Brick Loop: Circular conveyor belt puzzle with cannon-based goal elimination. Level editor with color grid editor and goal color sequence builder.
• #14 Good Swipe: Swipe-based item sorting puzzle with combo scoring and collection targets. Level editor with fill target and box placement editors.
• #15 Drop Marbles: Physics-based marble release and conveyor routing puzzle with color-matched fill targets. Level editor with box item and fill column editors.

Price: $39.99

v2.0 - Major Update

The second major release adds 5 brand new game modules, bringing the total to 10:

• #6 Pixel Shooter 3D: Color-matching puzzle-shooter with conveyor belt and abilities.
• #7 Topic Stack: Category-based item sorting with lock-in mechanics.
• #8 Solitaire Associations: Card-based solitaire with category matching, hints, and undo.
• #9 Coffee Go: Conveyor-based coffee cup color-sorting puzzle.
• #10 Bricky Bounce: 3D layered brick-breaking with ball routing and physics destruction.

Price: $34.99

v1.0 - Initial Release

The first release of the Hypercasual Game Engine includes 5 fully functional game modules:

• #1 Arrow Escape: Grid-based logic puzzle.
• #2 Block Associations: Drag-and-drop matching mechanic.
• #3 Color Block Jam: Spatial group-movement puzzle.
• #4 Jigsaw Puzzle: Dynamic texture-slicing puzzle.
• #5 Drop the Dog Jam: Physics-based SDF hole mechanic.

Launch Price: $29.99