Configuration Reference

Reference for the current oxide-animalcontroljob config layout.

How Settings Work

Settings are edited in-game with the /animalcontrol settings command (admins only). Changes save to your database and apply instantly — no restart needed.

The config files in the shared/ folder are factory defaults. The first time the resource starts, every value is imported from the files into the database; from then on, the database is the source of truth and editing a file does not change a setting that is already stored, even after a restart. Only brand-new settings added by a future update are imported from the files automatically.

The job still reads the files as its factory defaults at every start, and Reset to default on a setting in /animalcontrol settings replaces the stored value with that default. So a file edit takes effect only after a restart and pressing Reset to default on that setting.

This applies to everything — including office locations, the shelter delivery point, and the event list. Once the resource has started even once, change settings on a running install with /animalcontrol settings.

Three settings are never copied into the database, so they are always read from the files: Config.UseHudAccent in shared/config.lua, and Config.ModelHints and Config.SettingsCommand in shared/config/models.lua, which only set the wording of missing-model warnings.

The tables below document every setting and its factory default.

Config File Map

General Settings

File: shared/config.lua

See Phone Integration for the phone messages the job sends and which phones get texts or mail.

Enums

ShiftState

• idle
• waiting
• on_call
• working

JobType

• aggressive_animal
• stray_capture
• wildlife_removal
• deceased_pickup

Job Settings

File: shared/config/job.lua

Crew

Payment

Base pay by job type

Config.Payment.basePay = {
    [JobType.AGGRESSIVE_ANIMAL] = 85,
    [JobType.STRAY_CAPTURE]     = 70,
    [JobType.WILDLIFE_REMOVAL]  = 110,
    [JobType.DECEASED_PICKUP]   = 55,
}

Complaints

Timer

Current timer formula:

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

Calls

The cancel cooldown is a floor, not an extra delay on top: after a cancel, the next call arrives once both the normal 15–45 second gap and the cooldown have passed. Raise it if you want cancelling a call to cost the player some time; set it to 0 if you'd rather they get back to work immediately. See Cancelling a Call in the feature guide for what cancelling does.

Levels

File: shared/config/levels.lua

Each level entry defines:

• title
• requiredJobs
• payMultiplier
• tipChance
• tipRange

Default progression is 5 levels from Volunteer through Chief Officer.

Locations

File: shared/config/locations.lua

Shelter delivery point

Config.ShelterDeliveryPoint = vector3(-1139.70, -319.82, 37.67)

This is used for all live animal transport jobs that require shelter delivery.

Office fields

Config.Locations is the list of animal control offices. The resource ships with 1, but each entry is a complete, independent office — its own dispatcher NPC, map blip, truck spawn, and worker slots.

Each entry contains:

Adding a second office

Config.Locations is database-managed like every other setting (see How Settings Work), so on a running install you add and edit offices in-game with /animalcontrol settings (admins only), under Locations & Events → Offices, not by hand-editing the file. Place in world on the clerk spot and the truck spawn lets you set each one by standing where you want it, instead of typing coordinates. Changes save to the database and apply live.

The in-game builder (/animalcontrolbuilder) can also capture the coordinates for a new office — its dispatcher spot, heading, truck spawn and menu camera — see the Admin Guide. Use those coordinates when you add the office through /animalcontrol settings. The menu has no fields for the menu camera (it keeps an existing office's camera untouched), so an office added there opens the shift menu without the camera move.

Each office you add appears on its own, automatically: its dispatcher NPC spawns, its map blip is drawn, and it gets its own set of worker slots (Config.MaxSlotsPerLocation, 3 by default — so two offices means six workers total, three at each).

A shift belongs to the office the player clocked in at: that's where their truck spawns and which office's slot they take up.

You can edit, reorder or delete offices while officers are on shift. A shift keeps its office as long as the office keeps either its name or its dispatcher spot, and slot counts carry over. If you delete an office (or change its name and its dispatcher spot in the same save), the shifts there end straight away and are paid, and the players are told "Your office was removed, so your shift has ended."

Calls are shared, not per office. Config.Events (see below) is one global list of animal reports, and dispatch picks from all of it no matter which office a player clocked in at. A second office does not need its own event list and there is no way to tie an event to a specific office. What you may want instead is a few extra entries in Config.Events near the new office, so its workers aren't always driving across the map — pay and the job timer both scale with distance, so far-away calls aren't unfair, just slow.

Drop-offs are shared too: Config.ShelterDeliveryPoint is a single shelter for the whole job, so workers from every office deliver captured animals to the same place.

Events

File: shared/config/events.lua

Each event defines a dispatchable animal report. Current fields are:

The default package contains 54 events across 34 locations. Dispatch groups events by shared scene coordinates to reduce repeated locations back-to-back.

On a running install, add, move or remove events in /animalcontrol settings (under Locations & Events), which also lets you place a scene in the world. Dispatch skips any event with no animal, an invalid call type or a (0, 0, 0) location, and logs a console warning; the settings editor won't save such events.

Event count by type

Vehicle

File: shared/config/vehicles.lua

Animals

File: shared/config/animals.lua

Animal models

Config.Animals maps model names to display name and health values. The default package includes 14 animal models (dogs, cats, coyote, mountain lion, panther, deer).

Each entry has a name (shown to players) and health, and can carry an optional label, shown only in the event builder's picker so near-identical models (for example two Rottweilers) are easy to tell apart.

Tranquilizer

Stealth detection

Animal behavior

Per-job-type behavior settings live in Config.AnimalBehavior. Each job type defines:

• task type
• detection and escape radii
• spook and flee distances
• wander behavior
• NPC reaction radii

Animal loading

Props

File: shared/config/props.lua

This file controls:

• bait prop model and placement range
• bait scent particle effect
• bait player attachment offsets
• deceased bag model and durations
• deceased bag carry animation
• capture, bait placement, load, and unload progress bar animations

Primary props:

• bait (dog bowl)
• deceasedBag (bin bag)

Visuals

File: shared/config/visuals.lua

NPC and blips

• Config.NpcModel
• Config.NpcScenario
• Config.Blip
• Config.EventBlip
• Config.DeliveryBlip

Each office's map blip is labelled with that office's name; Config.Blip sets whether it shows (enabled) and its sprite, colour and scale.

Reporting NPC models

Config.ReportingNpcModels contains 16 possible civilian models for the person who reported the animal incident.

Reporting NPC behavior

Config.ReportingNPC controls:

• stand offset from animal
• animation cycle (beckoning, frightened, hand gestures)
• thank-you animation
• far-away scenario
• animation distance threshold

Safety zones

Config.SafetyZone controls:

• whether safety zones run (enabled)
• the slow-traffic rings around active job scenes (speedZones — each entry sets a radius and a speed)

Waypoints

Config.Waypoints controls marker height, scaling, and render timing.

Outfits

File: shared/config/outfits.lua

Optional on-duty uniform applied through o-link.clothing when the player clocks in and reverted on clock-out / death / logout / disconnect.

The default values are placeholders (drawable = 0, texture = 0) — replace them with valid IDs from your clothing pack before enabling. The previous appearance is snapshotted on apply and restored on revert via o-link.clothing.SetAppearance / o-link.clothing.Revert.

Tutorials

File: shared/config/tutorials.lua

Config.Tutorials contains 16 first-time guidance prompts. Each entry defines:

• icon
• title
• body
• position
• duration

With Oxide HUD, every prompt left at the default position (top right) appears where each player puts the tutorial prompts in the /hud editor. A prompt you give another position keeps that position. first_incoming_call ships at bottom right, clear of the call card, so it keeps that spot.

Model Compatibility

File: shared/config/models.lua

Every model this job spawns is checked before it is requested. A model that doesn't exist on a player's game build (older builds lack newer DLC props) is skipped instantly with a warning naming it, instead of freezing the load. Nothing is substituted automatically — you choose the replacement.

Config.ModelSwaps = {
    { from = 'm25_1_prop_m51_dog_bowl_full', to = 'prop_cs_bowl_01' },
}

On a running install, add rows under Compatibility in /animalcontrol settings.

When a player reports a missing model, the server logs it and notifies online admins once per model, pointing them at /animalcontrol settings. The warnings are capped per player and in total, so one misbehaving client can't flood admins or fill the log. Two models get a clearer message because a missing copy is an install problem, not a game-build one: the dart gun WEAPON_G2 ships in this resource's stream/ folder, and the kennel truck is a separate add-on (see Installation).

Server Rate Limits

The server has built-in protection against spammed actions (clocking in/out, accepting calls, capturing animals, and so on). Each action has a short cooldown so a player — or a cheat tool — can't fire it repeatedly. These limits are hard-coded in server/main.lua and don't need any configuration. If a player triggers one by clicking too fast, they simply get a "slow down" message.

Next Steps