Bubble Spire
Developer Guide

Start here: Bubble Spire

Bubble Spire is a complete editable Unity game template. Drag horizontally to rotate the tower, then tap a tower position to shoot. Connected groups of three or more same-colour marbles pop; marbles detached from the top fall. Complete colour quotas before the marble budget runs out.

Included: 25 curated levels, seeded continuation, visual level editor and validation, four guided helpers and portrait/landscape scenes. Saving is local. No multiplayer server, purchases, HLK, cloud accounts or remote LiveOps backend is included. Keep the required private game Kit. Szekipapa77 Ads is publisher-owned integration code; provider SDK binaries are excluded. Import only one game Kit per project because they share class names.

Installation and first play

Use Unity 6000.0.62f1, URP 17.0.4 and Unity UI 2.0.0. Retain the supplied official manifest and ProjectSettings. Install Android SDK/NDK/OpenJDK and WebGL support through matching Unity Hub modules.

1. Extract the standalone project to a short writable path and open it with the matching editor. Let package import finish.
2. For native package import, create a matching URP project, choose Assets > Import Package > Custom Package and import every game, Kit, Ads and WebGL template entry.
3. Run Szekipapa77 > Bubble Spire > Setup. This configures rendering and player settings; inspect changes when combining with an existing project.
4. Set Active Input Handling to Input Manager (Old), or Both if your project also has the Input System. New Input System only is insufficient.
5. Open Assets/Games/BubbleTower/Scenes/BubbleTower_Mobile.unity, press Play, dismiss the level card and follow the first-level guidance.
6. Stop Play mode before data editing. Retain .meta files/GUIDs. No separate TextMesh Pro import is needed by the classic Unity UI Text path.

Project map and actual scripts

All paths here are under Assets/Games/BubbleTower. Scripts owns gameplay; Editor owns visual tools; Kit supplies UI, audio, saving and platform code; Resources contains data/art/audio; Settings contains URP; Scenes contains mobile and WebGL entry points. The UI is created in code at runtime, not authored as a persistent Canvas prefab.

• Scripts/BtData.cs
• Scripts/BtGen.cs
• Scripts/BtLevels.cs
• Scripts/BtLogic.cs
• Scripts/BtMeshes.cs
• Scripts/BtSfx.cs
• Scripts/BubbleTowerGame.cs
• Scripts/BubbleTowerGame.Hud.cs
• Scripts/BubbleTowerGame.View.cs

Read BubbleTowerGame.cs for input/flow, BubbleTowerGame.Hud.cs for menus/popups, BubbleTowerGame.View.cs for the board/view, BtData.cs for the model and BtLevels.cs for level loading. Advertising settings are outside the game at Assets/Szekipapa77Ads.

Gameplay, input and progression

Drag horizontally to rotate the tower, then tap a tower position to shoot. Connected groups of three or more same-colour marbles pop; marbles detached from the top fall. Complete colour quotas before the marble budget runs out.

The curated bank contains 25 authored levels followed by generated continuation. The mobile scene requests portrait, while the WebGL-named scene requests landscape. Supplied build menu targets currently choose the portrait scene for both platforms; choose the landscape scene explicitly in a Build Profile if desired. Test layouts and controls after a near-startup scene replacement as well as after a finished round.

Tutorials and all four helpers

The first level includes guided controls; helper unlocks introduce each helper and its first use. Restart with fresh local progress to test first-launch guidance. Open in-game help to review controls.

A guided first use can be free and is not the same as spending a normal saved charge. Exhausted charges may request a rewarded placement. Confirm success/cancel/failure callbacks and grant rewards exactly once. Test each helper with valid preconditions: armed shots need a subsequent shot, Undo needs an unmatched pick and Bucket needs occupied tray slots.

Visual editor: your first edited level

Open Szekipapa77 > Bubble Spire > Level Editor. Exact implementation: Editor/BubbleTowerLevelEditor.cs.

Edit Name, Pattern tag, First-time hint and Marbles (budget). Around (columns) supports 12–28 and Height (rows) supports 6–40. Paint the unwrapped tower using Marble, Frozen, Rock, Oyster or Erase. Select colours from the palette and set colour-goal quantities to achievable values. Pattern fill uses colours, break-up and seed.

1. Back up levels.json and duplicate a simple early level.
2. Make one small change and use a distinctive visible name/note where supported.
3. Validate using the editor and fix every reported issue.
4. Save explicitly, stop and restart Play mode and open the edited index.
5. Check both supplied scenes and rebuild demos after data changes.

Generation, insertion and replacement

Count, Start at level #, Seed, Start/End difficulty and Breather every (0–8). Replace that range (else insert) removes the existing range before insertion; unchecked inserts and shifts later records. Start 26 appends to the original bank. Bot validation is part of generation.

Worked extension: keep a backup, generate five candidates after the original 25, use a moderate difficulty curve, validate every candidate, then Save. Reload JSON to confirm the count changed. Deliberately choose replacement only when you intend to overwrite those records. Runtime generated continuation does not write new project JSON assets. Solver/bot validation does not replace manual play testing.

Actual level schema

Canonical file: Assets/Games/BubbleTower/Resources/bubbletower/Levels/levels.json. Root levels array order defines visible level numbering; preserve version/type fields and numeric indices. The following is the actual first record, not a hypothetical schema:

{
  "name": "First Light",
  "pattern": "rings",
  "cols": 16,
  "rows": 10,
  "cells": [
    0,
    3,
    3,
    5,
    5,
    5,
    5,
    0,
    0,
    0,
    0,
    5,
    5,
    5,
    5,
    0,
    0,
    0,
    3,
    0,
    0,
    0,
    0,
    0,
    0,
    0,
    3,
    0,
    0,
    0,
    0,
    0,
    0,
    0,
    0,
    5,
    0,
    0,
    0,
    0,
    0,
    0,
    5,
    0,
    0,
    0,
    0,
    0,
    3,
    0,
    5,
    0,
    0,
    0,
    0,
    0,
    3,
    5,
    0,
    0,
    0,
    0,
    0,
    0,
    3,
    3,
    3,
    3,
    0,
    0,
    0,
    3,
    3,
    3,
    3,
    3,
    0,
    0,
    3,
    3,
    3,
    3,
    3,
    5,
    3,
    0,
    3,
    3,
    3,
    3,
    3,
    3,
    3,
    5,
    0,
    3,
    3,
    3,
    3,
    0,
    3,
    3,
    3,
    3,
    3,
    3,
    3,
    3,
    3,
    5,
    3,
    5,
    3,
    5,
    3,
    5,
    3,
    0,
    3,
    5,
    5,
    5,
    3,
    0,
    5,
    5,
    5,
    3,
    5,
    5,
    5,
    5,
    5,
    5,
    5,
    5,
    5,
    5,
    5,
    0,
    5,
    5,
    5,
    3,
    5,
    5,
    5,
    5,
    5,
    5,
    5,
    5,
    5,
    5,
    3,
    0,
    5,
    5,
    5,
    0
  ],
  "goalColor": [
    0
  ],
  "goalCount": [
    25
  ],
  "balls": 30,
  "difficulty": 0.05,
  "breather": false,
  "tut": 1,
  "hint": "",
  "seed": 4237
}

Use the visual editor to create structured coordinates, arrays and indices. Keep JSON valid and preserve booleans/numbers. Validate through BubbleTowerLevelEditor.cs before playing. Do not rename resource IDs or save keys during a display-text change.

Worked reskin: interface colours

Open Scripts/BubbleTowerGame.Hud.cs, find Brass with current hex #F2B544. Stop Play mode and back up the file. Change only that value to #42C9B0, keep the symbol/type, allow compilation and restart the scene. Review HUD, buttons, helper captions, result/settings popups and landscape layout. For Guess Five, check Night and Day and maintain clear clue contrast. Editor preview palettes can be separate; change them deliberately if matching is needed.

Exact runtime palette/material assignments follow. These show which file and assignment owns a colour; editing an editor-only colour does not reskin the runtime. Rebuild after accepting the change.

Worked reskin: visible text

Open Scripts/BubbleTowerGame.Hud.cs, find the displayed literal "marbles" and replace it with "shots". In HzUI.Label/Button, the first string can be the hierarchy object name; change the displayed text argument. Keep object identifiers, GameId, save/resource keys and asset filenames stable.

Preserve interpolation, numeric ToString formatting, line breaks and ON/OFF refresh logic. Update initial construction and later refresh assignments. Helper name/help sources are BoostName in BubbleTowerGame.cs and BoostDesc in BubbleTowerGame.cs. Level names and hints are separate JSON content. Visible title appears in the game Title property, HzGameInfo and sometimes separate screen lettering/art; review all branding deliberately.

There is no automatic translation of hard-coded game strings. A translation table must be called by each assignment. Word dictionaries/answer banks are gameplay data and do not translate Guess Five menus. Test title, tutorial, helper unlocks, HUD, settings/result popups and refreshed labels in both orientations.

Artwork, fonts and audio

Game assets live in Resources/bubbletower. Replace images through Unity while retaining resource keys, .meta GUIDs, Sprite/UI importer settings, alpha, pivots and slicing. Procedural fallbacks live in the view/art sources and may need their own changes; replacing a PNG does not automatically alter fallback graphics.

The private Kit supplies fonts and UI helpers. Retain included font licence notices and verify glyph coverage for new languages. Music resource: harbor_loop.ogg. Preserve load keys when replacing clips, review compression/loop boundaries, and test Sound and Music toggles separately. Inspect the Sfx/HzAudio code for current sound bindings.

Saving and resets

HzSave wraps PlayerPrefs, coalesces writes and flushes on focus loss/quit. WebGL uses browser IndexedDB tied to the hosting origin. Clearing site data or using a new origin starts a new save; this is not cloud synchronization. GameId-prefixed keys and some JSON progress hold levels, stars, helper counts, tutorial flags, audio options and statistics where implemented.

Test fresh launch, a completed level, helper consumption, audio toggles, focus loss, quit and relaunch. Use a separate development profile for resets. Preserve existing save keys for a visual reskin; changing them discards continuity. Inspect calls to HzSave in the listed scripts before adding a custom migration.

Advertising setup and scope

Settings asset: Assets/Szekipapa77Ads/Resources/AdsSettings.asset. Inspect backend, useGoogleTestIds and missingSdkFallback through the publisher Ads editor. This buyer contains integration/adapter code, not external provider SDK binaries. Missing-provider fallback and WebGL ads are simulated, not live commercial impressions.

For native real ads, obtain the supported provider from its official source in your working project, configure your own app/placement IDs and test with test IDs. Verify banner/interstitial/rewarded success, cancel and failure. Before production, supply your own IDs and disable simulated missing-SDK fallback. The build tools reject unsafe production fallback settings. No purchases or remote backend is supplied.

Android release

Install matching Android support in Unity Hub. Select Android, use the mobile scene, run Setup and review application ID com.szekipapa77.bubbletower, version, orientation and signing. Build Android writes Builds/Android/bubbletower.apk. Configure your own keystore and distribution settings; a demo APK is not a signed production release.

A provider-free build simulates ads. A supplied test-provider demo is not evidence of production account configuration. Use a Build Profile for your distribution format. On real hardware test touch, safe areas, audio focus, restart and ad callbacks. Keep signing passwords/keystores/private service files outside buyer archives. Successful compilation is not a physical-device play test.

WebGL release and hosting

Install WebGL support, select the WebGL target and run Setup and Build WebGL. Output: Builds/WebGL/bubbletower/. Serve index.html and every Build/StreamingAssets payload over HTTPS, not file://. Match compression, MIME and Content-Encoding to the host. The shell template controls the outer page; scene selection controls game orientation.

The publisher demo uses HyperCodeStore. Upload actual loader/framework/data/WASM files, not just a link; include the TemplateData shell required by the host. Test in a fresh anonymous session: loading, real pointer/keyboard input, audio after interaction, save/reload and mobile sizing. Rebuild and re-upload every changed game artifact.

Troubleshooting

Compilation errors: restore matching packages and import the entire private Kit/Ads layer; keep only one game Kit. Pink or invisible objects: run Setup and inspect Graphics and every Quality URP assignment. No input: check classic input handling, canvas focus and blocking modal. Missing resources: restore exact keys/importers/GUIDs.

Edited level absent: stop Play, Save, reload the canonical JSON and check saved progress/play overrides. No real ads: provider SDK is intentionally absent; inspect installed adapter and fallback. Text reverts: change both build and refresh assignments from the reference table. Scene reload exception: retain owner-lifetime and generation checks on delayed callbacks; do not remove those guards.

Support and release checklist

Support: szekipapa77@gmail.com. Include game title, exact Unity version, platform, first Console error and reproduction steps; never send credentials.

1. Pass a clean import and play both scenes.
2. Play tutorial, normal win/failure and every helper activation/effect.
3. Check reskin strings, settings, save/reload and both layouts.
4. Rebuild Android/WebGL after code or data changes and verify final output bytes.
5. Verify public APK, browser demo and full documentation links before publishing.
6. Keep licences and exclude private tooling/capture/workflow material from customers.