Installation Guide

Step-by-step instructions for installing and configuring the oxide-animalcontroljob animal control gig job resource.

---

Prerequisites

Required Resources

Resource	Purpose	Notes
community_bridge	Framework abstraction layer	Available in the Oxide Studios Discord
ox_lib	Utility library, callbacks, progress bars	Required
oxmysql	Async MySQL database driver	Required

Supported Systems

oxide-animalcontroljob uses community_bridge for framework abstraction, supporting any framework that community_bridge integrates with.

System	Supported Via
Framework	community_bridge (ESX, QBCore, QBX, Oxide, etc.)
Target	community_bridge target bridge (ox_target, qb-target, etc.)
Inventory	community_bridge inventory bridge (for dart weapon management)
Phone	community_bridge phone bridge (optional)
Notifications	community_bridge notification bridge
Progress Bar	ox_lib progress bar

---

Installation Steps

1. Download

Download or clone the oxide-animalcontroljob resource folder.

2. Place in Resources

Place the oxide-animalcontroljob folder in your server's resources directory.

3. Add to server.cfg

Add the following to your server.cfg, ensuring dependencies are started first:

ensure ox_lib
ensure oxmysql
ensure community_bridge
ensure oxide-animalcontroljob

4. Configure

Review and adjust configuration files in shared/config.lua and shared/config/*.lua to match your server's needs. See the Configuration Reference for all available settings.

5. Vehicle Model

The resource uses the kennel vehicle model by default (a Vapid Kennel Animal Control Truck addon). Ensure this vehicle model is installed on your server, or change Config.Vehicle.model in shared/config/vehicles.lua to a vehicle model available on your server.

6. Dart Weapon Registration

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

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

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

QBCore

Step 1: Add the weapon to 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:

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' },

ammo_pistol already exists in stock QBCore — no additional ammo registration needed. The default Config.Tranquilizer.ammoItem is already set to 'ammo_pistol'.

ESX / QBX (ox_inventory)

Step 1: Add the weapon to 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 to match ox_inventory's ammo item name:

ammoItem = 'ammo-9',

The ammo-9 item already exists in stock ox_inventory — no additional ammo registration needed. QBX uses ox_inventory, so these same steps apply.

---

Database Setup

Run the Install Script

Execute the SQL file located at sql/install.sql against your database. This creates the progression tracking table.

Schema

animalcontroljob_progression

Column	Type	Default	Description
char_id	VARCHAR(60)	--	Character identifier (primary key)
level	TINYINT	1	Current progression level (1-5)
total_jobs	INT	0	Lifetime completed jobs
daily_streak	INT	0	Consecutive days with completed jobs
last_job_date	DATE	NULL	Date of most recent job
complaints	TINYINT UNSIGNED	0	Current complaint count
timeout_until	DATETIME	NULL	Suspension expiry timestamp

CREATE TABLE IF NOT EXISTS `animalcontroljob_progression` (
    `char_id` VARCHAR(60) NOT NULL,
    `level` TINYINT NOT NULL DEFAULT 1,
    `total_jobs` INT NOT NULL DEFAULT 0,
    `daily_streak` INT NOT NULL DEFAULT 0,
    `last_job_date` DATE NULL,
    `complaints` TINYINT UNSIGNED NOT NULL DEFAULT 0,
    `timeout_until` DATETIME NULL,
    PRIMARY KEY (`char_id`)
);

---

Verification

1. Start the server and check the console for any errors related to oxide-animalcontroljob
2. Connect to the server and verify the Animal Control blip appears on the map
3. Walk to the dispatcher NPC at the animal control office, interact via third-eye, and confirm the shift menu opens. Clock in and wait for a dispatch call to verify the full workflow

---

Optional Setup

Phone Integration

If your server uses a phone resource supported by community_bridge, players will automatically receive email notifications for shift events, dispatch calls, and incident reports. No additional configuration is needed beyond having community_bridge phone support enabled.

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.

ACE Permissions

The /animalcontrolbuilder admin tool requires ACE permissions:

add_ace group.admin admin.animalcontroljob allow

This grants access to the animal control builder menu for creating and exporting office locations and job events. See the Admin Guide for details.

---

Next Steps

• Features — Understand all features and mechanics
• Configuration — Customize settings
• Admin Tools — Admin commands
• Troubleshooting — Common issues and solutions