MarkScoreOS 🏆

A Modern, Real-Time Competition Scoring System

Professional scoring application for quizzes, competitions, and live events

Features • Quick Start • Documentation • Contributing

📖 Overview

MarkScoreOS is a feature-rich, real-time scoring application designed for quizzes, competitions, game shows, and live events. Built with modern web technologies, it provides a stunning visual experience with professional animations, customizable themes, and intelligent responsive scaling.

Why MarkScoreOS?

🎯 Real-time Updates - WebSocket-powered live score synchronization
🎨 Beautiful Themes - 6 professionally designed themes
📱 Fully Responsive - Adapts to any screen size automatically
🎬 Rich Animations - Customizable animation system with multiple levels
🔊 Sound Effects - Configurable audio feedback for events
🎮 Multiple Game Modes - Classic, elimination, rounds, and more
⚡ Zero Configuration - Works out of the box
🌐 Multi-Display - Admin panel + public display view

✨ Features

🎮 Game Modes

Classic Points - Traditional point-based scoring
Elimination - Last team standing wins
Rounds - Multi-round competitions with round winners
Target Score - First to reach target wins
Best of N - Best of 3, 5, 7, etc.
Custom Rules - Define your own scoring logic

🎨 6 Beautiful Themes

🌃 Dark Neon - Purple and cyan vibes
🌊 Ocean Blue - Deep blue gradients
🌅 Sunset Orange - Warm sunset colors
🌲 Forest Green - Natural emerald tones
🏭 Industrial Dark - Professional dark theme
☀️ Professional Light - Clean light theme

🎬 Animation System

Animation Levels: Full, Minimal, or None

Customizable effects:

🎊 Confetti & Fireworks
✨ Particle Bursts
💫 Score Pop Animations
🌟 Glow Effects
🔄 Slide Transitions
📊 Smooth Score Count-ups

🔊 Sound Effects

Configurable audio feedback
Volume control
Enable/disable toggle
Custom sound upload support
Events: Score updates, new rounds, winner, buzzer, elimination

📊 Display Features

Intelligent Scaling - Auto-adjusts to screen resolution
Manual Scale Control - Fine-tune card sizes (50%-200%)
Team Cards - Large, readable cards with team info
Live Leaderboard - Real-time ranking display
Buzzer System - Visual buzzer press indicators
Round Indicators - Current round and progress display
Winner Celebrations - Animated winner announcements

🎛️ Admin Panel

Team Management - Add, edit, delete teams with images
Score Control - Increment/decrement scores with custom values
Game Control - Start, pause, reset, end games
Round Management - Start/end rounds, track progress
Settings - Themes, animations, sounds, display scale
Real-time Preview - See changes instantly on display

🚀 Quick Start

Prerequisites

Node.js 16.0.0 or higher
npm or yarn

Installation

Clone the repository

git clone https://github.com/yourusername/MarkScoreOS.git
cd MarkScoreOS

Install backend dependencies

cd backend
npm install

Install frontend dependencies

cd ../frontend
npm install

Start the backend server

cd backend
npm start

Start the frontend development server

cd frontend
npm run dev

Access the application

Display View: http://localhost:5173
Admin Panel: http://localhost:5173/admin

Production Build

# Build frontend
cd frontend
npm run build

# Start backend (serves built frontend)
cd ../backend
npm start

📚 Documentation

Project Structure

MarkScoreOS/
├── backend/                 # Node.js + Express backend
│   ├── data/               # Data storage (JSON files)
│   ├── routes/             # API routes
│   ├── uploads/            # Uploaded files (team images, sounds)
│   └── server.js           # Main server file
├── frontend/               # React + Vite frontend
│   ├── public/             # Static assets
│   ├── src/
│   │   ├── components/     # React components
│   │   ├── hooks/          # Custom React hooks
│   │   ├── pages/          # Page components
│   │   ├── services/       # API services
│   │   ├── styles/         # CSS and themes
│   │   └── utils/          # Utility functions
│   └── vite.config.js      # Vite configuration
├── CONTRIBUTING.md         # Contribution guidelines
├── SOUNDS.md              # Sound system documentation
├── LICENSE                # Apache 2.0 License
└── README.md              # This file

Key Technologies

Backend:

Node.js
Express.js
Socket.IO (WebSocket)
Multer (File uploads)

Frontend:

React 18
Vite
Framer Motion (Animations)
Lucide React (Icons)
Canvas Confetti

Configuration

All configuration is stored in backend/data/config.json:

{
  "theme": "dark-neon",
  "displayTitle": "MarkScoreOS",
  "displayScale": "auto",
  "soundEnabled": true,
  "soundVolume": 0.7,
  "animations": {
    "enabled": true,
    "level": "full"
  }
}

API Endpoints

Game State:

GET /api/game-state - Get current game state
POST /api/game/start - Start game
POST /api/game/end - End game
POST /api/game/reset - Reset game

Teams:

GET /api/teams - Get all teams
POST /api/teams - Add team
PUT /api/teams/:id - Update team
DELETE /api/teams/:id - Delete team

Scores:

POST /api/scores/update - Update team score
POST /api/scores/increment - Increment score
POST /api/scores/decrement - Decrement score

Configuration:

GET /api/config - Get configuration
PUT /api/config - Update configuration

WebSocket Events:

game-started - Game started
game-ended - Game ended
score-updated - Score changed
team-added - Team added
team-updated - Team updated
team-deleted - Team deleted
round-started - Round started
round-ended - Round ended
winner-announced - Winner declared
buzzer-pressed - Buzzer activated

🎯 Usage Guide

Setting Up a Competition

Open Admin Panel (http://localhost:5173/admin)
Add Teams:
- Go to "Teams" tab
- Click "Add Team"
- Enter team name, choose color
- Optionally upload team image
Configure Game:
- Go to "Game Control" tab
- Select game mode
- Set rounds/target score if applicable
Customize Appearance:
- Go to "Settings" tab
- Choose theme
- Adjust display scale
- Configure animations and sounds
Start Game:
- Click "Start Game"
- Display view updates automatically

During Competition

Admin Panel:

Update scores with +/− buttons
Use custom score input for specific values
Start/end rounds as needed
Press buzzer for teams
Monitor leaderboard

Display View:

Shows live scores and rankings
Displays animations for score changes
Shows winner celebrations
Indicates buzzer presses
Updates in real-time

Display Scale Control

Auto Mode (Recommended):

Automatically adjusts to screen size
Prevents scrolling
Optimal for any resolution

Manual Mode:

Use +/− buttons in Settings
Range: 50% - 200%
Presets: Small (75%), Normal (100%), Large (125%)

🎨 Customization

Adding Custom Themes

Edit frontend/src/styles/themes.css:

.theme-custom-name {
    --color-primary: #YOUR_COLOR;
    --color-secondary: #YOUR_COLOR;
    --color-bg: #YOUR_COLOR;
    /* ... more variables */
}

Update frontend/src/pages/Admin.jsx to add theme to selector.

Custom Sound Effects

Place audio files in frontend/public/sounds/
Supported formats: MP3, WAV, OGG
Name files: score-update.mp3, new-round.mp3, etc.
Or use the built-in sound generator at /sound-generator.html

Custom Animations

Modify animation settings in Admin Panel → Settings → Animations, or edit frontend/src/styles/animations.css.

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Development Setup

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Code Style

Use ESLint for JavaScript
Follow React best practices
Write meaningful commit messages
Add comments for complex logic

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

🙏 Acknowledgments

Framer Motion - Animation library
Socket.IO - Real-time communication
Lucide - Beautiful icons
Canvas Confetti - Celebration effects
Vite - Lightning-fast build tool

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
backend		backend
frontend		frontend
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SOUNDS.md		SOUNDS.md

License

Mythindia/MarkScoreOS

Folders and files

Latest commit

History

Repository files navigation

MarkScoreOS 🏆

📖 Overview

Why MarkScoreOS?

✨ Features

🎮 Game Modes

🎨 6 Beautiful Themes

🎬 Animation System

🔊 Sound Effects

📊 Display Features

🎛️ Admin Panel

🚀 Quick Start

Prerequisites

Installation

Production Build

📚 Documentation

Project Structure

Key Technologies

Configuration

API Endpoints

🎯 Usage Guide

Setting Up a Competition

During Competition

Display Scale Control

🎨 Customization

Adding Custom Themes

Custom Sound Effects

Custom Animations

🤝 Contributing

Development Setup

Code Style

📄 License

🙏 Acknowledgments

📞 Support

🗺️ Roadmap

📊 Screenshots

Display View

Admin Panel

Themes

About

Resources

License

Code of conduct

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages