🏐 Tchoukball Statistics Tracker

Complete guide to the match setup and statistics tracking system

🏠 Go to Setup Page 📊 Go to Game Page

📑 Table of Contents

📋 Overview

This application is a comprehensive match statistics tracking system designed for tchoukball. It consists of two main pages:

🏠 Setup Page

Configure match details

index.html

→

📊 Game Page

Track live statistics

game.html

📝 Match Setup

Configure date, time, location, teams, and players before starting.

⏱️ Track Match Time

Control game timer with play/pause, adjustable speed, and manual adjustments.

🎯 Record Scores

Track team scores with automatic updates from Point and Lost events.

👥 Manage Players

Track up to 12 players per team with playing/bench positions and swaps.

📊 Collect Statistics

Record multiple stat types per player with field position tracking.

🗺️ Field Positioning

Click on the field to record where events occurred with real-world coordinates.

🔍 Advanced Filtering

Filter field events by stat type, team, or individual players.

💾 Save & Load

Auto-save games and manually save/load game states.

☁️ Database Sync

Automatically sync events and scores to a database in real-time.

🏠 Setup Page (index.html)

The Setup Page is the entry point for the application. You must configure match details here before starting to track statistics.

Required Fields

The following fields are mandatory to start a match:

Field Description
Date * Match date (required for saving and identification)
Home Team Name * Name of the home team (displayed throughout the game)
Away Team Name * Name of the away team (displayed throughout the game)
5+ Players per Team * Minimum 5 player names entered for each team

Optional Fields

Field Description
Time Match start time
Location Venue or location of the match
Team Colors Color picker for each team (visual identification)

Loading Players

You can enter player names manually or load from a file:

  1. Click 📁 Load next to the team name
  2. Select a .txt file with player names (one name per line)
  3. Players are loaded into the form (5-12 players per team)

Loading Previous Games

From the setup page, you can resume previous matches:

Starting the Match

  1. Fill in all required fields (date, team names, 5+ players each)
  2. Click ▶ Start Match
  3. You'll be redirected to the Game Page with your configuration
⚠️ Validation: The "Start Match" button is disabled until all required fields are filled. Missing fields will be highlighted in red.

📊 Game Page (game.html)

The Game Page is where you track live match statistics. It shows your team names, colors, and only the players you entered in setup.

Match Info Bar

At the top of the page, you'll see:

Team Display

Your teams are displayed with:

Interface Layout

The game interface is divided into:

💡 Mobile View: On smaller screens, the interface switches to a tab-based layout for easier navigation.

⏱️ Timer Controls

Timer Display

The timer is located at the center of the header, showing time in MM:SS format. Default time is 12:00 minutes.

Control Buttons

Button Function
-1 min Decrease time by 1 minute
-1 sec Decrease time by 1 second
▶︎ / ⏸ Play/Pause the timer
+1 sec Increase time by 1 second
+1 min Increase time by 1 minute

Speed Control

Adjust playback speed from 0.5x to 2x using the dropdown menu:

Period Control

Track which period of the match you're in using the period buttons (◀ / ▶).

Manual Time Edit

Click directly on the timer display to enter a specific time (only when timer is stopped).

🎯 Scoring System

Score Controls

Each team has score controls in the header:

Automatic Score Updates

Scores update automatically when recording certain stats:

Stat Type Score Effect
Point +1 to player's team
Perdu / Lost +1 to opponent's team
✅ Smart Scoring: When you remove a "Point" or "Perdu" event from history, the scores are automatically reverted.

👥 Player Management

Player Setup

Players are configured on the Setup Page before the match. Only the players you entered will appear on the Game Page.

Editing Player Names (Game Page)

  1. Stop the timer
  2. Click directly on a player's name (not the card)
  3. Enter new name in the prompt dialog
  4. Name is updated and game auto-saves

Swapping Players

Use the bench-first swap system:

  1. Click a bench player - card turns yellow
  2. Click a playing player - players swap positions
  3. Stats move with the players
⚠️ Swap System Rules:
  • Must click bench player first
  • Cannot swap two bench players or two playing players
  • Cannot swap players between teams

📊 Player Statistics

Default Stat Types

The system tracks these statistics per player:

Stat Description Effect
Point Successful scoring attempt +1 team score
Perdu Lost ball/possession +1 opponent score
Bloque Blocked attempt -
Penetre Penetration into defense -
Zone Zone entry -
Cadre Shot on target -
Passe Successful pass -
Marcher Walking violation -
Autre Other event -
Defendu Defensive action -

Recording Stats

  1. Click a playing player card - opens stats popup
  2. Click the stat button (e.g., "Point", "Passe")
  3. Optionally, click on the field to record position before selecting stat
  4. Stat is added to player and event history

Viewing Stats

Each player card displays current stats below their name in a compact format.

💡 Tip: Stats are preserved when players are swapped between playing and bench positions.

🗺️ Field Coordinates

Field Specifications

The field represents a real tchoukball court:

Recording Field Positions

  1. Click anywhere on the field - a dot appears
  2. Select a player and stat type
  3. The dot is saved with the event
  4. Coordinates are stored in percentages and real meters

Dot Colors

Dots are color-coded by stat type and have team-colored borders:

✅ Responsive: Dots automatically reposition when you resize the window, maintaining their relative positions on the field.

🔍 Filtering & Analysis

Filter Types

The interface provides three types of filters below the field:

1. Stats Filter

Filter by event type (Point, Perdu, Bloque, etc.)

2. Teams Filter

Filter by team (All, Home, Away)

3. Players Filter

Filter by individual player names

Combined Filtering

All filters work together with AND logic:

Example 1

Stats: "Point" + Teams: "Home" = Shows only Home team's scoring locations

Example 2

Players: "John" + Stats: "Perdu" = Shows only John's lost balls

⚠️ Note: Filters only affect field dot visibility. Event history always shows all events.

📜 Event History

Event Log

All recorded events appear in chronological order, showing:

Removing Events

Each event has a × remove button:

⚠️ Warning: Removing events cannot be undone (unless you reload a saved game state).

💾 Save & Load Games

Auto-Save

The system automatically saves every 30 seconds to browser storage.

💡 Important: Auto-save does NOT automatically restore when you start a new match. You must explicitly click "Load Auto-save" on the Setup Page to resume.

Manual Save to File

  1. Click 💾 Download
  2. File downloads as tchoukball_game_YYYY-MM-DD-HH-MM-SS.json
  3. Store safely for future use

Loading Games

From the Setup Page:

Clear Auto-Save

Use the 🗑️ Clear button on the Game Page to remove the auto-saved game from browser storage.

☁️ Database Integration

Automatic Sync

When database integration is enabled, the application automatically:

Manual Database Save

Click ☁️ Save to DB to manually save the current game state to the database.

Database Requirements

For database integration to work, you need:

💡 Note: See DATABASE_README.md for detailed setup instructions.

💡 Tips & Tricks

Workflow Optimization

Best Practices

Troubleshooting

Problem Solution
Can't start match Check that date, both team names, and at least 5 players per team are filled
Dots in wrong positions after load Wait for the field image to load - dots will reposition automatically
Can't edit player names Make sure timer is stopped first
Auto-save not loading Use "Load Auto-save" button on Setup Page - it won't load automatically
Database not saving Check browser console (F12) for errors. Ensure API is configured.

❓ Need More Help?

For additional support:

✅ You're Ready! Head to the Setup Page to configure your match and start tracking statistics!
🏠 Go to Setup Page 📊 Go to Game Page