Games & Recreation API Reference

14 game engines, creative tools, and simulation services — all pure Dart with no external dependencies, fully testable, and designed for Flutter widget integration via reactive state.

Architecture Pattern Every game/recreation service follows the same pattern: pure business logic in lib/core/services/, UI state bridged through providers in lib/state/providers/, and views in lib/views/. Services are framework-agnostic — they manage grids, scores, and rules without any Flutter imports (except PixelArtService and SketchPadService which use dart:ui for color/offset types).

🎮 Classic Games

SnakeGameService

lib/core/services/snake_game_service.dart

Classic Snake on a 20×20 toroidal grid. The snake grows when it eats food, and the game ends on self-collision.

Key Types

Type	Description
`GridPoint(int x, int y)`	Immutable coordinate on the grid with value-equality
`SnakeDirection`	Enum: `up`, `down`, `left`, `right`

Properties

Property	Type	Description
`snake`	`List<GridPoint>`	Snake body segments (head-first)
`food`	`GridPoint`	Current food position
`direction`	`SnakeDirection`	Current movement direction
`score`	`int`	Current score
`isGameOver`	`bool`	Whether the game has ended

Methods

Method	Signature	Description
`newGame()`	`void`	Reset grid, place snake at center, spawn food
`tick()`	`void`	Advance one frame — move head, check food/collision, grow or trim tail
`changeDirection(dir)`	`void`	Set direction (ignores 180° reversals)

Usage

final game = SnakeGameService();
game.newGame();

// Game loop (driven by Timer or Ticker)
game.changeDirection(SnakeDirection.up);
game.tick();
if (game.isGameOver) print('Score: ${game.score}');
    

TetrisGameService

lib/core/services/tetris_game_service.dart

Full Tetris implementation with all 7 standard tetrominoes (I, O, T, S, Z, J, L), wall-kick rotation, line clearing with scoring, and next-piece preview.

Key Types

Type	Description
`TetrominoType`	Enum of the 7 standard piece types
`TetrisPoint(int x, int y)`	Board coordinate with value-equality and `+` operator
`Tetromino`	A piece with `type`, `rotation` (0–3), `position`, and computed `cells`

Properties

Property	Type	Description
`board`	`List<List<int>>`	20×10 grid (0 = empty, 1–7 = piece colors)
`current`	`Tetromino?`	Currently falling piece
`nextType`	`TetrominoType?`	Preview of the next piece
`score`	`int`	Total score (1/3/5/8 points for 1/2/3/4 lines)
`linesCleared`	`int`	Total lines cleared
`level`	`int`	Current level (increases every 10 lines)
`gameOver`	`bool`	True when a new piece can't spawn

Methods

Method	Signature	Description
`newGame()`	`void`	Clear board and start fresh
`tick()`	`void`	Drop piece one row; lock if landed, clear lines, spawn next
`moveLeft()` / `moveRight()`	`void`	Horizontal movement with collision check
`rotate()`	`void`	Clockwise rotation with wall-kick
`hardDrop()`	`void`	Instant drop to lowest valid position

Game2048Service

lib/core/services/game_2048_service.dart

The classic 2048 sliding-tile puzzle on a 4×4 grid. Tiles merge when equal values collide. Spawns a 2 (90%) or 4 (10%) after each move. Win condition: reach the 2048 tile.

Properties

Property	Type	Description
`grid`	`List<List<int>>`	4×4 tile grid (0 = empty)
`score`	`int`	Current score (sum of all merges)
`bestScore`	`int`	Session high score
`won`	`bool`	True when 2048 tile reached

Methods

Method	Signature	Description
`newGame()`	`void`	Reset grid, spawn 2 initial tiles
`swipe(SwipeDirection)`	`bool`	Slide + merge in direction; returns true if board changed
`acknowledgeWin()`	`void`	Allow continued play past 2048
`isGameOver`	`bool` (getter)	True when no valid moves remain

Merge Algorithm Each swipe decomposes into per-row left-merges via _mergeRow(): remove zeros, scan left-to-right for adjacent equal values, merge once (no chain-merging within a single swipe), then pad with zeros. The grid is transposed/reversed as needed to reduce all 4 directions to left-merge.

🧩 Puzzle & Strategy

SudokuService

lib/core/services/sudoku_service.dart

Generates valid 9×9 Sudoku puzzles at 4 difficulty levels by first solving a blank grid via randomized backtracking, then removing cells to reach the target "givens" count.

Difficulty Levels

Level	Givens
Easy	36
Medium	30
Hard	25
Expert	20

Properties

Property	Type	Description
`puzzle`	`List<List<int>>`	Original puzzle (0 = empty)
`solution`	`List<List<int>>`	Full solution for validation
`playerGrid`	`List<List<int>>`	Player's working grid
`given`	`List<List<bool>>`	Mask of non-editable cells

Methods

Method	Signature	Description
`generate(difficulty)`	`void`	Generate a new puzzle at the given difficulty
`setCell(row, col, value)`	`bool`	Set a cell (returns false if cell is a given)
`validate()`	`bool`	Check if current grid matches solution
`getHint()`	`(int, int, int)?`	Returns (row, col, value) for one empty cell
`hasConflict(row, col)`	`bool`	Check if a cell conflicts with row/col/box peers

MinesweeperService

lib/core/services/minesweeper_service.dart

Full Minesweeper with 3 preset difficulties, first-click safety (mines are placed after the first reveal to guarantee a safe start), flood-fill auto-reveal for zero-adjacent cells, and flag/chord support.

Difficulty Presets

Level	Grid	Mines
Beginner	9 × 9	10
Intermediate	16 × 16	40
Expert	16 × 30	99

Cell Model

class MinesweeperCell {
  bool hasMine;
  bool isRevealed;
  bool isFlagged;
  int adjacentMines;
}
    

Methods

Method	Signature	Description
`newGame(difficulty)`	`void`	Initialize grid for the selected difficulty
`reveal(row, col)`	`void`	Reveal a cell (flood-fills zeros); triggers mine placement on first click
`toggleFlag(row, col)`	`void`	Toggle flag marker on an unrevealed cell
`isWon`	`bool`	True when all non-mine cells are revealed
`isLost`	`bool`	True when a mine was revealed

TicTacToeService

lib/core/services/tic_tac_toe_service.dart

Tic Tac Toe with two modes: local two-player and vs. AI. The AI uses minimax search to play optimally (unbeatable on a 3×3 board).

Properties

Property	Type	Description
`board`	`List<String>`	9-element flat board (`''`, `'X'`, or `'O'`)
`currentPlayer`	`String`	`'X'` or `'O'`
`vsAi`	`bool`	Whether playing against AI
`gameOver`	`bool`	Whether the game has ended
`winner`	`String?`	`'X'`, `'O'`, or null (draw)
`isDraw`	`bool`	Game over with no winner

Methods

Method	Signature	Description
`makeMove(index)`	`bool`	Place current player's mark at index 0–8; triggers AI response if enabled
`setVsAi(bool)`	`void`	Toggle AI mode (resets the board)
`reset()`	`void`	Clear board and start fresh

MemoryGameService

lib/core/services/memory_game_service.dart

Emoji-based memory card matching game with 4 difficulty levels (6–15 pairs). Tracks moves, elapsed time, and calculates a star rating based on performance.

Difficulty Levels

Level	Pairs
Easy	6
Medium	8
Hard	10
Expert	15

Card Model

class MemoryCard {
  final int id;
  final String emoji;
  bool isFaceUp;
  bool isMatched;
}
    

Methods

Method	Signature	Description
`newGame(difficulty)`	`void`	Shuffle and deal cards for the selected difficulty
`flipCard(index)`	`FlipResult`	Flip a card; returns match/mismatch/waiting status
`isComplete`	`bool`	All pairs matched
`stats`	`GameStats`	Moves, time, star rating (1–3 stars)

🎨 Creative Tools

PixelArtCanvas

lib/core/services/pixel_art_service.dart

Grid-based pixel art editor with configurable canvas size (default 16×16), full undo/redo history, fill tool, and PNG export via dart:ui.

Constructor

PixelArtCanvas({int width = 16, int height = 16})

Methods

Method	Signature	Description
`setPixel(x, y, color)`	`void`	Set a single pixel (saves undo state)
`getPixel(x, y)`	`Color`	Read a pixel's color
`fill(x, y, color)`	`void`	Flood-fill from point with color
`clear()`	`void`	Reset all pixels to transparent
`undo()` / `redo()`	`void`	Navigate undo/redo stack
`toPng(pixelSize)`	`Future<Uint8List>`	Export canvas as PNG bytes at given pixel scale

SketchPadService

lib/core/services/sketch_pad_service.dart

Freehand drawing canvas that records strokes as sequences of Offset points with configurable color and stroke width. Full undo/redo support.

Stroke Model

class SketchStroke {
  final List<Offset> points;
  final Color color;
  final double width;
}
    

Methods

Method	Signature	Description
`startStroke(point, color, width)`	`void`	Begin a new stroke
`addPoint(point)`	`void`	Extend the current stroke
`endStroke()`	`void`	Finalize the current stroke
`undo()` / `redo()`	`void`	Navigate stroke history
`clear()`	`void`	Remove all strokes

🔬 Simulations & Visualizations

GameOfLifeService

lib/core/services/game_of_life_service.dart

Conway's Game of Life on a toroidal grid (edges wrap). Supports arbitrary grid sizes, preset patterns (glider, blinker, pulsar, Gosper glider gun), randomization, and single-step or continuous simulation.

Rules (B3/S23)

A dead cell with exactly 3 live neighbors becomes alive (birth)
A live cell with 2 or 3 live neighbors survives
All other live cells die (underpopulation or overpopulation)

Properties

Property	Type	Description
`grid`	`List<List<bool>>`	Current cell states (defensive copy)
`rows` / `cols`	`int`	Grid dimensions
`generation`	`int`	Steps elapsed since last reset
`liveCellCount`	`int`	Number of currently alive cells

Methods

Method	Signature	Description
`step()`	`bool`	Advance one generation; returns true if any cell changed
`toggleCell(row, col)`	`void`	Toggle a cell's state
`randomize({density})`	`void`	Fill grid randomly (default 30% alive)
`loadPreset(name)`	`void`	Load a named pattern (glider, pulsar, etc.)
`resize(rows, cols)`	`void`	Change grid dimensions (clears state)
`clear()`	`void`	Kill all cells, reset generation counter

Toroidal Topology Neighbor counting wraps around grid edges using modular arithmetic, so patterns like gliders can traverse the entire grid without hitting walls.

SortVisualizerService

lib/core/services/sort_visualizer_service.dart

Step-by-step visualization of 5 sorting algorithms. Generates an array of SortStep snapshots that record comparisons, swaps, and sorted regions — designed for animated playback.

Supported Algorithms

Algorithm	Time	Space
Bubble Sort	O(n²)	O(1)
Selection Sort	O(n²)	O(1)
Insertion Sort	O(n²)	O(1)
Merge Sort	O(n log n)	O(n)
Quick Sort	O(n log n)*	O(log n)

Step Model

class SortStep {
  final List<int> array;          // snapshot of array at this step
  final int? comparing1, comparing2; // indices being compared
  final Set<int> sorted;         // indices known to be in final position
  final String description;       // human-readable step explanation
}
    

Methods

Method	Signature	Description
`generate(algorithm, size)`	`List<SortStep>`	Generate all steps for the algorithm on a random array of given size
`generateFromArray(algorithm, array)`	`List<SortStep>`	Generate steps for a specific input array

🎲 Party & Fun

HangmanService

lib/core/services/hangman_service.dart

Classic Hangman word guessing game with a built-in word bank of 25+ words, each with a hint. 6 incorrect guesses allowed before game over.

Methods

Method	Signature	Description
`newGame()`	`void`	Pick a random word and reset state
`guessLetter(letter)`	`bool`	Guess a letter; returns true if it appears in the word
`displayWord`	`String`	Current word with unguessed letters as underscores
`hint`	`String`	Hint for the current word
`isWon` / `isLost`	`bool`	Win/loss state
`wrongGuesses`	`int`	Number of incorrect guesses (max 6)

SimonSaysService

lib/core/services/simon_says_service.dart

Memory game where the computer plays an ever-growing sequence of colored buttons that the player must reproduce. Each successful round adds one flash. 4 buttons (green, red, yellow, blue).

Methods

Method	Signature	Description
`startNewGame()`	`void`	Reset and begin with a 1-element sequence
`playerInput(buttonIndex)`	`InputResult`	Submit a button press; returns correct/wrong/round-complete
`sequence`	`List<int>`	Current computer sequence (for playback)
`round`	`int`	Current round number
`highScore`	`int`	Best score this session

RpsService

lib/core/services/rps_service.dart

Rock Paper Scissors with full history tracking, win/loss/draw stats, streak tracking, and a CPU opponent that plays randomly.

Types

Type	Values
`RpsMove`	`rock`, `paper`, `scissors`
`RpsOutcome`	`win`, `lose`, `draw`

Methods

Method	Signature	Description
`play(RpsMove)`	`RpsRound`	Play a round and get result (player move, CPU move, outcome)
`stats`	`RpsStats`	Cumulative stats: total rounds, wins, losses, draws, streaks, win rate
`history`	`List<RpsRound>`	Full round history (most recent first)
`reset()`	`void`	Clear all history and stats

SpinWheelService

lib/core/services/spin_wheel_service.dart

Customizable spin wheel / random picker with preset configurations, history tracking, and option management. Great for decision-making or party games.

Methods

Method	Signature	Description
`addOption(text)`	`void`	Add an option to the wheel
`removeOption(text)`	`void`	Remove an option
`loadPreset(preset)`	`void`	Load a preset wheel configuration
`spin()`	`SpinResult`	Spin and return a random result
`history`	`List<SpinResult>`	Previous spin results

ReactionTimeService

lib/core/services/reaction_time_service.dart

Reaction time testing with history (up to 100 results), average/best/worst stats, and session tracking. The UI handles the visual stimulus; this service manages scoring.

Methods

Method	Signature	Description
`addResult(result)`	`void`	Record a reaction time measurement
`averageMs`	`double?`	Average reaction time across all results
`bestMs`	`int?`	Fastest reaction time
`worstMs`	`int?`	Slowest reaction time
`clearHistory()`	`void`	Reset all recorded results

Testing All game services are covered by tests in test/. Because services are pure Dart with no Flutter widget dependencies, they can be tested with flutter test using standard expect() assertions — no widget pump or mock framework needed.

Last updated: April 2026 · Back to documentation home