Documentation
Install Water War on your FiveM server: requirements, the watergun add-on weapon, server.cfg load order, the arenas SQL table and giving staff creator access.
Before installing Water War, make sure your server meets the minimum requirements. Everything on this list is mandatory except the HUD.
Requirement | Status | Notes |
|---|---|---|
OneSync | Required | Hits are read from the server's weapon damage events, which only exist with OneSync. |
oxmysql | Required | Stores the arenas. |
Required |
Arena zones, callbacks and shared helpers. |
Framework | Required | ESX, QBCore or Qbox — detected on start. |
watergun | Required | The add-on weapon, |
qs-interface | Optional | The HUD is hidden while the creator is open. |
The framework is picked by looking at what is already running, and each one has its own small bridge:
Resource running | Bridge used |
|---|---|
|
|
|
|
|
|
After purchasing Water War, the resource is automatically linked to your CFX Portal account.
Sign in to the CFX Portal using the same account used during checkout, open Granted Assets, and download Water War.
After extracting the download, you should have two folders:
[waterwar]/
├── qs-waterwar/ -- the script
│ ├── config/ -- what you may edit
│ ├── custom/ -- framework bridges, notifications, the HUD
│ ├── database/ -- the SQL to import
│ ├── locales/ -- the translations
│ └── web/ -- the interface, ready to use
└── watergun/ -- the add-on water gunKeep both folder names as they are:
qs-waterwarandwatergun. The interface loads its pictures fromnui://qs-waterwar/, and only hits fromWEAPON_WATERGUN— the weapon the watergun resource adds — are counted.
Move both folders into your server's resources directory. They can live anywhere inside it, including a category folder:
resources/
└── [waterwar]/
├── watergun/
└── qs-waterwar/Once copied, open your server.cfg and make sure every dependency starts before Water War:
ensure oxmysql
ensure ox_lib
# Framework — one of these
ensure es_extended
# ensure qb-core
# ensure qbx_core
# Optional
# ensure qs-interface
ensure watergun
ensure qs-waterwarThe loading order matters. The framework is detected only if it is already started, so a framework that starts after Water War is not found and the resource refuses to start.
OneSync must be enabled. Most servers already run it; if yours does not, turn it on in txAdmin's FXServer settings, or start the server with +set onesync on.
Water War keeps every arena in a single table, and that table is not created for you. Import qs-waterwar/database/database.sql once, into the database oxmysql connects to, with HeidiSQL, phpMyAdmin, DBeaver or whichever tool you already use:
CREATE TABLE IF NOT EXISTS `waterwar_arenas` (
`id` INT(11) NOT NULL AUTO_INCREMENT,
`name` VARCHAR(100) NOT NULL,
`duration` INT NOT NULL DEFAULT 180,
`min_players` INT NOT NULL DEFAULT 2,
`max_players` INT NOT NULL DEFAULT 16,
`points` JSON NOT NULL,
`spawn_points` JSON DEFAULT NULL,
`rewards` JSON DEFAULT NULL,
`blip` JSON DEFAULT NULL,
`creator` VARCHAR(50) DEFAULT NULL,
`created_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
`updated_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
PRIMARY KEY (`id`),
INDEX `creator` (`creator`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;Columns | Hold |
|---|---|
name · duration · max_players | The arena's name, its round length in seconds, and its player cap. |
points | The arena's outline and height, exactly as drawn in the creator. |
rewards | Money and items for first, second and third place. |
blip | The map blip: label, sprite, colour, scale and position. |
creator · created_at · updated_at | Who drew it, and when it was created and last changed. |
Without the table nothing can be saved: the creator opens, but every new arena fails with An error occurred and the server console names the missing table.
The creator is where arenas are drawn, changed and deleted, so it sits behind a permission check on the server. Any one of these three routes is enough:
The usual route. With Config.UseAcePermissions = true — the default — any player or group holding the waterwar.creator ace gets in. Add it to server.cfg:
# the whole admin group
add_ace group.admin waterwar.creator allow
# or one player
add_ace identifier.license:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx waterwar.creator allowThe ace's name is Config.AcePermission if you would rather use one your staff already have.
Players whose job and grade appear in Config.CreatorJobs get in. The key is the job name, the value the lowest grade allowed:
Config.CreatorJobs = {
['events'] = 0, -- everybody in the events job
['police'] = 4, -- police from grade 4 up
}The shipped entries, admin and superadmin, are job names — replace them with your own staff job, or leave them if no such job exists.
Automatic, nothing to configure. On ESX, the admin and superadmin groups. On QBCore and Qbox, the admin and god permissions, and anybody allowed the command ace.
Players without access who type the command see You don't have permission for this action, and the server refuses every save, edit or delete they send — the check is not just in the window.
Arenas — their shape, length, cap, rewards and blip — are edited in game. Behaviour that applies to the whole server lives in config/main.lua, one section per subject:
Section | Contents |
|---|---|
Language Selection | The language and debug output. |
Creator Settings | The creator command, the minimum arena size, and who may use the creator. |
Arena Settings | Defaults for new arenas, the water gun and its ammo. |
Water Jet Effect | The jet's particles, size, position and the tuning command. |
Battle Settings | Points per hit, storing and returning weapons, and the arena walls. |
Rewards Configuration | Default rewards for new arenas, and the money account they are paid into. |
Blip Settings | The default blip for new arenas. |
UI Settings | How money is written on screen. |
Editor Controls · Camera Options | The keys and speed of the free camera used to draw arenas. |
The values worth reviewing first:
Config.Locale = 'en' -- en · tr
Config.Debug = false -- ships as true: turn it off on a live server
Config.CreatorCommand = 'waterwarcreator' -- opens the creator
Config.MoneyType = 'money' -- 'money' · 'bank' · 'black_money' (ESX only)
Config.Intl = { -- ships as Turkish lira
locales = 'en-US',
options = { style = 'currency', currency = 'USD', minimumFractionDigits = 0 }
}
Config.Debugships switched on. It prints every step to the console and draws every arena's zone in the world for every player — turn it off before your players join. Changes toconfig/main.luaapply after restartingqs-waterwar.
After completing the installation, restart your server and read the console. A healthy start looks like this:
[WATERWAR] Successfully loaded the framework: esx
WATERWAR INFO: ArenaManager server module initialized
WATERWAR INFO: Battle module initialized
WATERWAR INFO: Creator module initialized
[WATERWAR] Server initialized
WATERWAR INFO: RecordManager initialized with arena typeThe first line names the bridge in use — esx or qb. Then join your server and work through the first loop:
/waterwarcreator opens the Water War Creator. An empty list on a fresh server is correct.
Press Create Arena, name it, press Select under Area Points and click at least four corners around an open space, then Enter. Pick the blip's position inside the outline and save. Usage walks through every field.
Cross the outline. Your weapons are put away, the water gun is in your hands, cyan walls mark the edge and the battle card appears with the clock running. Bring a second player along to score.
Nothing needs a restart from here on. Every arena is created, changed and removed in game, and every connected player sees the change at once.