Bus Out Crowd Jam

Overview

Bus Out Crowd Jam is a crowd-sorting puzzle game where players tap buses to dock them at parking slots, and matching colored people walk from the grid to their corresponding bus. Clear all people from the grid by filling every bus to win the level. The game features 3D animated characters, a built-in level editor, an automatic level generator, a booster system, and full AdMob ad integration via RagendomAds.

Getting Started

Requirements

• Unity 6 or newer
• Universal Render Pipeline (URP)
• TextMesh Pro (included with Unity)

Installation

1. Import the Bus Out Crowd Jam 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/Bus Out Crowd Jam/Scenes/SampleScene.unity
4. Press Play to test the first level

Quick Test

Once in Play mode, tap any bus at the front of a queue to dock it at an available parking slot. Matching colored people on the grid will automatically walk toward the docked bus and board it. When all buses are filled and all people have boarded, the level is cleared and the next level loads automatically.

Folder Structure

Gameplay

Core Mechanics

Each level features a grid of color-coded people (grouped into "boxes"), a queue of color-coded buses arranged in columns, and a set of parking dock slots. The goal is to clear all people from the grid by filling every bus with matching colored passengers.

• Tap to dock — Tap a bus at the front of its queue to send it to an available parking dock slot
• Color matching — People on the grid automatically walk to the docked bus that matches their color
• Bus capacity — Each bus has a capacity number; when all seats are filled, the bus departs with a completion effect
• Queue order — Only the front bus in each column can be tapped (unless the Pick Any booster is active)
• Parking slots — Limited dock slots mean you must plan which buses to dock first; a full dock blocks new buses
• VIP docks — Some parking slots are locked (VIP) and must be unlocked with the VIP Dock booster
• Pathfinding — People use BFS pathfinding to navigate from their grid position to the bottom edge and then to their bus

People Colors

The game supports six predefined people/bus colors defined in the TypeColor enum:

Win & Lose Conditions

• Win — All bus queue columns are empty (every bus has been docked and filled). The level index advances and the next level loads automatically.
• Lose — All parking dock slots are occupied by buses that cannot be filled (no matching people remain on the grid, or the grid is blocked). The Game Over panel appears with a Retry button that reloads the current level.

Animations

People on the grid have four animation states: idle (default standing), run (triggered when moving toward a bus), sitDefault (seated inside a bus), and standUp (transitioning from seated to standing). Buses have a particle burst effect on completion and smooth movement animations when docking and departing.

Scripts Reference

Runtime scripts use the BusOutCrowdJam namespace. Editor scripts use the BusOutCrowdJam.Editor namespace.

Core Scripts

Utility Scripts

Editor Scripts

Level Editor

Opening the Level Editor

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

Features

• Level List — Browse, add, duplicate, reorder (up/down), and delete levels in the left panel
• Grid Painter — Click cells on the grid to paint colored people groups (boxes) or erase them
• Paint Modes — Select a mode from the toolbar: None, Box, Erase
• Color Selection — Choose a people color when in Box paint mode (Yellow, Red, Green, Orange, Purple, Blue)
• Box Management — Add/remove people groups (boxes) per level, change colors, clear positions, select for painting
• Car Columns — Configure bus queue columns with individual buses: set color and capacity for each bus
• Grid Settings — Adjust grid width and height per level
• Save / Reload — Save all levels to disk as JSON, or reload from disk with confirmation

Paint Modes

Level Storage

All levels are stored as individual JSON files in Assets/Bus Out Crowd Jam/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 playable puzzle levels procedurally. It uses region-growing grid partitioning with configurable difficulty curves to create varied, balanced levels.

Opening the Tool

In the Unity menu bar, go to Tools > Bus Out Crowd Jam > 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:
   • Randomizes grid size, color count, and region size within your ranges
   • Interpolates difficulty settings based on position in the batch (aggressive curve: levels 1–5 easy, 6–50 fast ramp, 51+ hard)
   • Partitions the entire grid into colored regions using a region-growing algorithm with random seeds
   • Converts contiguous same-color regions into box data (people groups)
   • Generates bus cars with capacities that exactly match the total people count per color
   • Distributes buses across queue columns in a shuffled round-robin pattern
   • Falls back to a simple striped layout if region-growing fails after 20 attempts
   • Exports a JSON level file to Resources/Levels/

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 data) and an optional tutorial popup that appears on first use.

Booster Buttons

Booster buttons are found in the GameHUD_Panel/BottomHolder in the scene UI. 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 active-mode tint (light blue: rgba(134, 191, 255)) when Pick Any mode is waiting for a target click
• Lock by level — boosters unlock at configurable levels (default: Shuffle at level 1, Pick Any at level 2, VIP Dock at level 3)

Cheat Mode

Press the U key during gameplay to unlock all boosters and refill their usage counts. Press Right Arrow / Left Arrow to jump to the next/previous level. These shortcuts are useful for testing.

AdMob Ads

This project includes the RagendomAds 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:

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/Bus Out Crowd Jam/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

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 Colors

To add a new person/bus color:

1. Open LevelData.cs and add a new entry to the TypeColor enum:
   public enum TypeColor { Yellow, Red, Green, Orange, Purple, Blue, // Add your custom color: Pink }
2. Open LevelDataJson.cs and add the color to the BusCrowdColors.colors dictionary:
   { TypeColor.Pink, new Color32(255, 107, 129, 255) },
3. Create a new Material in Art/Materials/Color/ with the desired color
4. Add the new color mapping to the ColorData ScriptableObject in Datas/Colors/

New colors 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 properties:

• gapBetweenCells — Spacing between grid cells in world units (adjustable in the Inspector)
• pedestalPrefab — The ground pedestal placed under each person
• pedestalDefaultMaterial — Default material for empty pedestals
• hiddenMaterial / hiddenMaterial2 / hiddenMaterial3 — Materials for hidden/transition states

Modifying Bus Visuals

Bus rendering is handled by the Car component. Each bus prefab includes:

• MeshRenderer — The bus body; material is set at runtime from ColorData
• Outline effect — Uses the CarOutline shader loaded from Resources; outline meshes are created/destroyed dynamically by TapOutManager
• Particle system — Completion burst effect when a bus is fully loaded
• TextMeshPro text — Displays remaining capacity count

Modifying People Visuals

People use SkinnedMeshRenderer with material coloring and Animator for character animations. To change the character model, replace the prefab mesh and ensure the Animator has triggers for run and standUp.

Adding New Boosters

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

1. Add booster state fields (use count, active flag, UI references)
2. Wire up the button in HookUpExistingBoosters() following the HookUpBoosterButton() pattern
3. Implement the booster logic in a new click handler method (e.g., OnMyBoosterClicked())
4. Add booster count fields to JsonLevelData and LevelData so it can be configured per level
5. Update UpdateBoosterUI() to handle the new booster's lock/unlock/count display

JSON Level Format

Each level is a JSON file with the following structure:

The boxes array defines colored people groups on the grid. Each box has a typeColor (integer matching the TypeColor enum) and a list of grid positions. The carColumns array defines bus queues, where each column contains a list of cars with amount (passenger capacity) and typeColor. Grid coordinates are zero-indexed with (0,0) at the top-left corner.

Support

Common Issues

Tips

• Use the Developer Settings Panel (gear icon) in Play mode to quickly navigate levels, trigger win/lose, unlock boosters, and test ads
• 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 500+ levels in seconds
• Car capacities in generated levels exactly match the total people count per color, ensuring every level is solvable
• Back up your Resources/Levels/ 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!