> For the complete documentation index, see [llms.txt](https://rtx-dev.gitbook.io/rtxdev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://rtx-dev.gitbook.io/rtxdev/table-football.md).

# Table Football

Documentation for RTX Table Football, the FiveM Table Football Script for ESX, QBCore and QBox: installation, configuration, commands, exports and FAQ.

{% embed url="<https://www.youtube.com/watch?v=d7-2pLR5-ck>" %}

## Purchase

[Purchase this resource](https://rtx.tebex.io/package/6191588)

**RTX Table Football** brings real table football to your FiveM server. Walk up to a table, take the handles and play. The ball rolls on the playfield, bounces off the walls and off every single figure, and it shoots exactly as hard as you snap the rod. Play a duel against another player or a match against the computer, put money on it, and every player around sees the same ball, the same rods and both players with their hands on the handles.

## Requirements

| Resource                              | Required                                                                   |
| ------------------------------------- | -------------------------------------------------------------------------- |
| `rtx_tablefootball`                   | Yes - the script, both tables, the figures and the animation are inside it |
| Database                              | No - nothing to import                                                     |
| Inventory                             | No - the script uses no items                                              |
| `ox_target` / `qb-target` / `qtarget` | No - only if you want target instead of the key prompt                     |

## Installation

{% stepper %}
{% step %}

### Add the resource

Place `rtx_tablefootball` into your resources folder and add it to your `server.cfg`, after your framework:

```
ensure rtx_tablefootball
```

{% hint style="warning" %}
Keep the `stream` folder and the `data` folder. The `stream` folder holds the tables, the figures and the animation, the `data` folder is where the tables you place in game are saved.
{% endhint %}
{% endstep %}

{% step %}

### Framework

Open `config.lua`, section 1:

```lua
Config.Framework = "esx" -- "esx", "qbcore" or "standalone"

Config.MoneyAccount = "money" -- "money" (cash) or "bank"
```

| Framework          | Value          |
| ------------------ | -------------- |
| ESX                | `"esx"`        |
| QBCore / QBox      | `"qbcore"`     |
| Standalone / other | `"standalone"` |

{% hint style="info" %}
In standalone mode every match is free, unless you fill in the money functions in `server/other.lua`. Use the ESX and QBCore parts in the same file as reference.
{% endhint %}
{% endstep %}

{% step %}

### Admins

The table creator and the reset command belong to whoever your `server.cfg` gives `tablefootball.admin` to:

```
add_ace group.admin tablefootball.admin allow
```

ESX groups, QBCore permissions and single players by identifier can be allowed too, see [Permissions](#permissions).
{% endstep %}
{% endstepper %}

## How a Match Works

Walk up to a table and press `E`. The table menu opens: pick **Duel** or **Against the computer**, how many goals win the match, the stake or the difficulty, and start the match. The side you play is the side of the table you stand at - walk round the table to play the other one.

In a duel the match waits for a second player. He walks up to the other side of the table and presses `E` to join, and players standing nearby get a notification that somebody is waiting for an opponent. After the countdown and the whistle the ball is served.

| Key               | Action                                                                    |
| ----------------- | ------------------------------------------------------------------------- |
| `E`               | Open the table menu, join a match                                         |
| `MOUSE` / `A` `D` | Slide your rods                                                           |
| `LMB` / `SPACE`   | Hold to wind up the rod, let go to shoot. The longer you hold, the harder |
| `RMB`             | Hold to lift your rods, so the ball rolls under them                      |
| `SCROLL`          | Take another rod yourself                                                 |
| `C`               | Switch the camera                                                         |
| `G`               | The match menu - rules, ask for a re-serve, leave the match               |

The rod you hold is picked for you, it is always the one nearest to the ball. The first team to reach the goal count wins. At the end both players see the result: goals, shots and the fastest shot of both players, the match time and the pot.

{% hint style="info" %}
Leaving the match counts as giving up. A player who walks away from the table, leaves the server, dies or goes down gives the match up too, and the other player wins.
{% endhint %}

### Game modes

```lua
Config.Modes = {
	["duel"] = true, -- Two players, one on each side of the table
	["computer"] = true -- One player against the computer, which plays the other side
}
```

### Match rules

```lua
Config.Match = {
	goals = 5, -- Goals needed to win, filled in when the menu opens
	goalsoptions = {3, 5, 7, 10}, -- What the player can pick in the menu
	countdown = 3, -- Seconds of countdown before the first serve of a match
	goalpause = 2.5, -- Seconds after a goal before the ball is served again
	servedelay = 1.0, -- Seconds between "re-serve" and the ball rolling in
	serve = "conceded", -- Who serves after a goal: "conceded", "scorer" or "random"
	deadball = 3, -- A ball lying still where no figure can reach it gets a small push back into play after this many seconds. 0 = never
	nudgespeed = 0.55, -- How hard that push is, in metres per second
	keeperball = 2.0, -- A ball lying still between a goalkeeper and his goal is put back in front of him after this many seconds. 0 = never
	possession = 15, -- Seconds one rod may keep the ball before the other team gets the serve. 0 = no limit
	stall = 8, -- A ball that has not moved for this many seconds gets the same small push. 0 = never
	lobbytime = 180, -- Seconds a match waits for a second player before it closes on its own
	finishdelay = 4, -- Seconds the result stays up before the table is free again
	leaveondeath = true -- true = a player who dies or goes down gives up his match
}
```

Spinning the rods all the way round is forbidden by the real rules and is off with `Config.Rods.spinning = false`.

### The computer

```lua
Config.Computer = {
	default = "normal", -- Difficulty filled in when the menu opens: "easy", "normal" or "hard"
	difficulty = {
		easy = {speed = 0.25, reaction = 0.3, anticipation = 0.04, error = 0.035, kick = 26.0, cooldown = 1.2, delay = 0.5},
		normal = {speed = 0.38, reaction = 0.2, anticipation = 0.08, error = 0.022, kick = 36.0, cooldown = 0.8, delay = 0.28},
		hard = {speed = 0.6, reaction = 0.1, anticipation = 0.14, error = 0.01, kick = 50.0, cooldown = 0.45, delay = 0.1}
	}
}
```

| Value          | What it does                                                 |
| -------------- | ------------------------------------------------------------ |
| `speed`        | How fast the computer slides its rods, in metres per second  |
| `reaction`     | How late it notices where the ball went, in seconds          |
| `anticipation` | How far ahead it guesses where the ball is going, in seconds |
| `error`        | How far off it may place its men, in metres                  |
| `kick`         | How hard it shoots                                           |
| `cooldown`     | Seconds between two shots of the same rod                    |
| `delay`        | Seconds it takes its time over a ball it could shoot         |

## Tables

There are three ways a table gets into the game, and they all work the same:

* **The table creator** - `/tablefootballcreator`, see [Table Creator](#table-creator)
* **`config.lua`** - `Config.Tables`, for those who like to write them by hand
* **Your map and other scripts** - every RTX football table that stands in the world is found automatically and can be played too: placed by a mapper in an MLO, put down as furniture in a housing script, or spawned by another script. The rods, the ball and the goal counter are added on their own. `Config.WorldTables = false` turns this off

```lua
Config.Tables = {
	{
		label = "Beach", -- Name shown in the table menu
		type = 1, -- 1 = RTX table, version 1, 2 = RTX table, version 2
		coords = vector3(-1612.09, -1069.66, 12.01), -- Where the table stands, on the floor
		heading = 90.0, -- Which way the table points
		price = 0, -- What each player pays to start a match here. 0 = free
		manage = {
			enabled = false -- see Business Tables
		}
	}
}
```

| Type | Table                |
| ---- | -------------------- |
| `1`  | RTX table, version 1 |
| `2`  | RTX table, version 2 |

{% hint style="info" %}
A table from another script is found when it is a local object, the way maps and most housing scripts spawn their furniture. A table spawned as a networked entity is skipped. A found table is remembered by where it stands until the next restart of the resource.
{% endhint %}

### Distances

```lua
Config.Distances = {
	spawn = 80.0, -- Your tables are spawned for a player closer than this, in metres
	stream = 40.0, -- A player closer than this to a table sees its rods, the ball and every match played on it
	interact = 1.1, -- How close to the edge of the table a player has to stand to use it
	leave = 6.0 -- A player in a match who gets further than this from the table gives the match up
}
```

## Table Creator

```
/tablefootballcreator
```

Opens the list of every table placed with the creator, nearest first. From there you can place a new table, edit one, go to it or delete it.

### Placing a table

The table follows where you look.

| Key                | Action          |
| ------------------ | --------------- |
| `MOUSE`            | Position        |
| `SCROLL` / `Q` `E` | Rotate          |
| `SHIFT`            | Finer steps     |
| `↑` `↓`            | Height          |
| `←` `→`            | Table type      |
| `LMB` / `ENTER`    | Place the table |
| `BACKSPACE`        | Back            |

### The form

The table stays where you put it while you fill in its name, the table type, the entry price and the managed table part - job, lowest grade, groups, ACE, players, starts locked, who can set the price, the highest price and the society. Save it and it appears for every player straight away - no restart.

```lua
Config.Creator = {
	groups = {"admin", "superadmin", "god"}, -- ESX groups / QBCore permissions that can use the creator
	identifiers = {}, -- Single players, by any identifier
	rotatestep = 5.0, -- Degrees one scroll turns the table while placing it. Hold SHIFT for 0.5 degree steps
	distance = 12.0 -- How far in front of the camera a table can be placed, in metres
}
```

{% hint style="info" %}
Tables placed with the creator are saved in `data/tables.json`, together with the locked / open state and the prices set on managed tables. Keep that file when you update the resource.
{% endhint %}

## Business Tables

Turn on `manage` for a table, in the creator or in `Config.Tables`, and the players you allow manage the table right at it.

* They open the table menu with `E`, or the management with `G`, and get a **Management** part at the bottom
* **Lock and unlock** the table - on a locked table nobody can start a match
* **Set the entry price**, up to the highest price you allow

```lua
manage = {
	enabled = true,
	job = "bahama", -- Job that can manage the table, "" = no job
	grade = 0, -- Lowest grade of that job
	groups = {}, -- ESX groups / QBCore permissions
	ace = "", -- e.g. "tablefootball.bahama"
	identifiers = {}, -- Single players, by any identifier
	locked = false, -- true = the table starts locked until it is opened
	setprice = true, -- true = they can change the entry price
	maxprice = 5000, -- Highest entry price they can set
	society = true -- true = the entry price goes to the job's society account
}
```

Who can manage it is any mix of a job from a grade, ESX groups / QBCore permissions, an ACE and single players.

```lua
Config.JobTables = {
	savestate = true -- Locked or open and the price are remembered after a restart
}
```

{% hint style="info" %}
Society money goes to `esx_addonaccount` on ESX and to `qb-banking` or `qb-management` on QBCore. Any other banking script is a few lines in `AddSocietyMoneyRTX` in `server/other.lua`.
{% endhint %}

## Price & Stakes

```lua
Config.Price = {
	default = 0 -- What each player pays to start a match on tables with no price of their own. 0 is free
}

Config.Stakes = {
	enabled = true, -- The player who opens a duel can put money on it. The second player pays the same to join
	min = 0, -- Smallest stake
	max = 50000, -- Biggest stake
	default = 0, -- Stake filled in when the menu opens
	fee = 0 -- Percent the house keeps from the pot. 0 gives the winner everything
}
```

The **entry price** is what each player pays to play at the table, matches against the computer pay the same. The **stake** is money on a duel: both players pay it and the winner takes the pot. When a match is cancelled before it is decided - nobody joined in time, or an admin reset the table - the stakes are paid back.

## Rods & Feel

How the rods answer the player's hands. All of it is the player's own feel, it never changes the physics.

```lua
Config.Rods = {
	select = "auto", -- "auto" = the rod nearest to the ball is taken for you, "manual" = you choose the rod with SCROLL
	autolift = true, -- A rod lifts by itself for a moment when a slow ball is stuck under one of its figures
	autoclear = true, -- While one of your rods shoots, your rods in front of it lift out of the way
	highlight = false, -- true = the rod you hold glows with a thin white outline
	aimassist = 0.05, -- While you hold the shoot key, the nearest figure slides onto the ball if it is at most this far off (metres). 0.0 = no help
	follow = "together", -- "together" = every rod follows your hand, "hold" = only the rod you hold slides
	slidesensitivity = 0.12, -- How far the rods slide for a mouse movement
	mouseswing = false, -- true = moving the mouse forward and back swings the rod by hand, for experienced players
	minshot = 26.0, -- Rod speed of a quick tap of the shoot key
	maxshot = 58.0, -- Rod speed of a fully charged shot
	chargetime = 0.8, -- Seconds the shoot key has to be held for a full power shot
	spinning = false -- true allows spinning the rods all the way round
}
```

The full list with every value is in `config.lua`, section 8.

## Cameras & Players

The player switches the camera with `C`.

| Camera     | What it shows                                                       |
| ---------- | ------------------------------------------------------------------- |
| `"end"`    | Behind your own goal, looking at the other one                      |
| `"side"`   | From the long side, high above the table, both goals left and right |
| `"top"`    | Straight from above, your attack goes up the screen                 |
| `"player"` | Your own eyes, standing at your handles                             |

```lua
Config.Camera = {
	default = "end", -- Camera a match starts in
	views = {"end", "side", "top", "player"}, -- Which views C cycles through, in this order
	transition = 450 -- Milliseconds the camera takes to blend
}
```

Every view has its own distance, height and field of view in `config.lua`, section 9.

### Hands on the handles

```lua
Config.Players = {
	distance = 0.98, -- How far from the middle of the table the player stands at his handles, in metres
	handik = true, -- true = the hands of every player hold the handles of his rods and follow them
	animation = 1, -- Which of the animations in the list a player plays at the table
	reachfit = true, -- The player is moved closer and turned until both of his arms reach their handles. Works for every ped
	sway = 1.0, -- How much the body moves with the rods the player holds
	autofit = true -- The player is moved and turned so that his two hands land on the handles
}
```

The first animation in `Config.Players.animations` is the custom RTX animation. Try the others in game with `/tablefootballanim` while you play - it switches to the next one and shows its number.

### Scoreboard and HUD

```lua
Config.Scoreboard = {
	enabled = true, -- The score card at the top of the screen during a match
	spectators = true, -- Players standing next to a table that is playing see the score card, the countdown and the goals too
	spectatordistance = 6.0 -- How close a spectator has to stand, in metres
}

Config.HideHud = true -- Hides your other HUD while you stand at the table in a match
```

What gets hidden with `Config.HideHud` is in `HideHudRTX` / `ShowHudRTX` in `client/other.lua` - put your own HUD in there.

## Interface & Interaction

```lua
Config.Language = "English"
Config.InterfaceColor = "#ff66ff" -- Accent colour of the whole interface
Config.Teams = {
	[1] = "#ee3b30", -- Colour of the red team in the interface
	[2] = "#3d9bff" -- Colour of the blue team in the interface
}
Config.Currency = "$"
Config.InteractionSystem = 1
Config.PromptPosition = "right" -- "right", "center" or "left"
Config.Notifications = "rtx"
```

| `InteractionSystem` | Prompt                                         |
| ------------------- | ---------------------------------------------- |
| `1`                 | RTX prompt, matching the rest of the interface |
| `2`                 | 3D text                                        |
| `3`                 | GTA Online style help                          |
| `4`                 | Floating help text above the table             |

`Config.Notifications = "rtx"` uses the built-in notifications. Anything else calls `Notify()` in `client/other.lua`, where your own notification system goes.

### Keys

```lua
Config.Keys = {
	interact = "E", -- At a table: open the menu, join a match
	menu = "G" -- During a match: the match menu. At a managed table: management
}

Config.Controls = {
	shoot = {id = 24, label = "LMB"},
	shootkey = {id = 22, label = "SPACE"},
	lift = {id = 25, label = "RMB"},
	rodnext = {id = 241, label = "SCROLL"},
	rodprev = {id = 242, label = "SCROLL"},
	left = {id = 34, label = "A"},
	right = {id = 35, label = "D"},
	camera = {id = 26, label = "C"}
}
```

{% hint style="info" %}
`E`, `G`, the shot and the lift are key mappings. Every player can rebind them in **Settings > Key Bindings > FiveM**.
{% endhint %}

### Target

```lua
Config.Target = true
Config.Targettype = "oxtarget" -- "oxtarget", "qbtarget" or "qtarget"
```

The table gets target options for the table menu, joining a match and the management instead of the `E` prompt. The registering is in `client/other.lua`, open source.

## Sounds

```lua
Config.Sounds = {
	enabled = true,
	volume = 0.85, -- Master volume, 0.0 to 1.0
	distance = 16.0, -- Nobody further away than this hears the table, in metres
	interface = true -- Sounds of the interface: kick-off, goal, win
}
```

Every kick, wall, post, goal and rod knock plays from where it happened, louder for a harder hit and quieter the further away you are. The files are in `html/sounds`, replace them freely.

## Physics

The playfield is tuned to a real table. Friction, how springy the walls and the figures are, the ramps in the corners and the fastest ball are all in `Config.Physics`.

{% hint style="warning" %}
Every player and the server use the same physics values. Change them only while the server is stopped, never with a live edit in the middle of matches.
{% endhint %}

## Synchronization

Each player moves his own rods on his own screen with no delay. The moment one of his figures touches the ball, his game sends the server where the ball is and how fast it goes. The server checks that it is possible - the ball really was there, one of his rods can reach it, the speed is legal - and passes it on to everyone at the table. Between touches the ball follows the same physics on every screen and on the server, so all players see the same ball, and only the server decides goals, dead balls and the score.

No ball, rod or table is a networked entity. Everything is created locally on each player's screen, so the script runs on servers with `sv_entityLockdown "strict"` without any extra setup. Every payment and every match is checked on the server.

`Config.Sync` works well as it is. Change it only if you know why.

## Player Checks

Nobody can use a table while dead or down, cuffed, in a vehicle, in the pause menu or with the inventory open. A player who dies or goes down during a match gives it up, and so does a player who gets further than `Config.Distances.leave` from the table.

How death and cuffs are detected is in `IsPlayerDeadRTX()` and `AllowedInteraction()` in `client/other.lua`, open for your own ambulance and police scripts. Your ambulance script can also trigger `rtx_tablefootball:client:playerDied` to take a dead player out of his match right away.

## Commands

| Command                 | Who       | What it does                                                                   |
| ----------------------- | --------- | ------------------------------------------------------------------------------ |
| `/tablefootballleave`   | Everybody | Leave the match you are in. It counts as giving up                             |
| `/tablefootballanim`    | Everybody | While you play: switches to the next standing animation and shows its number   |
| `/tablefootballreset`   | Admins    | Reset the table next to you, a running match is cancelled and stakes paid back |
| `/tablefootballcreator` | Admins    | The table creator                                                              |

```lua
Config.Commands = {
	leave = "tablefootballleave",
	reset = "tablefootballreset",
	creator = "tablefootballcreator",
	animation = "tablefootballanim"
}
```

Rename any of them, or set it to `""` and it is never registered.

## Permissions

```lua
Config.AdminAce = "tablefootball.admin"

Config.Creator = {
	groups = {"admin", "superadmin", "god"},
	identifiers = {}
}
```

A player can use the creator and the reset command if **any** of these is true:

* he has the ACE `tablefootball.admin`
* his ESX group / QBCore permission is in `groups`
* one of his identifiers is in `identifiers`

Identifiers can be the ESX identifier, the QBCore citizenid, `license:`, `steam:`, `discord:` - or just the part after the colon.

## Language

Every line of text - notifications and the whole interface - is in the `language` folder, open source. 18 languages are included:

English, German, Spanish, French, Czech, Polish, Portuguese, Italian, Russian, Turkish, Korean, Dutch, Chinese, Romanian, Hungarian, Thai, Japanese, Arabic

```lua
Config.Language = "German"
```

## Open-Source Files

This product is protected by the Escrow System. You can still configure almost everything:

| File               | What is in it                                                                        |
| ------------------ | ------------------------------------------------------------------------------------ |
| `config.lua`       | Everything configurable, fully commented                                             |
| `language/*.lua`   | Every text, in 18 languages                                                          |
| `client/other.lua` | Notifications, prompts, target, death check, hiding your HUD, match hooks            |
| `server/other.lua` | Money, jobs, society accounts, admin checks, player names, Discord logs, match hooks |
| `html`             | The interface and the sounds                                                         |
| `data/tables.json` | The tables placed with the creator                                                   |

### Discord logs

Switched on in `server/other.lua`, in `LogsRTX`. The webhook lives there too - never put it in `config.lua`, that file is sent to every player.

## Exports & Events

### Client exports

```lua
exports["rtx_tablefootball"]:IsPlayingFootball() -- true while the player is in a match
exports["rtx_tablefootball"]:GetFootballSide() -- 1 (red) or 2 (blue) while the player stands at the rods, nil otherwise
```

### Server exports

```lua
exports["rtx_tablefootball"]:IsPlayerPlayingFootball(source)
exports["rtx_tablefootball"]:GetPlayerFootballTable(source) -- id of the table the player plays at, or nil
```

### Server events

```lua
AddEventHandler("rtx_tablefootball:server:paid", function(source, amount, tableid) end)
AddEventHandler("rtx_tablefootball:server:matchStarted", function(tableid, mode, players, stake) end)
AddEventHandler("rtx_tablefootball:server:matchEnded", function(tableid, result) end)
```

`result` holds the mode, the reason the match ended, the winner, the players, the score, the stats of both sides (goals, shots, fastest shot), the pot and the duration in seconds.

### Client events

```lua
AddEventHandler("rtx_tablefootball:client:matchStarted", function(tableid, mode) end)
AddEventHandler("rtx_tablefootball:client:matchEnded", function(tableid, result) end)
AddEventHandler("rtx_tablefootball:client:hideHud", function() end)
AddEventHandler("rtx_tablefootball:client:showHud", function() end)
TriggerEvent("rtx_tablefootball:client:playerDied") -- from your ambulance script
```

## Updating from the Old Version

{% stepper %}
{% step %}

### Back up and replace

Back up your `config.lua`, then replace the whole `rtx_tablefootball` folder.
{% endstep %}

{% step %}

### Configure tables and settings

Set your tables and settings again in the new `config.lua` - or place them in game with `/tablefootballcreator`.
{% endstep %}

{% step %}

### Do not run both versions

Do not run the new version next to the old one.
{% endstep %}
{% endstepper %}

## Troubleshooting

<details>

<summary>The tables do not show up</summary>

The `stream` folder is missing or was renamed. Put it back and restart the server - streamed models are only picked up by players who connect after the restart.

</details>

<details>

<summary>Nobody pays for a match on standalone</summary>

Standalone has no money system. Fill in the money functions in `server/other.lua`.

</details>

<details>

<summary>The management does not show up</summary>

Only players who can manage the table see it. Check that `manage.enabled` is on for the table, and the job and grade, the groups, the ACE and the identifiers.

</details>

<details>

<summary>The creator says I am not allowed</summary>

Check the ACE in `server.cfg`, `Config.Creator.groups` and `Config.Creator.identifiers`. Any one of them is enough.

</details>

<details>

<summary>Target does not work</summary>

`Config.Target = true` needs the target resource running. If it is not, the console says so at startup.

</details>

<details>

<summary>A table in my MLO cannot be played</summary>

`Config.WorldTables` has to be `true`, the table has to be one of the two RTX table models, and it has to be a local object - a table that another script spawns as a networked entity is skipped.

</details>

<details>

<summary>A dead player stays in his match</summary>

Your ambulance script uses a death state the script does not know yet. Add it to `IsPlayerDeadRTX()` in `client/other.lua`, or trigger `rtx_tablefootball:client:playerDied`.

</details>

<details>

<summary>The hands are not on the handles</summary>

Keep `Config.Players.handik`, `autofit` and `reachfit` on. For fine tuning there are `handheight`, `handgrip` and `handback` in `Config.Players`.

</details>

## Support

If you need help with installation, configuration or have any questions regarding this resource, feel free to contact us on our Discord server:

[Join our Discord](https://discord.gg/rtxdev)
