System Requirements Document (SRD)

Project Name: bronze-candy

1. Introduction

The bronze-candy project is an advanced Match-3 puzzle game inspired by Candy Crush, designed to deliver an engaging and visually appealing experience for players. This document outlines the system requirements for the development of the game, ensuring it meets the expectations of users like Pavan Lodhi from India. The game will feature drag-and-swap functionality, responsive design, and advanced features such as leaderboards and game progress saving.

2. System Overview

The bronze-candy game will be a browser-based Match-3 puzzle game that supports both desktop and mobile platforms. The core gameplay revolves around matching candies on an 8x8 grid by dragging and swapping them. The game will include smooth animations, attractive visuals, and sound effects to enhance the user experience. Advanced features such as a timer mode, leaderboard, and game progress saving will be implemented to increase replayability and engagement.

Key highlights of the system:

• Cross-platform compatibility (desktop and mobile).
• Intuitive drag-and-swap functionality.
• Dynamic game logic with special candies and combos.
• Responsive and visually appealing UI.
• Advanced features for competitive and casual players.

3. Functional Requirements

Core Features

• As a User, I should be able to play on an 8x8 grid board.
• As a User, I should see at least 5 different candy types (image-based, not just color).
• As a User, I should be able to drag and swap candies using touch (mobile) or mouse (desktop).
• As a User, I should only be allowed valid moves (no random swaps).

Game Logic

• As a User, I should see candies removed when 3 or more match.
• As a User, I should see special candies created for 4-match (line blast) and 5-match (bomb candy).
• As a User, I should experience chain reactions (combo system) for extra scores.
• As a User, I should see new candies fall from the top (gravity system).
• As a User, I should see the board auto-refill after matches.

UI/Design

• As a User, I should experience a Candy Crush-like attractive UI.
• As a User, I should see smooth animations for swap, blast, and falling candies.
• As a User, I should hear background music and sound effects during gameplay.
• As a User, I should be able to play on a responsive design optimized for mobile and desktop.

Game System

• As a User, I should see a score system tracking my progress.
• As a User, I should play levels with target scores.
• As a User, I should have limited moves per level (e.g., 20 moves).
• As a User, I should see a Win/Lose screen at the end of a level.
• As a User, I should be able to restart or proceed to the next level using buttons.

Advanced Features

• As a User, I should be able to play in a timer mode option.
• As a User, I should see a leaderboard stored locally.
• As a User, I should have my game progress saved (local storage or Firebase).
• As a User, I should see a loading screen before the game starts.

4. User Personas

1. Casual Player

• Wants to enjoy a visually appealing and relaxing game.
• Prefers simple gameplay mechanics with intuitive controls.

2. Competitive Player

• Focuses on achieving high scores and climbing the leaderboard.
• Enjoys advanced features like timer mode and combos.

3. Mobile Gamer

• Primarily plays on mobile devices.
• Prefers touch-based controls and responsive design.

4. Desktop Gamer

• Prefers playing on larger screens using a mouse.
• Expects smooth animations and keyboard/mouse compatibility.

5. Visuals Colors and Theme

Color Palette

The bronze-candy project will feature a vibrant and playful color palette to evoke excitement and fun:

• Background: #FDF6E3 (Soft Cream)
• Surface: #FFD700 (Golden Yellow)
• Text: #4B0082 (Deep Indigo)
• Accent: #FF4500 (Bright Orange-Red)
• Muted Tones: #B0C4DE (Light Steel Blue)

6. Signature Design Concept

Floating Candy Universe

The homepage will feature an interactive floating candy universe. Players will see a 3D candy world where candies float and rotate in space. Each candy will represent a feature or section of the game.

Key Features:

• Interactive Animation: Candies will gently float and rotate, responding to mouse hover or touch with subtle bouncing effects.
• Dynamic Background: The background will shift colors dynamically, transitioning between the color palette based on the time of day.
• Micro-Interactions: Clicking on a candy will zoom into its section, accompanied by a candy explosion animation.
• Sound Effects: A soft "pop" sound will play when interacting with candies.

This design will create a memorable first impression, immersing players in the candy-themed universe before they even start playing.

7. Non-Functional Requirements

• The game must load within 3 seconds on standard broadband connections.
• The UI must remain responsive across devices with screen sizes ranging from 320px to 1920px.
• The game must handle up to 10,000 leaderboard entries without performance degradation.
• The animations must run at a minimum of 60 FPS for smooth gameplay.

8. Tech Stack

Frontend

• React for Web
• React Native for mobile app

Backend

• Python
• FastAPI

Database

• MySQL (preferred) or MariaDB for structured data.
• MongoDB for leaderboard and game progress storage.

AI Models

• GPT 5.4 for user-friendly responses.
• Google Nano Banana for image generation (candy assets).

AI Tools

• Litellm for LLM Routing.
• Langchain for advanced logic.

Local Orchestration

• Docker
• docker-compose

Server-Side Orchestration

• Kubernetes

9. Assumptions and Constraints

Assumptions

• Players will have access to devices with modern browsers supporting HTML5.
• Internet connectivity is required for advanced features like Firebase integration.

Constraints

• The game must be optimized for low-end devices without compromising core functionality.
• All assets (images, sounds) must be lightweight to ensure fast loading times.

10. Glossary

• Match-3 Puzzle: A game genre where players match three or more items to clear them.
• Gravity System: A mechanic where new items fall into empty spaces after matches.
• Combo System: A scoring mechanism rewarding chain reactions.
• Leaderboard: A ranking system displaying top scores.
• Firebase: A cloud-based platform for storing game progress.