Installation Guide

Step-by-step setup for oxide-animalcontroljob.

Prerequisites

Required resources

o-link expectations

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

ensure ox_lib
ensure oxmysql
ensure o-link
ensure oxide-animalcontroljob

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;

[`weapon_g2`] = {
    name = 'weapon_g2',
    label = 'Tranquilizer Gun',
    weapontype = 'Pistol',
    ammotype = 'AMMO_ANIMALCONTROL_DART',
    damagereason = 'Tranquilized',
},

weapon_g2 = { name = 'weapon_g2', label = 'Tranquilizer Gun', weight = 1000, type = 'weapon', ammotype = 'AMMO_ANIMALCONTROL_DART', image = 'weapon_g2.png', unique = true, useable = true, shouldClose = true, description = 'A tranquilizer gun used by animal control' },

weapon_g2                    = 0.15,

ammo_dart = { name = 'ammo_dart', label = 'Tranquilizer Dart', weight = 20, type = 'item', image = 'ammo_dart.png', unique = false, useable = true, shouldClose = true, description = 'One dart for an animal control tranquilizer gun' },

ammo_dart = { ammoType = 'AMMO_ANIMALCONTROL_DART', amount = 1 },

Config.WeaponRepairCosts.animalcontrol = Config.WeaponRepairCosts.pistol

return {
    Weapons = {
        ['WEAPON_G2'] = { label = 'Tranquilizer Gun', weight = 1000, durability = 0.1, ammoname = 'ammo_dart', client = { image = 'weapon_g2.png' } },
    },

    Ammo = {
        ['ammo_dart'] = { label = 'Tranquilizer Dart', weight = 20 },
    },
}

Updating an Existing Installation

Updating from a version that used pistol ammo for the dart gun:

No SQL is needed for this update. The settings table is created automatically on first start.

Extra darts require enough earned shift pay to cover their price; the initial pack is free. Equipment identifiers can be changed in settings after all active shifts end.

Existing saved events at (0, 0, 0) are excluded from dispatch without replacing the owner's list. Edit or remove that scene in /animalcontrol settings. An empty call list leaves dispatch idle.

Verification

Optional Setup

Phone messaging

When Config.usePhone = true (the default), the animal control office sends the player phone messages: a welcome when they clock in, notices for a destroyed truck, an escaped or killed animal, and a shift cancelled after going down on the job, and the detailed pay summary at clock-out (when Config.shiftSummary = 'text'). The phone also rings for each incoming call. Make sure your o-link phone module is configured for the phone resource your server uses.

Supported phones: qb-phone, lb-phone, gksphone, okokPhone, qs-smartphone, qs-smartphone-pro, yseries and Oxide Phone. How the messages arrive depends on the phone:

Incoming call ring: when dispatch sends a call, the phone shows a notification titled "Incoming Call" with the call type. Only the crew leader's phone rings (or the solo officer's). The call is still accepted or declined on screen, exactly as before. The ring works on every supported phone except qb-phone and older qs-smartphone versions.

Gigs app on Oxide Phone

If you run Oxide Phone, its Gigs app shows the animal control offices (and whether each has room), the player's current call (offered or in progress, their crew role, and pay so far), and their level. While the player carries an Oxide Phone and the Gigs app is on, shift updates and the call ring arrive there as Gigs notifications instead. The pay summary at clock-out still arrives as a text or mail. You don't need to set anything up beyond running Oxide Phone and this job.

Summary and notification-only setups

If you want a popup end-of-shift summary, set Shift summary (Config.shiftSummary) to Popup summary in /animalcontrol settings (General).

The popup opens on clock-out with either menu style. A shift that ends any other way than a clock-out still sends the summary as a text.

If your server has no phone, or you prefer notifications only, turn off Use phone (Config.usePhone) in /animalcontrol settings (General).

Nothing is sent to the phone then, and the phone doesn't ring. The on-screen notifications still show, and with Config.shiftSummary = 'text' the pay summary becomes a notification showing the net pay.

Stealth detection

Stray and wildlife jobs check whether the player is sneaking (crouched) when approaching an animal. If your server uses a custom crouch script from another resource, the game may not recognize players as sneaking even when they look crouched. In that case, turn off Use crouch detection under Stealth (Config.Stealth.useNativeStealth) in /animalcontrol settings (Animals, Advanced tab) — spook checks then use random chance instead of crouch detection, so the job stays playable.

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:

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

If you already run QBCore, Qbox, 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. The same admin check covers the /animalcontrol settings editor.

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