Billiard Scoreboard Documentation v4.0

This documentation contains all installation steps as well as explanations for table control, UI logic, training features and OBS integration.

1 Requirements

• Tested on Ubuntu Server (24.04 LTS)
• PHP 8.3 with SQLite3 support
• Nginx web server
• Internet connection for Material Design Icons (MDI)

2 System Installation

sudo apt update
sudo apt install nginx php8.3-fpm php8.3-sqlite3 -y

3 Folder Structure

sudo mkdir -p /var/www/billard/assets/css
sudo mkdir -p /var/www/billard/assets/js
sudo mkdir -p /var/www/billard/logos

4 Set Permissions

sudo chown -R www-data:www-data /var/www/billard
sudo chmod -R 775 /var/www/billard

or e.g.:

sudo chown -R www-data:www-data /var/www/html
sudo chmod -R 775 /var/www/html

depending on where the files are located.

5 Nginx Configuration

Configuration path: /etc/nginx/sites-available/default

server {
    listen 80;
    root /var/www/billard;
    index index.php index.html;

    location / {
        try_files $uri $uri/ =404;
    }

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;
    }
}

sudo nginx -t
sudo systemctl restart nginx

6 URL Overview

7 Table Control via URL

8 OBS Studio Integration NEW

Setup in OBS

1. In OBS: Sources → + → Browser
2. Enter name (e.g. "Scoreboard Table 1")
3. Enter URL: http://[SERVER-IP]/obs_big.php?Tisch=1
4. Width: 1400 (big) or 700 (small)
5. Height: 150 (big) or 100 (small)
6. Leave "Custom CSS" empty
7. Enable "Refresh browser when scene becomes active"

Recommended Sizes

Setting Up Club Logos

Logos are automatically displayed when a PNG file with the exact club name exists:

# Create logo folder
sudo mkdir -p /var/www/billard/logos

# Upload logos (examples)
/var/www/billard/logos/BC Berlin.png
/var/www/billard/logos/BC Bremen.png
/var/www/billard/logos/Imperium.png

9 Winner/Alternate Break NEW

For 8-Ball, 9-Ball and 10-Ball, the break mode can be selected in setup:

Procedure

1. In setup select Discipline (8-Ball, 9-Ball or 10-Ball)
2. Select Break Mode (Alternate Break or Winner Break)
3. When clicking START GAME the popup "Who breaks first?" appears
4. Select player - the active player is marked with a border
5. On REMATCH you'll be asked again who breaks

10 Help Buttons (Rules & Rack) NEW

All disciplines (14/1, 8-Ball, 9-Ball, 10-Ball) have a Help Button (question mark) in the control bar.

Content per Discipline

11 GD (Game Average) NEW

The GD (Game Average = Points / Innings) is displayed for 14/1 games in multiple places:

12 14/1 History (Player Statistics) NEW

Each player now has a history chart for their 14/1 games. The chart shows the development of high run and GD over the last 20 matches.

How to Open History

1. Navigate to Player Database
2. Click on a Player Card
3. In the popup click "14/1 History" (blue button)

Chart Explanation

Statistics Box

Below the chart the following values are displayed:

• Avg High Run - Average of all displayed high runs
• Max High Run - Best high run in the period
• Avg GD - Average game average
• Max GD - Best GD in the period
• Number of Games - How many 14/1 games are shown

13 Multi-language Support (i18n) NEW

The scoreboard now supports full multi-language capability. The language can be switched at any time in the sidebar.

Supported Languages

Language Switch

1. Open sidebar (burger menu)
2. Click DE or EN at the bottom
3. The entire UI is immediately translated

14 14/1 Live Innings NEW

During a 14/1 game, an overview of all innings played so far can be displayed at any time.

How to Open the Overview

1. During a 14/1 game
2. Click the History Button (clock icon) in the control bar
3. A popup shows all innings with points and intermediate scores

Displayed Information

15 New Disciplines NEW

Rotation

61 points game with the 3-foul rule. If a player commits 3 fouls in a row, they lose the game.

One Pocket

Sink balls into your designated pocket. Default target: 8 balls.

Bank Pool 9-Ball

Only bank shots allowed. Target: 5 balls.

Bank Pool 15-Ball

Only bank shots with all 15 balls. Target: 8 balls.

Doubles Modes

8-Ball, 9-Ball and 10-Ball can be played as doubles (2 vs 2). Team names are automatically combined.

16 Equal Offense Training

Pool 14/1 Levels (1-4)

9-Ball Levels (1-3)

Bowlliards NEW

Bowling scoring on the pool table. Single player training with classic bowling point calculation.

Scoring

10th Frame Special Rules

• Strike: 2 bonus throws (max. 3 throws total)
• Spare: 1 bonus throw (max. 3 throws total)
• Open: No bonus (2 throws)

17 PIN System

18 API Endpoints

19 Troubleshooting

20 Backup

# Create backup
cd /var/www
sudo tar -czf billard-backup-$(date +%Y%m%d).tar.gz billard/

# Restore backup
sudo tar -xzf billard-backup-20250127.tar.gz

Version History

• v4.0 (February 2026) - Multi-language (DE/EN), 14/1 live innings button, dark button text, Rotation with foul logic, One Pocket, Bank Pool, Doubles modes
• v3.8 (February 2026) - 14/1 history in player popup with line chart (High Run & GD), Chart.js integration
• v3.5 (February 2026) - Bowlliards training, Material Design Icons, unified blue buttons, browser compatibility (Firefox/Opera)
• v3.2 (January 2026) - Help buttons 8/9/10-Ball, GD display & champion, EO4 logic (14+X), history PIN protection
• v3.1 (January 2026) - Winner/Alternate break, 4 new OBS overlays, game over lock
• v3.0a (January 2025) - Fix: Equal Offense restart
• v3.0 (January 2025) - OBS integration, logos
• v2.0 (January 2025) - Equal Offense training
• v1.0 (2024) - Basic scoreboard with monitor

Pro Billiard Scoreboard System v4.0 | Developed for billiard players