Billiard Scoreboard Documentation v4.5

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 {
    background-color: rgba(0, 0, 0, 0);
    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

CSS with Text Alignment

To display text vertically centered with horizontal alignment, use the following CSS variants:

Text left-aligned:

body {
    background-color: rgba(0, 0, 0, 0);
    color: #ffffff;
    font-family: "Arial";
    font-size: 40px;
    font-weight: bold;
    text-shadow: 2px 2px 4px #000000;
    overflow: hidden;
    margin: 0;
    height: 100vh;
    display: flex;
    align-items: center;
    justify-content: flex-start;
}

Text centered:

body {
    background-color: rgba(0, 0, 0, 0);
    color: #ffffff;
    font-family: "Arial";
    font-size: 40px;
    font-weight: bold;
    text-shadow: 2px 2px 4px #000000;
    overflow: hidden;
    margin: 0;
    height: 100vh;
    display: flex;
    align-items: center;
    justify-content: center;
}

Text right-aligned:

body {
    background-color: rgba(0, 0, 0, 0);
    color: #ffffff;
    font-family: "Arial";
    font-size: 40px;
    font-weight: bold;
    text-shadow: 2px 2px 4px #000000;
    overflow: hidden;
    margin: 0;
    height: 100vh;
    display: flex;
    align-items: center;
    justify-content: flex-end;
}

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 (Server)

# 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

23 In-App Backup & Restore NEW v4.3

All data can be exported as a JSON file and re-imported directly in the app.

Create Backup

1. Navigate to Player Database
2. Click "Backup" (download icon)
3. A JSON file is downloaded: billard-backup-YYYY-MM-DD.json

Import Backup

1. Click "Restore" (upload icon)
2. Enter the Master PIN
3. Select the JSON backup file
4. Confirm the import - all data will be overwritten

Included Data

• Players and clubs
• All statistics (incl. discipline stats, H2H)
• Game history
• Training results

24 Rankings NEW v4.3

The rankings show all players in a sortable table.

Sort Options

Displayed Columns

• # - Rank
• Name - Player name and club
• Win% - Win percentage
• W - Wins
• L - Losses
• HS - High run
• GD - Best game average

25 Player Statistics NEW v4.3

Detailed statistics per player, accessible via the player action popup.

How to Open Statistics

1. Navigate to Player Database
2. Click on a Player Card
3. Click "Statistics" in the popup

Included Information

Win% on Player Cards

The win percentage is displayed directly on each player card (with at least 1 game). Players with 3+ consecutive wins receive a green streak badge (e.g. "5W").

Win% Champion

In the champions section, the player with the best win percentage is displayed (minimum 5 games required).

26 Player Comparison NEW v4.3

Two players can be compared directly.

How to Open Comparison

1. Navigate to Player Database
2. Click "Compare" (scale icon)
3. Select two players from the dropdowns

Compared Values

27 History Improvements NEW v4.3

Filter

History entries can be filtered:

• Player Search - Free text search by player name
• Discipline - Dropdown with all played disciplines

CSV Export

The game history can be exported as a CSV file (semicolon-separated, UTF-8 with BOM for Excel).

Included columns: Date, Discipline, Race, Player 1, Player 2, Score 1, Score 2, Winner

28 Training Progress Chart NEW v4.3

Shows the development of training results as a line chart.

How to Open the Chart

1. Click on a Player Card
2. Click "Training Progress" in the popup
3. Select an exercise from the dropdown

Chart Elements

• Green line - Score trend (last 20 results)
• Red dashed line - Target value of the exercise
• Statistics box - Average and maximum

29 Cancel Game NEW v4.4

A new button in the popup menu (tool icons) allows you to cancel the current game.

How It Works

1. During a game, click the Tools button (wrench icon)
2. In the popup, a new Cancel icon (X) appears next to Restart, Undo and Help
3. After clicking, a confirmation popup is displayed
4. Upon confirmation, the game ends - without saving any values to statistics

30 Icon Configuration NEW v4.4

The appearance of buttons can be configured in config.php.

Settings

Example config.php

define('ICON_STYLE', 'square');   // 'round' or 'square'
define('ICON_3D', true);          // true = 3D shadows, false = flat

31 Legal Notice & Privacy Policy NEW v4.4

The sidebar provides access to Legal Notice (Impressum) and Privacy Policy pages. The pages contain sample texts that should be customized.

Activation

In config.php:

define('SHOW_LEGAL', true);   // true = visible, false = hidden

Access

1. Open sidebar (burger menu)
2. Below "Fullscreen", the links Legal Notice and Privacy Policy appear
3. Click the respective link

32 Login System NEW v4.5

The start page (index.php) can optionally be protected with a login. There are two login methods: admin login and player login.

Activation

In config.php:

define('REQUIRE_LOGIN', true);    // true = login required, false = no login
define('LOGIN_USER', 'admin');    // Admin username
define('LOGIN_PASS', 'billard'); // Admin password

Admin Login

The administrator can log in using the credentials defined in config.php (LOGIN_USER / LOGIN_PASS).

Player Login

Players can log in with their name and PIN, provided the "Login Startpage" checkbox is enabled in the player editor.

1. Navigate to Player Database
2. Edit player (pencil icon)
3. Enable the "Login Startpage" checkbox
4. Save

Login Form

• Field Name - Admin username or player name
• Field Password / PIN - Admin password or player PIN
• The name input is not case-sensitive

Logout

A Logout button appears in the sidebar (only visible when login is active). Clicking it ends the session.

Version History

• v4.5 (February 2026) - Login system (admin + player login with name/PIN, configurable in config.php, logout button in sidebar)
• v4.4 (February 2026) - Cancel game (without statistics), Icon configuration (round/square, 3D shadows), Legal Notice & Privacy Policy (sample texts, config.php)
• v4.3 (February 2026) - Rankings, Player Statistics (per discipline, H2H, Win%, Streaks), Player Comparison, History Filter, CSV Export, Training Progress Chart, In-App Backup/Restore
• 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.5 | Developed for billiard players