Word Crush

A Flutter word puzzle game with Turkish word validation, grid-based gameplay, boosters, sound effects, and local leaderboards.

Overview

Word Crush is a cross-platform Flutter game. The app is displayed as Word Blast in the UI. Players connect adjacent letters on a square grid to form valid words, earn points, use boosters, and try to maximize their score before running out of moves.

The project is built with a layered Flutter structure using Provider for state management and SharedPreferences for local persistence.

Features

• Turkish dictionary-based word validation
• 8-direction adjacent letter selection
• Drag-based word selection on the game grid
• 6x6, 8x8, and 10x10 grid options
• 15, 20, and 25 move game modes
• Letter-based scoring system
• Combo scoring for valid sub-words
• Power-up tiles generated from longer words
• Booster market with persistent inventory
• Local leaderboard and game history
• Persistent username, score, gold, sound, and booster data
• Sound effects and looping background music
• Retro/neon styled Flutter UI

Gameplay

1. Enter a username on first launch.
2. Start a new game from the home screen.
3. Select a grid size.
4. Select the number of moves.
5. Connect adjacent letters horizontally, vertically, or diagonally.
6. Submit valid words with at least 3 letters.
7. Earn points, trigger power-ups, and continue until no moves remain.
8. The final score is saved to the local leaderboard.

Rules

• Words must be between 3 and 10 letters.
• A tile cannot be used more than once in the same word.
• Every selected tile must be adjacent to the previous tile.
• Invalid word attempts reduce the remaining move count.
• After a valid word, selected tiles are removed and the grid collapses.
• The board is repaired or regenerated when it becomes unplayable.
• The game ends when the remaining move count reaches zero.

Scoring

Scores are calculated from per-letter values. Common letters have lower values, while rarer letters award more points. When a submitted word contains smaller valid words, the game adds combo points.

Power-ups are created based on word length:

Word Length	Power-up	Effect
4 letters	Row clear	Affects the selected row
5 letters	Area clear	Affects nearby tiles
6 letters	Column clear	Affects the selected column
7+ letters	Mega area	Affects a larger area

Boosters

Booster	Description	Price
Fish	Removes multiple random letters	100
Wheel	Clears the selected tile's row and column	200
Lollipop	Removes one selected letter	75
Swap	Swaps two adjacent letters	125
Shuffle	Shuffles all letters on the grid	300
Party	Regenerates the entire grid	400

Tech Stack

• Flutter
• Dart
• Provider
• SharedPreferences
• Audioplayers
• Flutter Lints

Main dependencies:

provider: ^6.1.2
shared_preferences: ^2.5.3
audioplayers: ^6.1.0
animate_do: ^4.2.0
cupertino_icons: ^1.0.8

Project Structure

word_crush/
├── android/
├── assets/
│   ├── icons/boosters/
│   ├── sounds/
│   └── words/
├── ios/
├── lib/
│   ├── main.dart
│   ├── models/
│   ├── services/
│   ├── state/
│   ├── ui/
│   │   ├── screens/
│   │   └── widgets/
│   └── utils/
├── linux/
├── macos/
├── test/
├── web/
├── windows/
├── pubspec.yaml
└── README.md

Architecture

• lib/main.dart initializes services, registers providers, and starts the app.
• lib/models/ contains game levels, tiles, scores, boosters, power-ups, and validation result models.
• lib/services/ contains grid generation, word validation, score storage, sound playback, and booster inventory logic.
• lib/state/ contains GameState, the main game controller for score, moves, selected tiles, board updates, and game status.
• lib/ui/screens/ contains the home, game, grid selection, move selection, market, and leaderboard screens.
• lib/ui/widgets/ contains reusable UI components.
• lib/utils/ contains scoring, Turkish text normalization, and grid helper functions.

Getting Started

Prerequisites

• Flutter SDK
• Dart SDK
• Android Studio, Xcode, Visual Studio, or another platform-specific toolchain depending on your target device

Installation

Clone the repository:

git clone https://github.com/bedirhaneren/word_crush.git
cd word_crush

Install dependencies:

flutter pub get

Running the App

List available devices:

flutter devices

Run on the default device:

flutter run

Run on a specific target:

flutter run -d chrome
flutter run -d windows
flutter run -d android

Building

Build release artifacts:

flutter build apk --release
flutter build web --release
flutter build windows --release

Testing and Analysis

Run static analysis:

flutter analyze

Run tests:

flutter test

Note: test/widget_test.dart still appears to contain the default Flutter counter test. It should be updated to match the current word game flow and service behavior.

Assets and Local Data

Word lists:

• Main dictionary: assets/words/words.txt
• Additional word file: assets/words/words_tr.txt
• The main dictionary currently contains about 63,000 lines.

Visual assets:

• App logo: assets/logo.png
• Booster icons: assets/icons/boosters/

Audio assets:

• Success, error, combo, win, and lose effects
• Looping background music

Local storage keys:

• word_blast_username
• word_blast_scores
• word_blast_game_counter
• word_blast_gold
• word_blast_joker_inventory
• sound_enabled

Development Notes

• WordService loads and normalizes the word list for fast lookup.
• GridService generates weighted Turkish letter grids and repairs boards using dictionary-guided placement.
• Word counting runs with Flutter compute to avoid blocking the UI.
• GameState centralizes game rules, selection handling, scoring, power-ups, boosters, and game completion.
• Scores and inventory are stored locally, so the game does not require a backend.

Images