> For the complete documentation index, see [llms.txt](https://docs.sergioverse.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sergioverse.com/free-air-hockey.md).

# Free Air Hockey

This Air Hockey script completely replaces the original prop from GTA V with a brand-new model. This system allows any player to start a match instantly, solo or with a friend.

[📥 **Download it for free!**](https://store.sergioverse.com/package/airhockey)

### 📸 **Preview**

<div><figure><img src="https://1594809754-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7F3GWo5B2ghxY7IJZ25i%2Fuploads%2FX95U7XRUwohE1UkYVZYP%2FTimeline%201_01_08_47_03.jpg?alt=media&amp;token=efca8fd8-aeb4-45bd-a55e-fae20eb17cef" alt=""><figcaption></figcaption></figure> <figure><img src="https://1594809754-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7F3GWo5B2ghxY7IJZ25i%2Fuploads%2Fe8AhaKXGG1rUJMl7vHsr%2FTimeline%201_01_08_36_12.jpg?alt=media&amp;token=272ad0bc-b24b-4f0c-89a0-4c352d9dc3b3" alt=""><figcaption></figcaption></figure></div>

***

### 📦 **Features**

✅ Fully synced **multiplayer gameplay** (requires OneSync)\
✅ **Professional 3D table model** replacing the original GTA V prop\
✅ **Solo and 1v1 mode** — play alone or against another player\
✅ **Mouse-based movement & controls**\
✅ **Dynamic 3D scoreboard** rendered on the table itself\
✅ **Configurable match time and score limit** (default: 3 min / 7 points)\
✅ **Smooth synchronized animations and physics**\
✅ **All major FiveM languages included** (20+ locales: English, Spanish, French, German, Portuguese, Arabic, and more)\
✅ **Optimized and lightweight** – ideal for roleplay servers\
✅ **Standalone**, works with any framework

***

### ⚙️ **Installation**

#### **1️⃣ Dependencies**

Required:

* **OneSync** (essential for multiplayer sync)

***

#### **2️⃣ AirHockey Pro Resources**

Download and install:

```
sverse_airhockey
sverse_airhockey_assets
```

Place them inside your server’s `resources` folder.

***

#### **3️⃣ Add to `server.cfg`**

```
ensure sverse_airhockey
ensure sverse_airhockey_assets
```

***

#### **4️⃣ Table Integration**

AirHockey **automatically replaces** all air hockey tables across the map with the new professional model.\
You can also:

* Add tables manually through `Config.lua`
* Place them dynamically with a **mapping tool**
* Spawn them through **housing or arcade systems**

No setup required, every table becomes instantly playable.

***

#### **5️⃣ Controls**

* **Mouse movement** → Move the paddle
* **Score limit** → Default 7 (configurable)
* **Time limit** → Default 3 minutes (configurable)
* **Exit game** → Press *Backspace* or *ESC* (configurable)

***

#### **6️⃣ Multiplayer System**

Players can walk up to any air hockey table and interact.\
If no one joins, you can play **solo mode** for practice or fun.

All animations, puck physics, collisions, and scores are **fully synchronized** between nearby players.

***

### 🎮 **How to Play**

1️⃣ Approach any air hockey table.\
2️⃣ Interact using the E key (or the one you put).\
3️⃣ If you’re alone, the game starts in **solo mode**.\
4️⃣ If another player joins, it becomes a **1v1 match**.\
5️⃣ Move your paddle using the **mouse** to hit the puck and score goals.\
6️⃣ The game will stop if both players leave or if 7 rounds (or the pucks you put) are over or there is no **time left.**

The scoreboard is **3D-rendered** on the table and visible for all nearby players in real time, no intrusive UI.

***

### 🧠 **Configuration**

All settings are handled inside `Config.lua`.

#### **⚙️ Basic Settings**

```lua
Config.locale = 'en' -- en, es, pt, fr, de, ar, etc.
```

#### 🏒 **Tables**

```lua
-- Tables setup (position is center of table, heading is direction of the table)
Config.tables = {
    {
        position = vector3(-1635.243896, -1053.903320, 13.137695),
        heading = 323.149597
    }
}
```

#### **🕹️ Gameplay**

```lua
Config.defaultGameOptions = {
    totalPucks = 7,      -- integer > 0 and odd number
    whoStarts = 'random',   -- 'red' | 'blue' | 'random'
    timeLimit = 180,    -- seconds, integer > 0
}
```

#### **🧱Visuals**

```lua
Config.playerAlphaWhilePlaying = 50 -- 0-255 alpha value for player while playing
```

#### **⌨️ Controls**

```lua
Config.playControlKey = 38 -- https://docs.fivem.net/docs/game-references/controls/
Config.playControlLabel = "E"

Config.cancelControlKey = 177 -- https://docs.fivem.net/docs/game-references/controls/
```

#### **🌍 Localization**

Includes **20+ pre-installed languages** (English, Spanish, French, German, Portuguese, Arabic, and more).\
You can add or modify translations inside `Locales.lua`.

#### ❓ **Help Notification**

You can edit the 3D help notification editing the file `Bridge.lua`.

***

### ❓ **FAQ**

**Q: Does it replace the GTA V air hockey prop automatically?**\
A: Yes. All props are replaced with the new high-quality model.

**Q: Can I play solo?**\
A: Yes. Solo mode is supported by default.

**Q: How do I exit a game?**\
A: Press *Backspace* or *ESC* (configurable).

**Q: Is it fully synced for all players nearby?**\
A: Yes. Movements, puck, goals, and animations are synced using OneSync.

**Q: Can I change the score limit or match duration?**\
A: Absolutely. Configurable in `Config.lua`.

**Q: Is there a scoreboard UI?**\
A: The scoreboard is drawn directly on the table, visible in 3D for everyone.

**Q: What languages are included?**\
A: Over 20 languages, including English, Spanish, Portuguese, French, German, and Arabic.

**Q: Can I add my own translations?**\
A: Yes, simply edit the `Locales.lua` file.

**Q: Does it support my framework?**\
A: Yes, it supports any framework.