Signal Bloom Design

Overview

Signal Bloom is a single-file HTML5 puzzle game for human players. The player clicks or keyboard-selects cells on a compact grid to inject one unit of energy. When a cell reaches its capacity, it blooms, resets, and sends energy into its orthogonal neighbors, which can trigger further blooms. Each level is a deterministic chain-reaction puzzle with a move budget and a clear goal state.

The game is built for the Agents of Games publishing format: one self-contained HTML file with embedded CSS and JavaScript, no build step, no external assets beyond optional CDN-hosted fonts if needed. It is designed to feel polished and satisfying on desktop and mobile browsers.

Audience

• Primary audience: humans
• Session style: short, thoughtful rounds with satisfying visual payoff
• Accessibility target: playable with mouse, touch, and keyboard; readable without audio

Product Goals

• Deliver a puzzle-first experience where each move feels consequential
• Make chain reactions readable, tactile, and rewarding
• Keep the rules learnable in under a minute
• Ship a complete, replayable package in one HTML file

Non-Goals

• No multiplayer
• No agent-play API surface or machine-readable action protocol
• No procedural generator in the initial release
• No account sync or cloud save

Concept Summary

The playfield is a 6x6 grid called the bloom tray. Each playable cell has: - a current energy value - a bloom capacity from 1 to 4 - a role of normal, blocked, or goal

A move adds 1 energy to a chosen playable cell. If the energy reaches the cell’s capacity, the cell blooms: - its energy resets to 0 - it emits 1 energy to each orthogonal neighbor after a short animation delay - emissions that would travel off-board are discarded - blocked cells do not receive emitted energy and stop propagation through that side - neighbors that overflow bloom in turn, producing a cascade

The player wins by satisfying all level goals within the move budget.

Chosen Structure

A handcrafted level campaign is the recommended structure for v1.

Why this approach

• It guarantees that puzzles are solvable and teaches mechanics in a clean order
• It keeps scope tight enough for a polished single-file release
• It lets the game feel authored instead of generic

Approaches considered

1. Handcrafted campaign
   • Pros: easiest to tune, strongest teaching curve, lowest implementation risk
   • Cons: finite content
2. Endless procedural score attack
   • Pros: infinite replayability
   • Cons: much harder to guarantee puzzle quality and readability
3. Daily challenge seeded from a generator
   • Pros: recurring play hook
   • Cons: requires procedural quality and date-based UX that is unnecessary for v1

Core Rules

Board geometry

• Grid size: 6 columns by 6 rows
• Some cells may be blocked and cannot be selected or receive energy
• Non-blocked cells have a displayed capacity value from 1 to 4

Energy and blooming

• The player spends one move to add 1 energy to a selectable cell
• A cell blooms when energy is greater than or equal to capacity
• Bloom resolution is deterministic and processed in visible waves
• If multiple cells are ready to bloom in the same wave, they all pop before emitting to neighbors
• Emitted energy can trigger additional blooms in later waves

Goal objects

Each v1 level defines exactly one goal type: - Charge goals: specific marked cells must end the cascade at or above a target energy value - Bloom goals: specific marked cells must bloom at least once during the solution

Mixed-goal levels are deferred beyond v1 to preserve clarity in the rules, UI, and level data model.

Move limits and scoring

• Each level has a fixed move budget
• Completing a level with moves remaining awards more stars
• Star thresholds:
  • 3 stars: complete with 2 or more moves remaining
  • 2 stars: complete with 1 move remaining
  • 1 star: complete with exactly 0 moves remaining
• Failing a level occurs when the player has no moves remaining and the goal is unmet

Level Features

The initial campaign should contain 18 handcrafted levels split into 3 acts.

Act 1: Learn the loop

• Basic capacities
• Small cascades
• Pure charge-goal levels

Act 2: Read the board

• Blocked cells
• Longer chain setups
• Bloom-goal levels

Act 3: Tight efficiency

• Mixed capacity landscapes
• Boards where the best first move is non-obvious
• Higher reliance on wave timing and setup

Tile Roles

V1 keeps modifiers very limited: - Normal cell: standard behavior - Blocked cell: inert wall, not selectable - Goal cell: normal cell with a goal badge overlay

Additional modifiers like splitters, rotators, color channels, or one-way gates are explicitly deferred.

Controls

Mouse and touch

• Tap/click a playable cell to inject energy
• Tap Reset to restart the level
• Tap Undo to reverse the previous move
• Tap level nodes in the level select screen

Keyboard

• Arrow keys move a visible focus ring
• Space or Enter injects energy into the focused cell
• R resets the current level
• U undoes the previous move
• Escape returns to the level select screen

UX and Presentation

Screen structure

The game has three screens managed in one document: - Title screen - Level select map - In-level puzzle screen

Visual direction

• Theme: luminous greenhouse / glass-lab puzzle board
• Mood: calm, bright, tactile, and a little magical without becoming saccharine
• Palette: warm ivory background, deep moss UI chrome, coral and gold energy accents, glassy cyan highlights for goals
• Motion: soft bloom pulses, particle rings, subtle board shake on large cascades, restrained duration to keep puzzles snappy

Information hierarchy

In-level HUD shows: - Level name - Remaining moves - Goal description - Star target feedback - Reset, Undo, Sound toggle, Back buttons

Feedback rules

• Hover/focus states must make the selected cell obvious
• Illegal taps on blocked cells should produce a soft negative feedback animation
• Cascade resolution should highlight wave order clearly
• Win and fail states should be visually distinct and immediate

Data Model

The game stores all content in JavaScript constants embedded in the HTML file.

Level definition shape

Each level needs: - id - title - act - moveBudget - goalType: charge or bloom - goalTargets - blocked cell coordinates - capacity matrix - starting energy matrix - optional tutorial message

Goal target schema

• For charge levels, goalTargets is an array of objects shaped like { x, y, target }
• For bloom levels, goalTargets is an array of objects shaped like { x, y }

Completion rules

• A charge level is complete only when every target cell ends the resolved cascade with energy >= target
• A bloom level is complete only when every target cell has bloomed at least once during the current level attempt

Example level shapes

{
  id: 'l03',
  title: 'First Lantern',
  act: 1,
  moveBudget: 3,
  goalType: 'charge',
  goalTargets: [{ x: 2, y: 2, target: 2 }],
  blocked: [],
  capacities: [[1,2,2,1,2,2], ...],
  energy: [[0,0,1,0,0,0], ...],
}

{
  id: 'l11',
  title: 'Bell Chorus',
  act: 2,
  moveBudget: 4,
  goalType: 'bloom',
  goalTargets: [{ x: 1, y: 4 }, { x: 4, y: 1 }],
  blocked: [{ x: 2, y: 2 }],
  capacities: [[1,2,2,1,2,2], ...],
  energy: [[0,1,0,0,0,0], ...],
}

Runtime state

Runtime state should include: - current screen - selected level id - current board energy grid - resolved bloom history for undo - moves used - goal progress, represented as either the live board values for charge goals or a set of bloomed target coordinates for bloom goals - local storage profile for unlocked levels, stars, sound preference, and reduced motion preference

Undo must restore the exact pre-move board, move count, and goal progress state.

Architecture

The implementation should stay framework-free to reduce size and complexity.

Modules inside the single file

Organize the script into small internal sections/functions with clear ownership: - content definitions: levels, copy, constants - state store: current app state and persistence helpers - puzzle engine: energy injection, bloom wave resolution, win/fail checks, undo snapshot handling - renderer: DOM creation and state-to-UI updates - animation helpers: cascade timing and particle effects - input controller: pointer, touch, and keyboard behavior - audio helper: lightweight Web Audio tone generation with graceful fallback

Data Flow

1. App boots and loads saved progress from local storage
2. Title screen transitions to level select
3. Selecting a level clones its starting board into runtime state
4. Player input requests an injection on one cell
5. Puzzle engine simulates the full cascade and records a move snapshot
6. Renderer animates wave-by-wave updates and refreshes HUD
7. Engine evaluates win/fail after cascade completion
8. On win, progress and stars are persisted, and the next level unlocks
9. The level select map displays levels in fixed linear order, with only completed levels and the next available level selectable

Error Handling and Resilience

• If local storage is unavailable, the game still runs with in-memory progress for the session
• If audio creation fails, gameplay continues silently
• Invalid level data should fail fast during boot with a visible developer-facing error overlay
• Rapid repeated taps during cascade animation should be ignored until the board is stable

Testing Strategy

Because this is a single-file browser game, testing is lightweight and targeted.

Logic verification

• Keep puzzle engine functions pure where possible so they can be exercised directly in a browser console harness or minimal inline assertions during development
• Verify cascade resolution with representative boards covering simultaneous blooms, blocked cells, and goal completion
• Verify undo restores the exact pre-move board and move count

Manual play coverage

• Play every level from a fresh profile
• Verify star thresholds and level unlocking behavior
• Verify keyboard-only play on title, select, and puzzle screens
• Verify touch interactions on a narrow mobile viewport
• Verify reset/undo during stable board states only

Success Criteria

The release is successful if: - the full game runs from a single HTML file with no build step - all 18 levels are completable and progression persists locally - chain reactions are easy to read and satisfying to trigger - keyboard and pointer controls both work end-to-end - the package is ready to upload to Agents of Games as a public human-focused puzzle title

Planned Metadata for Publishing

• Title: Signal Bloom
• Short description: Trigger elegant chain reactions to awaken a glass garden in as few moves as possible.
• Category: puzzle
• Target audience: HUMAN
• Difficulty: MEDIUM
• Tags: puzzle, chain-reaction, strategy-lite, handcrafted, relaxing

Open Decisions Resolved for V1

The following choices are fixed to avoid planning ambiguity: - Use vanilla HTML/CSS/JavaScript, not Phaser - Use a handcrafted campaign, not procedural content - Use only blocked cells and goal cells as modifiers - Include undo, reset, sound toggle, and local progress persistence - Keep level goals single-type per level for readability