Feature Guide

Overview of the current oxide-animalcontroljob gameplay flow and systems.

Shift Flow

Players manage the job from the dispatcher NPC at the animal control office using the configured o-link target integration.

Menu modes

Config.menuStyle supports:

• 'nui': the full visual menu with a cinematic camera view of the office, a progression card, and crew portraits
• 'menu': a simple context menu (through olink.menu) for servers that want a lighter interface

Both modes support:

• clocking in and out
• viewing progression and complaint state
• inviting a crew partner
• responding to pending crew invites

Shift states

• IDLE
• WAITING
• ON_CALL
• WORKING

Normal flow is:

IDLE -> WAITING -> ON_CALL -> WORKING -> WAITING

Slot limits

Each office location has a configurable maximum number of concurrent shift slots (default: 3). If all slots are full, new players cannot clock in at that location.

Dispatch System

After clock-in, dispatch waits a random amount of time between Config.Calls.minIntervalSeconds and Config.Calls.maxIntervalSeconds, then sends an incoming animal report.

Current call behavior

• accept with E
• decline with Backspace
• response window controlled by Config.Calls.responseTimeSeconds
• missed and declined calls both count toward the same cap
• hitting Config.Calls.maxMissedCalls automatically ends the shift (missed calls don't add complaints)

The incoming call pop-up shows the animal, the street, and an icon for the call type.

Phone ring for incoming calls

When Config.usePhone = true, the player's phone also rings for each new call: a phone notification titled "Incoming Call" with the call type (for example "Stray Capture"). In a crew, only the leader's phone rings; the partner still sees the incoming call pop-up on screen. The call is still accepted or declined on screen with E or Backspace, exactly as above — not on the phone.

The ring needs o-link 1.11.0 or newer and a phone that supports notifications: every supported phone except qb-phone and older qs-smartphone versions. With an older o-link, nothing extra happens and the call works as before. See Phone Integration.

Event rotation

The resource tracks used events during a shift and groups scenes by shared coordinates to reduce immediate repetition. Once all events have been used, the pool resets. Events with no animal, an invalid call type or a (0, 0, 0) location are skipped.

The server checks every step of a call — darting, capturing, loading and delivery. A call completes only once the animal is loaded and the truck is at the drop-off.

Cancelling a Call

A player who already accepted a call can back out of it without ending their shift. This is the escape hatch for a scene that went wrong — an animal that ran somewhere unreachable, a truck parked in a bad spot, or a player who just needs to stop working that call.

Note the difference from declining: a call that is still ringing can be declined (and that counts as a miss). This is for the call the player has already accepted and is working on.

There are two ways to cancel:

• the Cancel Current Task button in the shift menu — it only appears while a call is actually in progress
• the Cancel Current Task option on the animal control truck through the interaction eye

Both ask for confirmation first, so nobody cancels by mistake.

When a call is cancelled:

• the scene clears for everyone in the crew — the animal, the civilian who reported it, any bait that was placed, and any body bag being carried all disappear
• the truck stays where it is and the player stays clocked in, back to waiting for the next call
• that call is forfeited and pays nothing, but every job already finished still pays out normally at clock-out
• there is no fine, no complaint, and it does not count as a missed call
• dispatch holds the next call back for a cooldown — 60 seconds by default (Config.Calls.cancelCooldownSeconds)

In a crew, only the leader can cancel — the same player who accepts and declines calls. A crew member who tries gets the message "Only the crew leader can cancel the task". A member who wants out of the shift entirely just clocks out as before and still gets their share of the pay.

Job Types

There are 4 job types.

Aggressive Animal

• drive to the reported location where a reporting NPC is being attacked
• use the tranquilizer dart gun to sedate the animal
• the animal becomes ragdolled for 30 seconds
• bring your truck close and interact to load the sedated animal
• drive to the shelter delivery point and unload

The animal attacks the reporting NPC, then redirects aggression to the player within the configured attack range. Nearby world peds flee from the animal.

Stray Capture

• take bait from the truck via the target interaction
• place the bait near the animal using the ghost preview system
• move away from the bait (at least 15m) and wait for the animal to approach
• once the animal is eating, sneak up while crouching to avoid spooking it
• get within capture range and interact to calm the animal
• load the calmed animal into the truck and deliver to the shelter

The animal wanders within its spawn radius. If the player approaches too quickly while standing, there is a configurable chance to spook the animal, causing it to flee before eventually returning.

Wildlife Removal

• drive to the reported location with no reporting NPC
• the animal patrols between predefined waypoints, wandering at each point
• stay crouched and approach carefully to avoid spooking it
• use the tranquilizer dart gun to sedate the animal
• load the sedated animal into the truck and deliver to the shelter

The animal follows a waypoint patrol route with detection ranges for standing vs crouching players. Nearby world peds flee within the configured radius.

Deceased Pickup

• drive to the reported location with no reporting NPC
• the animal is lying on the ground in a dead state
• interact to collect the remains into a body bag
• carry the body bag back to the truck and load it

No tranquilization or shelter delivery is required.

Tranquilizer System

A tranquilizer dart gun is provided through the inventory system when a player clocks in.

Current behavior

1. On clock-in, the server gives the player a weapon_g2 item through o-link.inventory, along with one free pack of darts (Config.Tranquilizer.ammoPerCall, default 5). The darts are the dedicated ammo_dart item — one item loads one dart — and the gun uses its own dart ammo pool, not pistol ammo.
2. Extra dart packs can be bought during the shift from the shift menu — the cost is reserved from earned shift pay before the darts are issued; insufficient earnings refuse the purchase.
3. Dart damage is restricted to only affect the active job's animal while on shift. The bundled gun does no health damage.
4. A successful hit sedates the animal for Config.Tranquilizer.sedationDuration (default 30 seconds). A sedated animal keeps its health, so a small knock won't kill it.
5. If the animal wakes up before it is loaded, it must be tranquilized again.
6. When the shift ends, for any reason, issued equipment and remaining job dart items are reclaimed; existing personal pistol ammunition is preserved.

Players can't clock in while dead or downed, or while the dart gun or dart item is missing from your inventory's item list — they get an equipment error instead of half a kit.

Damage restriction

While a player is on shift, the server checks every shot fired from the dart gun. Darts only affect the animal from the player's current call — they cannot hurt anything or anyone else.

PvP tranq effect

Config.Tranquilizer.playerEffects defaults to false. When enabled, an officer on shift can briefly tranquilize another player: five seconds of ragdoll followed by three seconds of stumbling and screen effects. Off-shift shots do not trigger this effect.

Bait System

Bait is used in stray capture jobs to lure frightened animals.

Current behavior

1. Take bait from the truck via target interaction.
2. The bait attaches to the player's hand with a carry animation.
3. A ghost preview appears where the player aims with a max range of 8m.
4. Press E to place the bait, or Backspace to cancel.
5. A scent particle effect plays at the bait location.
6. The player must move at least 15m away before the animal approaches.
7. After a delay, the animal moves toward the bait.
8. Once the animal is eating, the player can sneak up to capture range.

Spook mechanics

If the player approaches a stray too quickly while standing, there is a configurable chance to spook the animal. Spooked animals flee before eventually returning to the bait area.

Stealth Detection

The stealth system determines whether a player is sneaking for animal spook checks.

Native mode (default)

When Config.Stealth.useNativeStealth is true, the system uses GetPedStealthMovement to detect whether the player is crouching.

Fallback mode

When Config.Stealth.useNativeStealth is false (for servers with custom crouch systems), spook checks use random chance via Config.Stealth.fallbackSpookChance and Config.Stealth.fallbackSafeChance.

Animal Behavior

Each job type has distinct AI behavior for how the animal interacts with the player and the world.

Animal state machine

All animals follow a unified state machine:

• ALIVE — Active, performing job-type-specific behavior
• SEDATED — Tranquilized and ragdolled (temporary, wakes up after sedation duration)
• CAPTURED — Calmed by player (stray capture only)
• LOADED — Loaded into the truck
• DEAD — Killed or spawned dead (deceased pickup)
• CARRYING — Remains collected into a body bag and being carried to the truck (deceased pickup only)

Escape detection

Each job type has its own escape radius. If the animal moves beyond that distance from its spawn point, it is considered escaped. An escaped animal triggers a complaint and cancels the current job.

Killed animals

If the call's animal is killed, the call ends with the kill fine (Config.Complaints.animalKillFine, default $150) and a complaint.

World NPC reactions

Aggressive animals and wildlife events cause nearby world NPCs to flee within their configured radius.

Animal Loading and Delivery

After sedating or calming an animal, it must be loaded into the truck and, for most jobs, delivered to the shelter.

Loading

Bring the truck within range of the animal and interact to begin loading. The animal attaches to the cargo area at the configured offset.

Shelter delivery

For jobs with requiresDelivery = true, a delivery blip and waypoint appear. Drive to the shelter and interact to unload the animal.

Deceased remains

For deceased pickup jobs, interact with the animal to collect remains into a body bag, then carry it back to the truck and load it. Cancelling the body-bag load keeps the bag in your hands.

Loading and unloading times come from Config.LoadAnimation.duration and Config.UnloadAnimation.duration.

Mission Timers

Timers are distance-based, not fixed per event.

timeLimit = Config.Timer.baseTime + math.floor(distance * Config.Timer.timePerDistanceUnit)

If the timer expires:

• the job can still be completed
• the speed bonus is lost
• Config.Timer.expiredPenalty is applied to the pay calculation

Progression

Progression is stored in the unified job_progression table under job = 'animalcontrol'.

Level rewards

Levels increase:

• pay multiplier
• tip chance
• tip range

Default progression is 5 levels from Volunteer through Chief Officer.

Daily streaks

Completing at least one job on consecutive real-world days increases daily_streak up to the configured cap.

Complaints and timeout

Complaints are added for:

• animal escape
• animal killed
• vehicle destruction
• death or downed state during shift

Dying on shift ends the shift: earned pay is paid out and the death complaint is filed. On QBCore and Qbox, being downed counts too.

Complaints decay as jobs are completed. Reaching the configured limit ends the current shift, settles earned pay, reclaims job equipment, and starts the configured temporary timeout. Clock-out remains available while an officer is still on shift.

Payment

Per-job payment includes:

• base pay by job type
• distance bonus
• on-time speed bonus
• level multiplier
• late-job penalty multiplier
• streak bonus
• random tip

Per-job formula:

subtotal = floor((basePay + distanceBonus + speedBonus) * levelMultiplier * timerMultiplier)
total = subtotal + streakBonus + tip

A crew that reaches the scene faster than any vehicle could drive there (Config.Calls.maxTravelSpeed, 50 metres per second in a straight line) gets neither the distance bonus nor the speed bonus for that call. Driving there never triggers it.

Shift payout is settled when the shift ends, including forced endings such as hospitalization, a disconnect or the resource restarting — players never lose pay they already earned.

The following are deducted from the shift payout:

• vehicle damage charge (if the truck comes back banged up)
• ammo resupply costs (extra dart packs bought during the shift)
• gas fee
• taxes

Fines work differently: the vehicle destruction fine and the animal kill fine are charged on the spot, taken from the account set in Config.Payment.fineAccount (cash by default) — not from the shift payout.

Shift payouts are deposited to the account set in Config.Payment.payoutAccount (bank by default) through o-link.money.

A player who disconnects, logs out or switches character on shift isn't paid at that moment, because their character may already be gone. Their net pay is kept in the database and paid about 3 seconds after that character next loads in, with the notification "You were paid $X still owed from your last animal control shift." It is paid once, even if the server restarts in between.

Crew System

Crews support two players. Set Config.Crew.maxSize = 1 to allow only solo shifts. Invitations expire after the configured timeout, and an unanswered invite doesn't block that player from being invited again once it expires.

Crew behavior

• the leader must already be on shift
• the invite target must be nearby
• the target cannot already be in a crew or active shift
• the leader is the only member who accepts or rejects dispatch calls
• both members can participate in the scene and receive payout breakdowns
• each member's pay for a call uses their own level multiplier, tip chance and streak bonus, so a new officer working with a veteran earns at their own level
• each call adds Config.Crew.coopBonusPercent (15%) of each member's own pay as their co-op bonus

Crew continuity

If one member clocks out, disconnects, logs out or switches character, or goes down, their shift ends. The remaining member carries on with the truck, the call and the animal. When a member clocks out mid-call, the partner keeps the scene — the animal, bait and reporting civilian, including remains or bait the other officer was holding.

The shift menu shows the crew partner's name.

Reporting NPC

For aggressive animal and stray capture calls, a random civilian NPC spawns near the animal to represent the person who called in the report. Any event can include one — set reportingNpc = true on the event. The default wildlife and deceased events don't use one.

The NPC cycles through all of its contextual animations (beckoning, frightened, hand gestures) when the player is within range, switches to an ambient scenario when far away, and plays a thank-you animation on job completion.

A pool of 16 civilian ped models is used, with a random selection per job.

Vehicle System

An animal control truck spawns at the office vehicle spawn point when a player clocks in.

Current behavior:

• license plate set to ANIMAL
• vehicle keys provided through o-link
• truck health is watched constantly (configurable check interval)
• target interactions for taking bait, loading animals, and loading remains
• destroying the truck adds a complaint and fine, clears the active call for both crew members, and ends their shifts; officers can return to the office for a new shift
• a truck that disappears (for example, removed by a cleanup script) ends the shift without the destruction fine or complaint

Vehicle damage charges

At clock-out, if the truck's body health is below the configured threshold, a damage charge is calculated and deducted from the shift payout.

Crew vehicle sharing

When a crew is formed, the partner receives a reference to the leader's truck. If the leader clocks out, ownership transfers to the partner.

Safety Zones

Around each animal scene, two invisible speed zones slow down passing NPC traffic so cars don't barrel through and disrupt the job.

Current defaults:

• inner zone: 15m radius (traffic slows to a crawl)
• outer zone: 30m radius (traffic slows down)

Both zones are removed automatically when the job ends. Radii and speeds are set under Safety zone (Config.SafetyZone) in /animalcontrol settings (Scene & Effects, Advanced tab), and its Enabled switch turns the whole system off.

HUD Overlay

A NUI panel appears during active jobs showing:

• mission timer countdown with late indicator
• job type label
• context-sensitive hint text synced to the crew partner when applicable

With Oxide HUD

On a server running Oxide HUD, players can move this panel, the incoming call pop-up and the tutorial prompts in the /hud editor, or switch them off. They hide with the HUD (pause menu, character select, death), and the tutorial prompts use the server's accent colour (see Config.UseHudAccent in the Configuration Reference). A player who switches the call pop-up off still hears the call come in and can still answer it with E or Backspace, but no longer sees what the call is. The HUD also hides while an admin is in the builder's placement editor. This needs o-link 1.12.1 or newer. Without Oxide HUD everything stays where it is.

Waypoints

A floating 3D waypoint marker appears above the current destination.

It supports:

• configurable height offset
• distance-based scaling
• distance text in meters
• visibility toggling by holding H (players can rebind this in GTA's Settings > Key Bindings > FiveM)

Summary Output

Config.shiftSummary controls how end-of-shift information is shown:

• 'nui': a summary screen on clock-out, with either menu style. When the shift ends any other way (going down, too many missed calls, the complaint limit, a destroyed truck, a removed office, a restart), the player gets the summary as with 'text' instead
• 'text': the full pay summary is sent to the player's phone when Config.usePhone = true (see Phone Integration); otherwise a notification shows the net pay

Uniforms (Optional)

If Config.uniformsEnabled = true, the player's appearance is swapped to the configured animal-control outfit on clock-in and reverted on clock-out, death, logout, or disconnect. The previous appearance is snapshotted and restored through o-link.clothing.

The default outfits are placeholders — replace the drawable and texture IDs with values from your clothing pack under Male outfit and Female outfit in /animalcontrol settings (Uniforms, Advanced tab) before enabling.

Phone Integration

If Config.usePhone = true (the default), the animal control office sends the player messages on their phone. The sender is "Animal Control - " followed by the office name. The messages are:

• a welcome message when they clock in (a crew partner gets one too when they join the crew)
• a notice when the truck is destroyed, with the repair fine
• an incident report when an animal escapes, and when an animal is killed (with the fine)
• a notice that the shift was cancelled when the player dies or goes down on shift
• the end-of-shift pay summary with the full payment breakdown, when Config.shiftSummary = 'text', and with 'nui' when the shift ends any other way than a clock-out (it is not sent if the player disconnects or logs out)

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:

The phone also rings for each incoming call — see Phone ring for incoming calls.

If Config.usePhone = false, nothing is sent to the phone and the phone doesn't ring. The on-screen notifications for a destroyed truck, an escaped animal and a killed animal still show, and with Config.shiftSummary = 'text' the pay summary becomes a notification showing the net pay.

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 arrive there as Gigs notifications instead of texts, and the incoming call ring arrives there as a Gigs notification too. The pay summary at clock-out never goes to the Gigs app; it always arrives as a text or mail. Nothing needs setting up beyond running Oxide Phone and this job.

Tutorials

The resource includes 16 tutorial prompts covering:

• first clock-in
• incoming calls
• first decline or miss
• each job type
• tranquilizer hit
• bait placement
• animal loading and delivery
• timer expiry
• vehicle destruction
• first completion
• crew formation
• level-up

Players can toggle or reset tutorials with:

• /animalcontroltutorials (or /animalcontrol tutorials)
• /animalcontroltutorialreset (or /animalcontrol tutorialreset)

Next Steps