Configuration Reference

Complete reference for all oxide-animalcontroljob configuration settings, organized by config file.

---

Config File Map

File	Purpose
shared/config.lua	General settings (debug, phone, menu style, slot limits, shift states, job types)
shared/config/job.lua	Crew, payment, complaints, timer, call dispatch settings
shared/config/levels.lua	Progression level definitions
shared/config/locations.lua	Office locations with NPC and vehicle spawn positions, shelter delivery point
shared/config/events.lua	All 55 job events with coordinates, animal models, and behavior flags
shared/config/vehicles.lua	Service vehicle model and health settings
shared/config/animals.lua	Animal model registry, tranquilizer config, stealth detection, per-type behavior, loading settings
shared/config/props.lua	Bait props, deceased bag, progress bar animations
shared/config/visuals.lua	NPC models, blips, reporting NPC behavior, safety zones, waypoints
shared/config/tutorials.lua	Tutorial tooltip definitions
shared/init.lua	Bridge initialization, debug function
server/main.lua	Rate limit configuration

---

General Settings

File: shared/config.lua

Setting	Type	Default	Description
Config.Debug	boolean	false	Enable debug logging with [oxide-animalcontroljob] prefix
Config.usePhone	boolean	true	Send shift emails via phone instead of toast notifications
Config.shiftSummary	string	'text'	Shift summary display mode: 'nui' for popup summary screen, 'text' for email summary
Config.menuStyle	string	'nui'	Dispatcher menu style: 'nui' for Vue shift menu with cinematic camera, 'menu' for Bridge.Menu context menu
Config.MaxSlotsPerLocation	number	3	Maximum concurrent shift slots per office location

---

Job Settings

File: shared/config/job.lua

Crew

Setting	Type	Default	Description
Config.Crew.maxSize	number	2	Maximum crew members (leader + partner)
Config.Crew.inviteTimeout	number	60	Seconds before a crew invite expires
Config.Crew.coopBonusPercent	number	0.15	Bonus percentage applied to jobs completed while in a crew (15%)

Payment

Setting	Type	Default	Description
Config.Payment.basePay	table	See below	Base pay per job type
Config.Payment.distanceBonusPerUnit	number	0.30	Bonus per distance unit from accept location to event
Config.Payment.speedBonusAmount	number	25	Flat bonus for completing a job before the timer expires
Config.Payment.vehicleDestroyFine	number	200	Flat fine when the service truck is destroyed
Config.Payment.streakBonusPerDay	number	10	Bonus added per consecutive daily streak day
Config.Payment.maxStreakDays	number	7	Maximum streak days (caps the streak bonus)
Config.Payment.gasFeePercent	number	0.05	Gas fee as a percentage of gross pay (5%)
Config.Payment.taxPercent	number	0.10	Tax as a percentage of gross pay (10%)

Base Pay by Job Type

Job Type	Base Pay
Aggressive Animal	$85
Stray Capture	$70
Wildlife Removal	$110
Deceased Pickup	$55

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

Complaints

Setting	Type	Default	Description
Config.Complaints.maxComplaints	number	3	Complaints needed to trigger a suspension
Config.Complaints.timeoutMinutes	number	30	Suspension duration in minutes
Config.Complaints.animalEscapePenalty	number	1	Complaints added when an animal escapes
Config.Complaints.animalKillPenalty	number	1	Complaints added when an animal is killed
Config.Complaints.animalKillFine	number	150	Fine deducted from cash when an animal is killed
Config.Complaints.vehicleDestroyPenalty	number	1	Complaints added when the service truck is destroyed
Config.Complaints.deathPenalty	number	1	Complaints added when the player dies on shift
Config.Complaints.decayPerJob	number	1	Complaints removed per successful job completion

Timer

Setting	Type	Default	Description
Config.Timer.baseTime	number	90	Base timer in seconds before distance scaling
Config.Timer.timePerDistanceUnit	number	0.20	Additional seconds per distance unit from player to event
Config.Timer.expiredPenalty	number	0.85	Payment multiplier when completing after the timer expires (15% penalty)

Calls

Setting	Type	Default	Description
Config.Calls.minIntervalSeconds	number	15	Minimum seconds between dispatch calls
Config.Calls.maxIntervalSeconds	number	45	Maximum seconds between dispatch calls
Config.Calls.responseTimeSeconds	number	30	Seconds to accept/decline a call before it counts as missed
Config.Calls.maxMissedCalls	number	3	Missed/declined calls before automatic clock-out

---

Levels

File: shared/config/levels.lua

Each level is defined as an entry in Config.Levels:

Field	Type	Description
title	string	Locale key for the level title
requiredJobs	number	Total jobs needed to reach this level
payMultiplier	number	Multiplier applied to base pay calculation
tipChance	number	Probability of receiving a tip (0.0 - 1.0)
tipRange	table	Min/max tip amount { min, max }

Default Levels

Config.Levels = {
    [1] = { title = 'level.volunteer',        requiredJobs = 0,   payMultiplier = 1.0,  tipChance = 0.10, tipRange = { 5, 15 }  },
    [2] = { title = 'level.handler',          requiredJobs = 15,  payMultiplier = 1.1,  tipChance = 0.15, tipRange = { 5, 20 }  },
    [3] = { title = 'level.senior_handler',   requiredJobs = 40,  payMultiplier = 1.2,  tipChance = 0.25, tipRange = { 10, 30 } },
    [4] = { title = 'level.field_supervisor', requiredJobs = 80,  payMultiplier = 1.35, tipChance = 0.30, tipRange = { 10, 40 } },
    [5] = { title = 'level.chief_officer',    requiredJobs = 150, payMultiplier = 1.5,  tipChance = 0.40, tipRange = { 15, 50 } },
}

---

Locations

File: shared/config/locations.lua

Each location in Config.Locations defines a complete animal control office:

Field	Type	Description
name	string	Locale key for the location name
coords	vector3	Dispatcher NPC position
heading	number	NPC facing direction
vehicleSpawn	vec4	Service truck spawn position and heading
menuCamera	table	Camera settings for NUI menu (coords, heading, rotation, fov)

Shelter Delivery Point

Config.ShelterDeliveryPoint defines the global delivery coordinates for all live animal transport jobs.

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

Default Location

Config.Locations = {
    {
        name = 'location.animal_control_office',
        coords = vector3(-1162.75, -321.83, 37.61),
        heading = 172.06,
        vehicleSpawn = vec4(-1181.48, -340.36, 37.29, 339.7),
        menuCamera = {
            coords = vector3(-1172.27, -334.03, 42.44),
            heading = 339.69,
            rotation = vector3(0.00, 0.00, 0.00),
            fov = 50.0,
        },
    },
}

---

Events

File: shared/config/events.lua

Each event in Config.Events defines an animal report:

Field	Type	Description
type	string	Job type constant (JobType.AGGRESSIVE_ANIMAL, JobType.STRAY_CAPTURE, JobType.WILDLIFE_REMOVAL, JobType.DECEASED_PICKUP)
label	string	Locale key for the event label
animalModel	string	GTA animal model name
coords	vec4	Spawn position and heading for the animal
reportingNpc	boolean	Whether to spawn a reporting civilian NPC
requiresDelivery	boolean	Whether the animal must be delivered to the shelter
animalWaypoints	table	(Wildlife removal only) Array of vector3 patrol waypoints

Event Count by Type

Job Type	Events
Aggressive Animal	13
Stray Capture	15
Wildlife Removal	5
Deceased Pickup	22

Debug Override

Set Config.DebugForceJobType to a JobType constant to restrict dispatch to a single job type for testing. Set to nil for normal operation.

Config.DebugForceJobType = nil -- Set to JobType.STRAY_CAPTURE to test only strays

---

Vehicle

File: shared/config/vehicles.lua

Setting	Type	Default	Description
Config.Vehicle.model	string	'kennel'	Animal control truck model name (Vapid Kennel addon)
Config.Vehicle.spawnDistance	number	5.0	Distance threshold for spawn area clearing
Config.Vehicle.healthCheckInterval	number	1000	Milliseconds between health checks
Config.Vehicle.destroyedThreshold	number	150	Engine health below which the truck is considered destroyed
Config.Vehicle.damageChargeRate	number	0.50	Dollar charge per health point below damage threshold
Config.Vehicle.damageChargeThreshold	number	950	Body health below which damage charges apply

---

Animals

File: shared/config/animals.lua

Animal Models

Config.Animals maps animal model names to their display name and health values:

Model	Name	Health
a_c_rottweiler	Rottweiler	200
a_c_rottweiler_02	Rottweiler	200
a_c_shepherd	German Shepherd	200
a_c_husky	Husky	200
a_c_retriever	Golden Retriever	200
a_c_poodle	Poodle	100
a_c_pug	Pug	80
a_c_westy	West Highland Terrier	100
a_c_cat_01	Cat	80
a_c_cat_02	Cat	80
a_c_coyote	Coyote	250
a_c_mtlion	Mountain Lion	350
a_c_panther	Panther	400
a_c_deer	Deer	200

Tranquilizer

Setting	Type	Default	Description
Config.Tranquilizer.weaponHash	string	'WEAPON_G2'	Weapon hash for the tranquilizer dart gun
Config.Tranquilizer.ammoPerCall	number	5	Darts provided per dispatch call
Config.Tranquilizer.sedationDuration	number	30000	Milliseconds the animal stays sedated after a hit

Stealth Detection

Setting	Type	Default	Description
Config.Stealth.useNativeStealth	boolean	true	Use GetPedStealthMovement for crouch detection
Config.Stealth.fallbackSpookChance	number	0.35	Chance to spook per check when not using native stealth
Config.Stealth.fallbackSafeChance	number	0.70	Chance to be considered "sneaking" when using fallback mode

Animal Behavior

Per-job-type behavior settings in Config.AnimalBehavior:

Aggressive Animal

Setting	Type	Default	Description
task	string	'combat'	Behavior type
attackPlayerRange	number	10.0	Range at which the animal redirects aggression to the player
escapeRadius	number	80.0	Distance from spawn beyond which the animal is considered escaped
npcScanRadius	number	30.0	Radius to scan for nearby world peds to target
npcFleeRadius	number	20.0	Radius within which world peds flee from the animal

Stray Capture

Setting	Type	Default	Description
task	string	'stray'	Behavior type
wanderRadius	number	15.0	Area the animal wanders in
escapeRadius	number	60.0	Distance from spawn beyond which the animal is considered escaped
fleeRange	number	12.0	Distance at which the animal flees if the player approaches standing
sneakRange	number	5.0	Distance the player can approach while crouching without spooking
spookChance	number	0.4	40% chance to spook if the player approaches standing
spookFleeDistance	number	20.0	How far the animal runs when spooked
returnToBaitDelay	number	8000	Milliseconds before a spooked animal returns to bait
baitApproachDelay	number	5000	Milliseconds after player leaves before animal approaches bait
captureRange	number	2.5	Distance required to calm/capture the animal

Wildlife Removal

Setting	Type	Default	Description
task	string	'patrol'	Behavior type
spotRange	number	25.0	Distance at which the animal spots a standing player
sneakRange	number	12.0	Distance a crouching player can approach
panicRange	number	5.0	Distance that spooks regardless of crouch state
wanderAtPointRadius	number	8.0	Wander radius at each waypoint
wanderAtPointTime	table	{ 5000, 10000 }	Min/max milliseconds to wander before moving to next waypoint
escapeRadius	number	100.0	Distance from spawn beyond which the animal is considered escaped
npcFleeRadius	number	25.0	Radius within which world peds flee from the wildlife

Deceased Pickup

Setting	Type	Default	Description
task	string	'dead'	Behavior type (ragdoll/dead state)

Animal Loading

Setting	Type	Default	Description
Config.AnimalLoading.loadDuration	number	5000	Progress bar duration for loading animal into truck (ms)
Config.AnimalLoading.unloadDuration	number	4000	Progress bar duration for unloading at shelter (ms)
Config.AnimalLoading.loadRange	number	3.0	Max distance from animal to begin loading
Config.AnimalLoading.shelterRange	number	5.0	Max distance from shelter point to unload
Config.AnimalLoading.vehicleAttachOffset	vec3	(0.0, -1.5, 0.5)	Offset inside vehicle cargo area for attached animal
Config.AnimalLoading.vehicleAttachRotation	vec3	(0.0, 0.0, 0.0)	Rotation for vehicle-attached animal

---

Props

File: shared/config/props.lua

Bait

Setting	Type	Default	Description
Config.Props.bait.model	string	'm25_1_prop_m51_dog_bowl_full'	Bait prop model (dog bowl)
Config.Props.bait.placementRange	number	8.0	Max placement distance from player (meters)
Config.Props.bait.playerLeaveRadius	number	15.0	Player must be this far from bait before the animal approaches

Scent Effect

Setting	Type	Default	Description
Config.Props.bait.scentEffect.dict	string	'core'	Particle effect dictionary
Config.Props.bait.scentEffect.name	string	'exp_grd_bzgas_smoke'	Particle effect name
Config.Props.bait.scentEffect.scale	number	0.2	Particle scale
Config.Props.bait.scentEffect.offset	vec3	(0.0, 0.0, 0.15)	Offset from bait position

Player Attach

Setting	Type	Default	Description
Config.Props.bait.playerAttach.bone	number	28422	Player bone (SKEL_R_Hand)
Config.Props.bait.playerAttach.offset	vec3	(0.01, -0.1, -0.2)	Attachment offset
Config.Props.bait.playerAttach.rotation	vec3	(0.0, 0.0, 0.0)	Attachment rotation
Config.Props.bait.playerAttach.animDict	string	'anim@heists@box_carry@'	Carry animation dictionary
Config.Props.bait.playerAttach.animName	string	'idle'	Carry animation clip

Deceased Bag

Setting	Type	Default	Description
Config.DeceasedBag.model	string	'm25_2_prop_m52_binbag_01a'	Body bag prop model (bin bag)
Config.DeceasedBag.pickupDuration	number	1500	Remains collection duration (ms)
Config.DeceasedBag.loadDuration	number	4000	Loading into truck duration (ms)

Animations

Progress bar animations for different actions:

Animation	Duration	Dict	Clip	Label
Capture	8000ms	mini@repair	fixing_a_player	progress.capturing_animal
Bait Place	3000ms	pickup_object	pickup_low	progress.placing_bait
Load	5000ms	mini@repair	fixing_a_player	progress.loading_animal
Unload	4000ms	anim@heists@box_carry@	idle	progress.unloading_animal

---

Visuals

File: shared/config/visuals.lua

NPC and Blip Settings

Setting	Type	Default	Description
Config.NpcModel	string	's_m_m_doctor_01'	Ped model for the dispatcher NPC
Config.NpcScenario	string	'WORLD_HUMAN_CLIPBOARD'	Ambient scenario the NPC performs
Config.Blip.sprite	number	273	Map blip sprite ID
Config.Blip.color	number	2	Map blip color
Config.Blip.scale	number	0.8	Map blip scale
Config.Blip.label	string	'blip.animal_control'	Locale key for blip label
Config.EventBlip.sprite	number	463	Blip sprite for job event locations
Config.EventBlip.color	number	1	Event blip color
Config.EventBlip.scale	number	1.2	Event blip scale
Config.DeliveryBlip.sprite	number	141	Blip sprite for shelter delivery point
Config.DeliveryBlip.color	number	2	Delivery blip color
Config.DeliveryBlip.scale	number	1.0	Delivery blip scale

Reporting NPC Behavior

Setting	Type	Default	Description
Config.ReportingNPC.standOffset	vec3	(3.0, 0.0, 0.0)	Offset from animal for NPC standing position
Config.ReportingNPC.animationDistance	number	40.0	Distance threshold for animation vs ambient scenario
Config.ReportingNPC.farScenario	string	'WORLD_HUMAN_STAND_MOBILE'	Ambient scenario when player is far away

Safety Zone

Setting	Type	Default	Description
Config.SafetyZone.enabled	boolean	true	Enable traffic safety zones around animal scenes
Config.SafetyZone.scenarioBlockRadius	number	15.0	Radius to block ambient ped scenarios
Config.SafetyZone.clearVehiclesRadius	number	8.0	Radius to clear parked vehicles on job start

Speed Zone Tiers

Tier	Radius	Speed
Inner	15m	8.0
Outer	30m	20.0

Waypoints

Setting	Type	Default	Description
Config.Waypoints.heightOffset	number	5.0	Height above ground for waypoint marker
Config.Waypoints.scaleMin	number	0.5	Minimum scale at far distance
Config.Waypoints.scaleMax	number	1.0	Maximum scale at near distance
Config.Waypoints.scaleNearDist	number	30.0	Distance at which maximum scale is used
Config.Waypoints.scaleFarDist	number	300.0	Distance at which minimum scale is used

---

Tutorials

File: shared/config/tutorials.lua

17 contextual tutorial tooltips guide new players. Each entry defines an icon, title, body text, screen position, and auto-dismiss duration. Tutorials persist via KVP storage and are shown once per topic.

Tutorial Keys

Key	Trigger
first_clockin	First time clocking in
first_incoming_call	First dispatch call received
first_call_decline	First declined or missed call
first_aggressive_job	First aggressive animal job
first_stray_job	First stray capture job
first_wildlife_job	First wildlife removal job
first_deceased_job	First deceased pickup job
first_tranq_hit	First successful tranquilizer hit
first_bait_placed	First bait placement
first_animal_loaded	First animal loaded into truck
first_shelter_delivery	First shelter delivery
first_timer_expired	First late job finish
first_vehicle_damage	First vehicle destruction
first_job_complete	First job completed
first_crew	First crew formation
first_level_up	First level up

---

Enums

ShiftState

Value	Constant	Description
'idle'	ShiftState.IDLE	Not on shift
'waiting'	ShiftState.WAITING	On shift, waiting for dispatch
'on_call'	ShiftState.ON_CALL	Call accepted, driving to scene
'working'	ShiftState.WORKING	Handling the animal

JobType

Value	Constant	Description
'aggressive_animal'	JobType.AGGRESSIVE_ANIMAL	Aggressive animal combat/tranquilize job
'stray_capture'	JobType.STRAY_CAPTURE	Stray animal bait and capture job
'wildlife_removal'	JobType.WILDLIFE_REMOVAL	Wildlife patrol and tranquilize job
'deceased_pickup'	JobType.DECEASED_PICKUP	Deceased animal remains collection job

---

Rate Limits

File: server/main.lua

Server-side rate limiting prevents action spam. Each action has a cooldown period in milliseconds:

Action	Cooldown (ms)	Description
clockIn	2000	Clocking in to a shift
clockOut	2000	Clocking out of a shift
acceptCall	2000	Accepting a dispatch call
rejectCall	2000	Rejecting a dispatch call
completeJob	5000	Completing a service job
crewInvite	5000	Sending a crew invite
respondToInvite	2000	Accepting/declining a crew invite
propSync	500	Prop state sync to crew partner
animalSync	1000	Animal state sync to crew partner
updateAnimal	5000	Animal network ID update
updateReportingNpc	5000	Reporting NPC network ID update
updateVehicle	2000	Service truck network ID update
vehicleDestroyed	10000	Vehicle destroyed event
animalEscaped	5000	Animal escaped event
animalKilled	10000	Animal killed event

---

Next Steps

• Features — Understand all features and mechanics
• Installation — Set up the resource
• Admin Tools — Admin commands
• Troubleshooting — Common issues and solutions