TKU Sparring System

A modern, user-friendly web application for managing Taekwondo sparring matches of UIT Taekwondo Tournaments.

Installation Guide

Option 1: Direct access (Recommended)

Simply visit TKU Sparring App in your web browser to start using the application immediately.

Option 2: Setup the project locally

Prerequisites:

• Node.js (Latest LTS version recommended)
• bun
• MongoDB Atlas
• Git

Setup Steps:

1. Clone the repository:

   git clone https://github.com/chef0111/tku-sparring-app.git
   cd tku-sparring-app

2. Install dependencies:

   bun install

3. Configure environment variables:

   • Copy .env.example to .env.local:

     cp .env.example .env.local

   • Update the environment variables:

     DATABASE_URL=<your-mongodb-connection-string>
     BETTER_AUTH_URL=http://localhost:3000
     BETTER_AUTH_SECRET=<generate-a-random-secret>

4. Set up the database:

   npx prisma generate
   npx prisma db push

5. Start the development server:

   bun run dev

   The application should now be available at http://localhost:3000

6. Build for production

   bun run start

Features

Match Configuration

• Customizable player names and avatars
• Adjustable round duration (10-300 seconds)
• Configurable break time between rounds (10-120 seconds)
• Customizable maximum health points (50-200)
• Support for up to 3 rounds per match

Scoring System

• 5-point scoring system:
  • 5 points: Critical head hit (25 health points)
  • 4 points: Critical trunk hit (20 health points)
  • 3 points: Head hit (15 health points)
  • 2 points: Trunk hit (10 health points)
  • 1 point: Punch (5 health points)
• Automatic health bar updates
• Visual feedback for critical hits
• Hit counter for each player

Penalty System

• Gam-jeom (penalty) tracking
• Mana system (5 points)
• Penalty effects on health and mana
• Visual feedback for penalty points

Timer Features

• Round timer with countdown
• Break time between rounds
• Visual indicators for time status
• Support for pausing/resuming matches

Match Management

• Round-by-round score tracking
• Match winner determination
• Match result display
• Support for multiple matches

Requirements and Restrictions

Scoring Restrictions

• Scoring buttons are disabled when:
  • Match is not started
  • Timer is paused
  • Break time is active
  • A player's health reaches 0
  • Match time has expired
  • Maximum rounds are completed

Penalty System Rules

• Maximum 5 penalty points per player
• Penalty points reduce mana
• Match ends if a player's mana reaches 0
• Penalties can be removed if not at maximum mana

Timer Rules

• Round timer must be started to enable scoring
• Break time is not allowed to skip
• Timer can be paused during active rounds
• Match ends when time expires or health/mana depletes

Winner Determination

Winner is determined in the following order:

1. Health depletion (KO)
2. Mana depletion (penalties)
3. Remaining health points
4. Fewer penalty points
5. Higher technique points
6. More 3-point hits

Note

• User can still operate a match without configuration
• Timer must be started before using any feature
• User cannot reset the previous round's stat during break time
• The system is web-base and only supports PC resolution.

Stats

---

Hope you have a good experience while using the system!