Oxide StudiosOxide

Installation Guide

Step-by-step guide to install oxide-animalcontroljob with o-link, unified progression, and the current configuration layout.

Step-by-step setup for oxide-animalcontroljob.

Prerequisites

Required resources

ResourcePurpose
ox_libLocale, callbacks, timers, UI helpers
oxmysqlDatabase driver
o-linkFramework and system abstraction used by this resource

This resource depends on your server's o-link setup for:

  • player identity and character lookup
  • notifications
  • phone messaging
  • money handling
  • inventory for dart weapon management
  • targeting
  • progress bars
  • menu support when Config.menuStyle = 'menu'

Installation

Place the resource

Place oxide-animalcontroljob inside your server's resources folder.

Add startup order

Start dependencies before the job resource:

server.cfg
ensure ox_lib
ensure oxmysql
ensure o-link
ensure oxide-animalcontroljob

Install the SQL table

Run sql/install.sql against your database.

This creates the unified progression table used by current Oxide jobs:

sql/install.sql
CREATE TABLE IF NOT EXISTS `job_progression` (
    `char_id`            VARCHAR(60)      NOT NULL,
    `job`                VARCHAR(40)      NOT NULL,
    `level`              TINYINT          NOT NULL DEFAULT 1,
    `total_count`        INT              NOT NULL DEFAULT 0,
    `daily_streak`       INT              NOT NULL DEFAULT 0,
    `last_activity_date` DATE             NULL,
    `complaints`         TINYINT UNSIGNED NOT NULL DEFAULT 0,
    `timeout_until`      DATETIME         NULL,
    PRIMARY KEY (`char_id`, `job`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

oxide-animalcontroljob stores progression rows with job = 'animalcontrol'.

Migrate old data if needed

If your server is migrating from an older Oxide job install, run sql/migrate_unified_progression.sql once before moving to the unified progression table.

Install the vehicle model

The resource uses the kennel vehicle model by default, based on the Vapid Kennel Animal Control Truck add-on. Ensure that vehicle model is installed on your server, or change Config.Vehicle.model in shared/config/vehicles.lua to a model your server already uses.

Register the dart weapon

The tranquilizer gun uses the WEAPON_G2 weapon hash by default with item name weapon_g2. You must register this weapon in your framework so the inventory system recognizes it. If you prefer a different tranquilizer weapon, update Config.Tranquilizer.weaponHash in shared/config/animals.lua.

Item image: Copy weapon_g2.png from the resource's itemimages/ folder into your inventory image directory:

  • QBCore (qb-inventory): qb-inventory/html/images/
  • ESX / ox_inventory: ox_inventory/web/images/

Step 1: Add the weapon to qb-core/shared/weapons.lua:

qb-core/shared/weapons.lua
[`weapon_g2`] = {
    name = 'weapon_g2',
    label = 'Tranquilizer Gun',
    weapontype = 'Pistol',
    ammotype = 'AMMO_PISTOL',
    damagereason = 'Tranquilized',
},

Step 2: Add the weapon item to qb-core/shared/items.lua:

qb-core/shared/items.lua
weapon_g2 = { name = 'weapon_g2', label = 'Tranquilizer Gun', weight = 1000, type = 'weapon', ammotype = 'AMMO_PISTOL', image = 'weapon_g2.png', unique = true, useable = true, shouldClose = true, description = 'A tranquilizer gun used by animal control' },

Step 3: If you use qb-weapons (durability system), add the weapon to qb-weapons/config.lua inside Config.DurabilityMultiplier:

qb-weapons/config.lua
weapon_g2                    = 0.15,

Without this, qb-weapons will throw attempt to perform arithmetic on a nil value (local 'DecreaseAmount') at server/main.lua:166 the first time the player fires the tranquilizer. Any custom weapon missing from DurabilityMultiplier causes the same crash.

Step 4: Point the job at QBCore's pistol ammo item. Open shared/config/animals.lua in this resource and change the ammoItem line to:

shared/config/animals.lua
ammoItem = 'pistol_ammo',

QBCore's built-in pistol ammo item is named pistol_ammo (it already exists in qb-core/shared/items.lua, so there is nothing to register). The shipped default 'ammo_pistol' does not exist in QBCore — if you skip this step, players will not receive any darts when they clock in.

Step 1: Add the weapon to ox_inventory/data/weapons.lua:

ox_inventory/data/weapons.lua
['WEAPON_G2'] = {
    label = 'Tranquilizer Gun',
    weight = 1000,
    durability = 0.1,
    ammoname = 'ammo-9',
},

Step 2: Update Config.Tranquilizer.ammoItem in shared/config/animals.lua:

shared/config/animals.lua
ammoItem = 'ammo-9',

ammo-9 already exists in stock ox_inventory, so no additional ammo registration is required. QBX uses ox_inventory, so the same steps apply.

Review configuration

Adjust:

  • shared/config.lua
  • shared/config/job.lua
  • shared/config/levels.lua
  • shared/config/locations.lua
  • shared/config/events.lua
  • shared/config/animals.lua
  • shared/config/vehicles.lua
  • shared/config/props.lua
  • shared/config/visuals.lua
  • shared/config/tutorials.lua
  • shared/config/outfits.lua

See the Configuration Reference for the full config surface.

Verification

Start the server and confirm ox_lib, oxmysql, o-link, and oxide-animalcontroljob load without dependency errors.
Join the server and verify the animal control office blip and dispatcher NPC appear.
Interact with the dispatcher through your configured o-link target system.
Clock in, confirm the truck spawns, and wait for a dispatch call.
Accept a call and verify the timer, scene interactions, and payout flow work as expected.

Optional Setup

Phone messaging

If Config.usePhone = true, service messages and text summaries are sent through o-link.phone. Make sure your o-link phone module is configured for the phone resource your server uses.

If you want a popup end-of-shift summary, use:

Config.menuStyle = 'nui'
Config.shiftSummary = 'nui'

If you prefer notification-only output, set:

Config.usePhone = false

Stealth detection

If your server uses a custom crouch system that the native GetPedStealthMovement does not detect, set Config.Stealth.useNativeStealth to false in shared/config/animals.lua. This switches spook checks to random chance instead of crouch detection.

Permission for the builder tool

The /animalcontrolbuilder admin command (used to create new offices and call locations in-game) is restricted to admins. To make someone an admin, add them to the admin group and grant that group the admin ace in your server.cfg:

server.cfg
add_principal identifier.license:<their-license> group.admin
add_ace group.admin admin allow

If you already run QBCore, QBX, or ESX admins, they pass automatically — no extra setup is needed.

Regular players who are not admins see a "No permission" message if they try the command.

See the Admin Guide for builder usage and SQL management.

Notes for UI developers

The packaged web/dist build is already included and referenced by the manifest. Rebuilding the UI is only necessary if you edit files under web/src.

Next Steps

Features

Gameplay flow and systems.

Configuration

Customize settings.

Admin Tools

Commands and builder guidance.

Troubleshooting

Common issues.

On this page

PrerequisitesRequired resourceso-link expectationsInstallationPlace the resourceAdd startup orderInstall the SQL tableMigrate old data if neededInstall the vehicle modelRegister the dart weaponReview configurationVerificationOptional SetupPhone messagingStealth detectionPermission for the builder toolNotes for UI developersNext Steps