Bubble Shooter

Developer Documentation

Unity 2022.3.62f3 LTS · Android & iOS · 1,115 Levels

Ghost Studio · 2024

Getting Started — Opening & Running the Project
Level Editor — Creating and Editing Levels
Reskin Guide — Sprites, Fonts, Sounds & Colors
IAP & Configuration — In-App Purchases & Economy

1. Getting Started

1.1 Requirements

Item	Value
Unity Version	2022.3.62f3 LTS (exact version required)
Render Pipeline	Universal Render Pipeline (URP)
Target Platforms	Android / iOS
Scripting Backend	IL2CPP (recommended)
Minimum API Level	Android 5.0 (API 21) / iOS 12
Third-party Plugin	DOTween (Demigiant) — included
Spine Runtime	Spine Unity — included in Assets/Spine

1.2 Opening the Project

Install Unity Hub — download from unity.com/download if not already installed.
Install Unity 2022.3.62f3 LTS — open Unity Hub → Installs → Install Editor → select 2022.3.62f3. Add the Android Build Support and iOS Build Support modules.
Open the project — click Open in Unity Hub and navigate to the BubbleShooter/ folder (the one that contains Assets/ and ProjectSettings/).
Wait for import — Unity will import all assets on first open. This may take several minutes. Do not interrupt.
Resolve any compilation errors — if a popup asks about package manager updates, click Continue. URP and Spine packages are already included.

Unity Editor with Loading scene — Figure 1.1 — Unity Editor showing the Loading scene with the Bubble Shooter splash screen in Game view

1.3 Scene Structure

The project contains three scenes that must be added to Build Settings in the order shown below. The game starts from Loading and transitions automatically through the flow.

Build Index	Scene	Path	Role
0	Loading	`Assets/Game/Scenes/Loading.unity`	Splash screen, initialise managers
1	Main	`Assets/Game/Scenes/Main.unity`	Home screen, map, menus
2	Level	`Assets/Game/Scenes/Level.unity`	Gameplay, in-game UI

Important: Always set the Loading scene as Build Index 0. Go to File → Build Settings, click Add Open Scenes for each scene, and drag them into the correct order.

1.4 Running in the Editor

Open Assets/Game/Scenes/Loading.unity.
Switch to the Game tab and set the resolution to iPhone 12 Pro Max or any 9:19.5 portrait resolution.
Click the Play button. The game starts from the loading screen and transitions to the main menu.
To test a specific level directly, open Level.unity and use the Level Editor (see Section 2).

1.5 Building for Android / iOS

Open File → Build Settings. Select the target platform, click Switch Platform, then configure Player Settings:

Android: set Package Name (e.g. com.yourcompany.bubbleshooter), Minimum API 21, Target API Latest, Scripting Backend = IL2CPP.
iOS: set Bundle ID, signing team, and iOS Target SDK = Device SDK.
Click Build And Run (or Build to get the APK/Xcode project).

2. Level Editor

Bubble Shooter includes a full custom Level Editor built into the Unity Editor. It lets you design bubble layouts, set win conditions, configure difficulty, and manage all 1,115+ levels without writing any code.

2.1 Opening the Level Editor

With the project open in Unity, go to Window → Level Editor:

Figure 2.1 — Window menu with Level Editor entry

The Level Editor window opens as a floating panel. You can dock it or leave it floating. It has four tabs:

Tab	Purpose
Editor	Main tab — design the bubble grid for a level
A/B Testing	Reserved for A/B test variants (currently disabled)
Items	Configure special item behaviour
Settings	Clear the current level grid

2.2 Editor Overview

Figure 2.2 — Level Editor open on Level 1. Left: bubble grid (11 columns). Right: configuration panel.

The Editor tab has two areas:

Area	Description
Left — Grid	The hexagonal bubble grid (11 columns × variable rows). Click a cell and then click a bubble type to place it. Click an occupied cell to remove it.
Right — Config	Level settings: number, limit type, star thresholds, bubble palette, and bullet pool.

2.3 Configuration Panel Reference

Field	Description	Example
Level	Level number to load/save (1–1115). Use the arrows or type.	1
Limit	Win condition: MOVES (total shots) or TIME (seconds).	MOVES / 35
Is Hard Level?	Toggle to mark a level as 'hard' (shows a flame icon).	false
Star 1/2/3	Score thresholds for each star rating.	5,000 / 10,000 / 15,000
LevelField	Switch to the bubble palette to paint the grid.	(tab)
LevelBullet	Define the shooter queue — the sequence of bubbles the player fires.	(tab)

2.4 Bubble Types (Palette)

All bubble types are defined in Assets/Game/Scripts/GameConstant.cs as the BallType enum. The palette groups them into rows:

Row	Type Group	Colours / Variants
1	Normal Balls	Blue, Cyan, Pink, Red, Orange, Green
2	Plus Balls	Same 6 colours with a +1 score bonus on pop
3	Minus Balls	Same 6 colours — penalise the shot count
4	Paint Balls	Convert adjacent bubbles to their colour on pop
5	Ghost Balls	Invisible until hit; appear in 6 matching colours
6	Ghost Off	Revealed ghost (already visible)
7	Special	Metal Ball, Black Hole, Ice Ball, Random, Key, Morph
8	Rescue Girls	Characters to rescue (4 variants) — collectible objective
9	Duo Balls	Split-colour balls (15 combinations)

2.5 Editing an Existing Level

Open the Level Editor (Window → Level Editor).
Type the level number in the Level field and press Enter (or use the arrows). The grid loads automatically.
Select a bubble type by clicking its icon in the LevelField tab on the right panel.
Click any cell in the grid to place that bubble. Click an occupied cell to remove it.
Adjust Limit, Stars and Is Hard Level? as needed.
Changes are saved automatically to Assets/Game/Resources/Levels/level-{N}.txt.

2.6 Adding a New Level

Click New level in the configuration panel. The level number increments to the next slot.
Paint the grid with the desired bubble layout.
Set Limit (MOVES recommended), Stars, and optionally mark it Hard.
Switch to LevelBullet and configure the shooter queue (each slot maps to a BallType).
The level file is saved to Assets/Game/Resources/Levels/ as a .txt file.
Update MAX_LEVEL in GameConstant.cs if you exceed 1,115 levels.

Tip — Test a Level: Click Test level in the configuration panel. Unity enters Play mode and loads the level directly so you can play it immediately.

3. Reskin Guide

All visual and audio assets are organised under Assets/Game/Assets/. You can swap any asset by replacing its file — keep the same filename and texture settings so existing references stay intact.

3.1 Sprites

Sprites live in Assets/Game/Assets/Textures/. Key sub-folders:

Folder	Contents
`sprites/ball-bubbles/`	Main gameplay bubbles — all BallType variants (PNG sprite sheets)
`sprites/UI/`	General UI elements (buttons, frames, backgrounds)
`sprites/popup-bg/`	Popup window backgrounds
`sprites/level-btn/`	Level select button states (locked, 1-star, 2-star, 3-star)
`sprites/tutorial/`	Tutorial hand / arrow overlays
`sprites/text-image/`	Stylised text images (title logos, combo text)
`sprites/rescue-girls-blackout/`	Silhouettes shown before rescue characters are unlocked
`sprites/9-chest/`	Treasure chest animation frames
`Textures/icon/`	App icon assets (iOS and Android sizes)
`Textures/Loading/`	Loading screen background
`Textures/UI/challenge/`	Challenge mode UI elements

How to swap a sprite: Find the PNG in the Project window, select it, and verify the Texture Type (Sprite 2D and UI) and Pixels Per Unit match the original. Then right-click → Show in Explorer and paste your replacement PNG with the same filename.

3.2 Fonts

All font files are in Assets/Game/Assets/Font/:

File	Usage
`000CCBattleCryTB-Regular.otf`	Primary display font — level numbers, score, headings
`HP-Vari Bold.TTF`	Secondary bold font — UI labels, button text
`Font/TMProAssets/`	TextMesh Pro font atlas files (auto-generated)

To replace a font: drop your .ttf or .otf into Assets/Game/Assets/Font/, then in the TextMesh Pro font asset (TMProAssets/), update the Source Font File reference and click Generate Font Atlas.

3.3 Sounds

All sound effects and music are in Assets/Game/Assets/Sounds/ as .mp3 files. They are referenced by string constants in GameConstant.cs:

Constant	File	Event
`AUDIO_MUSIC_GAME`	music_ingame	In-game background music
`AUDIO_MUSIC_MAIN`	music_menu	Main menu background music
`AUDIO_BUBBLE_SHOOT`	bubble_shoot.mp3	Player fires a bubble
`AUDIO_BUBBLE_POP`	bubble_pop1.mp3	Bubble pops
`AUDIO_BUBBLE_CLEAR`	clear_bubbles1–6.mp3	Group of bubbles cleared
`AUDIO_PLAY_CLEAR`	play_clear.mp3	Level complete
`AUDIO_PLAY_FAIL`	play_fail.mp3	Level failed
`AUDIO_ITEM_BOMB`	item_fire.mp3	Bomb booster used
`AUDIO_ITEM_RAINBOW`	item_rainbow.mp3	Rainbow booster used
`AUDIO_ITEM_LIGHTNING`	item_lightning.mp3	Lightning booster used
`AUDIO_CLICK`	common_button.mp3	Generic UI button tap
`AUDIO_EAT_COIN`	common_getcoin.mp3	Coin collected

To replace a sound, place your new .mp3 in the same folder with the exact same filename. Unity will automatically use it on the next play.

3.4 Colours

UI colours are set on individual UI components in the Unity scene. The most impactful changes:

Background gradient — sprites/gradationMainMenu.png controls the main menu gradient.
Bubble tints — the sprite sheets in sprites/ball-bubbles/ define all bubble colours. Replace the PNGs.
URP settings — post-processing is configured in URPAsset.asset and URPShader.asset.
Shader Graph materials — custom shaders in ShaderGraph/ control special effects.

3.5 Assets Container (Scriptable Object)

The file Assets/Game/Assets/Assets Container.asset is a ScriptableObject that holds references to all in-game sprites and prefabs. Select it in the Project window and use the Inspector to update any sprite reference — changes propagate everywhere that asset is used.

4. IAP & Configuration

The project supports in-app purchases and various gameplay configuration constants. Replace the placeholder values with your own before publishing.

4.1 In-App Purchases (IAP)

IAP state is tracked via PlayerPrefs keys defined in GameConstant.cs. The project supports two purchase products out of the box:

PlayerPrefs Key	Product	Effect
`PLAYER_PREF_STARTER_BUNDLE`	Starter Bundle	Grants starter coin & booster pack
`PLAYER_PREF_PREMIUM_PASS`	Premium Pass	Unlocks premium rewards track

To integrate real IAP: import Unity IAP via Window → Package Manager → Unity Registry → In App Purchasing, define your Product IDs matching the keys above, and set the corresponding PlayerPref to "1" in the purchase success callback.

4.2 Booster Costs

In-game booster prices (paid in coins) are defined as constants in GameConstant.cs:

Booster	Constant	Default Cost (coins)
Bomb	`BOMB_COST`	300
Rainbow	`RAINBOW_COST`	500
Lightning	`LIGHTNING_COST`	600
Beam	`BEAM_COST`	400

4.3 Gameplay Economy Constants

Key gameplay numbers are all in GameConstant.cs and can be tuned without touching any other file:

MAX_LEVEL = 1115 — total number of levels. Increase when you add more.
MOVES_AMOUNT_COIN = 5 — extra moves purchased with coins.
PIGGY_BONUS_COIN = 50 — coins added to the piggy bank per qualifying action.
SPIN_COIN = 200 — coin cost to spin the Lucky Spin wheel.
COIN_RATIO = 5 — score-to-coin conversion ratio.

4.4 Notifications

Push notification settings are stored in ProjectSettings/NotificationsSettings.asset. Configure your notification channels and IDs there, or integrate a third-party push notification SDK (e.g. Firebase Cloud Messaging) following the SDK's Unity setup guide.

4.5 Privacy Policy & Terms of Service URLs

The placeholder URLs are in GameConstant.cs:

URL_POLICY — replace "google.com" with your Privacy Policy URL.
URL_TERM — replace "google.com" with your Terms of Service URL.