Modulo Squares

Contents

• Demo
  • Architecture
  • Gameplay walkthrough
• Status
• Repository Structure
• Product behavior
• Web application
• Local setup
• Build and validation
• CI/CD
• Documentation

Modulo Squares is a falling-number arcade puzzle for iOS built with Flutter, with Game Center for the leaderboard and achievements. Guide each number into one of ten divisor buckets before it lands, build combos, fill the progress grid, and chase a persistent local high score.

The repository contains the mobile app, release automation, and project documentation. It also still holds the legacy Firebase backend and React site from the 1.0.x app; they come out when that version is retired (docs/GAME_CENTER_MIGRATION.md). The public website is https://nelsongrey.com/games/modulo-squares.

Demo

Architecture

flowchart TB
    subgraph Client["packages/mobile (Flutter, iOS)"]
        Main["main.dart: service locator (GetIt), ads, purchases"]
        Game["GameScreen -> FallingModuloGameScreen\nfeatures/game/game_screen.dart"]
        Engine["FallingModuloGameEngine\nfeatures/game/models/falling_modulo_game_engine.dart"]
        GC["lib/gamecenter/\nconnection, leaderboard, achievement tracker"]
        Services["core/services:\nAdService, PurchaseService, CacheService, ConsentService"]
    end

    GameCenter["Game Center\nleaderboard + 15 achievements"]
    Site["nelsongrey.com/games/modulo-squares\nwebsite, privacy, support"]

    Main --> Game --> Engine
    Game --> GC --> GameCenter
    Main --> Services
    Game -. "legal links" .-> Site

There is no application backend. Identity, the leaderboard and achievements are Game Center; the best score is also stored on the device. See docs/System_Architecture.md.

Gameplay walkthrough

The tile-resolution arithmetic below is entirely client-side; this walks through the actual resolution logic in FallingModuloGameEngine.resolveCurrentTile (packages/mobile/lib/features/game/models/falling_modulo_game_engine.dart). Reporting a new best score is a separate step: the game screen passes it to the Game Center leaderboard when the player is connected.

1. A tile carrying value F spawns in the center lane of 10 lanes and begins falling after a 500 ms pause.
2. Ten buckets line the bottom, shuffled at game start: 1-9 (scoring) plus one dead bucket 0.
3. The player taps the Left or Right control to move the tile into a bucket B before it lands (180 ms move cooldown, down to 138 ms at combo 8+, from the 1.30x speed multiplier).
4. On landing, highestDivisorFor(F) computes H, the largest bucket value 1-9 that divides F evenly.
5. Scoring, from resolveCurrentTile:
   • B == H and H != 1 → best possible catch: scoreDelta = 2 * (F * B), fill +2, combo +1, gold "★ BONUS!" burst.
   • H == 1 (F coprime to every other bucket) and B == 1 → flat bonus scoreDelta = F, fill +2, combo +1.
   • F % B == 0, B != H, and B > 1 → valid but not optimal: scoreDelta = F * B, fill +1, combo +1.
   • B == 1 and B != H (bucket 1 isn't the highest divisor) → valid catch but no reward: scoreDelta = 0, fill +1, combo +1.
   • B == 0 (dead bucket) → scoreDelta = -F, fill -1, combo resets to 0.
   • Otherwise (F % B != 0) → scoreDelta = -(F * B * remainder), fill drops by remainder, combo resets to 0.
6. Score is clamped at zero (max(0, state.score + scoreDelta)); the 100-cell progress grid fills toward a level-up, and combo streaks raise the horizontal move speed multiplier up to 1.30x at combo 8+.
7. At level-up the falling number range scales up and the drop interval shrinks toward its floor (dropIntervalForLevel, 0.96^(level-1) decay per GameDifficulty), and buckets reshuffle.

Buckets carry no pre-drop hint of which are valid or optimal — the player has to work out the divisibility live. See docs/Game_Mechanics.md for the full rule table and test/models/falling_modulo_game_engine_test.dart for executable examples of every branch above.

Status

• Mobile version: 1.1.0+1
• Platform: iOS only (Android shelved)
• Public website: https://nelsongrey.com/games/modulo-squares
• Active branch workflow: .github/workflows/ci-cd.yml
• Toolchain used by CI: Flutter 3.44.2, Dart >=3.7.0, Node.js 24
• Current gameplay entry point: GameScreen -> FallingModuloGameScreen
• App Store: version 1.1.0 has been live since November 6, 2026 (bundle id com.modulosquares.app.ios), with Game Center leaderboards and 15 achievements

See Current State, Documentation Index, and Go-Live Runbook.

This is the beginning of the README. Read the rest at the original. Read the full README ↗