Billiard Scoreboard Documentation v4.2

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

Color Scheme via URL NEW

The color scheme can be set directly via a URL parameter. Both German and English names are accepted:

Language via URL NEW

The language can be set directly via a URL parameter:

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 Game Timer & Header Display NEW v4.2

During a running game, the discipline and running game time are displayed in the header.

Features

• The current discipline is shown centered in the header
• Below it, the game time runs in HH:MM:SS format
• The logo is displayed on the right side of the header (visible on all pages)
• On Rematch, the game time continues without interruption
• When the game ends, the timer stops

10 OBS Text Files NEW v4.2

In addition to the browser overlays, individual TXT files are automatically generated in the /obs/ folder. These can be used as browser sources in OBS.

Available Files per Table

Setup in OBS (Browser Source)

The recommended method is using a Browser source with the xObsBrowserAutoRefresh plugin:

1. Install the xObsBrowserAutoRefresh plugin
2. In OBS: Sources → + → Browser
3. Enter URL: http://[SERVER-IP]/obs/table1_score1.txt
4. Adjust width/height as needed
5. Enter Custom CSS for text formatting:

body {
    color: #ffffff;
    font-family: "Arial";
    font-size: 40px;
    font-weight: bold;
    text-shadow: 2px 2px 4px #000000;
    overflow: hidden;
}

6. Right-click on the browser source → Filters
7. Click + to add the "Browser Auto-refresh" filter
8. Set the interval to 15 seconds

11 Winner/Alternate Break

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

12 Help Buttons (Rules & Rack)

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

Content per Discipline

13 GD (Game Average)

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

14 14/1 History (Player Statistics)

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

15 Multi-language Support (i18n)

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

16 14/1 Live Innings

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

17 New Disciplines

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.

18 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)

19 PIN System

20 API Endpoints

21 Troubleshooting

22 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.2 (February 2026) - Game timer in header (discipline + timer), OBS text files (individual files per value in /obs/ folder, configurable interval)
• v4.1 (February 2026) - URL parameters for color scheme (theme) and language (lang), OBS overlays with i18n, monitor_en.php
• 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.2 | Developed for billiard players