> For the complete documentation index, see [llms.txt](https://docs.cuxial.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cuxial.com/scripts/core/cuxial-garages/configuration.md). # Configuration Every option of Cuxial Garages explained: main config, keys, impound, rentals, vehicle cleanup and markers. The options are split in six files: `shared/config.lua` for the core, and one file per system in `data/`. Garages, depots, job fleets and rental points are not in any file: they are created in game from the [admin panel](/scripts/core/cuxial-garages/commands.md#admin-panel). Restart the resource after changing a file. | File | Covers | | ------------------- | -------------------------------------------------- | | `shared/config.lua` | Permissions, payments, transfers, blips, interface | | `data/keys.lua` | Vehicle keys, theft and police alerts | | `data/impound.lua` | Impound jobs, default fee and command | | `data/rental.lua` | Rental contracts, late fees, warnings | | `data/carwipe.lua` | Vehicle cleanup | | `data/zones.lua` | Interaction distances and the marker | ## Main config · `shared/config.lua` ### General | Option | Type | Default | What it does | | ------------------------ | ------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `debug` | boolean | `false` | Prints traces to the console. Also enabled by setting the convar `cuxial_garages_debug` to `1`. | | `admin.permission` | string | `'admin'` | Permission checked through your framework to open the admin panel and use its actions. `/adminkey` also needs the ACE group `group.`. | | `language` | string | `'es'` | Language of the interface: `'es'` or `'en'`. Notifications and prompts follow the convar `ox:locale` instead. | | `accentColor` | string | configurable | Accent colour of the interface. Accepts `RRGGBB` or the short `RGB`, with or without `#`, and the 8-digit `AARRGGBB` form, where the first two digits are ignored. | | `externalGarages` | boolean | `false` | `true` lets another resource open house garages through the `OpenGarage` and `StoreVehicle` exports. Leave it `false` unless you use one: the request comes from the client. | | `fallbackGarage` | string | `''` | Id of a public garage that receives the vehicles whose saved garage no longer exists. `''` = none. | | `normalizeStatesOnStart` | boolean | `false` | `true` sets every vehicle with an unknown state to stored when the resource starts. Impounded vehicles are kept. Useful only on the first start after moving from another garage resource. | | `vehicleState` | table | `OUT = 0`, `STORED = 1`, `IMPOUND = 2` | Values written to the `state` column of the vehicle table. Do not change them. | | `fuelExemptClasses` | table | `[14] = true` | GTA vehicle classes that are always delivered with a full tank. `14` = boats. | ### Blips · `blips` | Option | Type | Default | What it does | | --------- | ------- | ------- | -------------------------------------------------- | | `garages` | boolean | `true` | `false` hides the blips of every garage and depot. | | `rental` | boolean | `true` | `false` hides the blips of the rental points. | The look of each blip comes from two tables: | Option | What it does | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | `categoryBlips` | Sprite and scale by the first category of the access point: `car`, `motorcycle`, `air`, `sea`. Checked first. | | `defaultBlips` | Sprite, colour and scale by garage type: `public`, `house`, `job`, `gang`, `depot`. Used only when the category has no entry in `categoryBlips`. | Each entry accepts `sprite`, `color` and `scale`. A missing `color` is `3`. ### Capacity · `capacity` | Option | Type | Default | What it does | | --------- | ------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `enabled` | boolean | `false` | `false` = every garage is unlimited. `true` applies the limit each garage has in the admin panel; garages with no limit stay unlimited. | The limit is per player: how many vehicles one person can keep in that garage. Vehicles currently outside still count. Staff actions from the admin panel ignore it. ### Payments · `payment` and `recover` | Option | Type | Default | What it does | | --------------------------- | ------- | -------- | -------------------------------------------------------------------------------------------------------- | | `payment.account` | string | `'bank'` | Account charged for transfers, recoveries, impound fees and rentals. Rental deposits are refunded to it. | | `payment.allowCashFallback` | boolean | `true` | `true` charges cash when the account does not cover the amount. `false` rejects the payment. | | `recover.price` | number | `1000` | Price of recovering a vehicle that was left outside. `0` = free. | ### Transfers · `transfer` | Option | Type | Default | What it does | | ------------- | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------- | | `maxDistance` | number | `10.0` | Metres within which another player can receive a vehicle or be asked to pay an impound fee. | | `allowPlayer` | boolean | `true` | `false` disables transferring vehicles to other players on every garage. With `true`, each garage can still turn it off in the panel. | The receiving player gets a prompt and must accept. A vehicle with pending finance cannot be transferred to another player. The price of moving a vehicle between garages is set per garage in the panel. ### Vehicle options | Option | Type | Default | What it does | | ------------------------- | ------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `cinematic.enter` | boolean | `true` | `true` previews the selected vehicle on its parking spot and, when an owned vehicle is taken out, the character walks to it and gets in with a follow camera. `false` delivers the vehicle directly, with no preview. | | `nickname.enabled` | boolean | `true` | `false` disables saving vehicle nicknames. | | `nickname.maxLength` | number | `24` | Maximum characters of a nickname. Do not go above `24`. | | `forceBaseLivery.enabled` | boolean | `false` | `true` forces the base livery on the fleet vehicles of the jobs listed below. | | `forceBaseLivery.jobs` | table | example jobs | Jobs affected, as `jobname = true`. Replace the examples with your own. | ### Integrations | Option | Type | Default | What it does | | ------------------- | ------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- | | `finance.enabled` | boolean | `false` | Shows the pending instalments of financed vehicles and lets the owner pay from the garage. Only active while the resource below is running. | | `finance.resource` | string | `'jg-dealerships'` | Resource that provides the finance data. | | `speakers.enabled` | boolean | `false` | Tells the speaker resource that an owned vehicle was taken out, so it restores its speakers. Only active while the resource below is running. | | `speakers.resource` | string | `'rahe-speakers'` | Resource to notify. | ## Vehicle keys · `data/keys.lua` Each key is an inventory item that carries a plate. Whoever holds it can lock, unlock and start that vehicle. ### General | Option | Type | Default | What it does | | -------------------------- | --------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `enabled` | boolean | `true` | `false` turns the whole key system off: no keys, no lock or engine binds, no theft, no key exports. Use it only if another resource handles keys. | | `item` | string | `'vehiclekeys'` | Inventory item used as the key. | | `lockDistance` | number | `8.0` | Metres from which a vehicle can be locked or unlocked. | | `giveOnTakeout` | boolean | `true` | `true` gives the key when the owner takes the vehicle out of a garage. | | `removeOnStore` | boolean | `true` | `true` removes the key when the vehicle is stored. | | `getKeysWhenEngineRunning` | boolean | `false` | `true` gives the key to whoever gets into the driver seat of a vehicle with the engine running, when that vehicle has no owner. | | `lockState` | number | `2` | GTA door lock state applied when locking. `2` = locked. Any state above `1` counts as locked. | | `immuneVehicles` | string\[] | example model | Models that cannot be searched for keys. | | `noLockVehicles` | string\[] | `{}` | Models that cannot be locked. The lock key always leaves them open. | | `ignoreBicycles` | boolean | `true` | `true` treats bicycles like `noLockVehicles` and keeps them out of the key search. | ### Binds and commands | Option | Type | Default | What it does | | ----------------------- | ------ | ------------ | --------------------------------------------------------------------------------------- | | `keybinds.toggleLocks` | string | `'L'` | Default key to lock or unlock the nearest vehicle. | | `keybinds.toggleEngine` | string | `'G'` | Default key to turn the engine on or off from the driver seat. | | `keybinds.searchKeys` | string | `'H'` | Default key to search for keys in a vehicle you have no key for. | | `commands.giveKey` | string | `'givekey'` | Name of the command that hands your key to another player. `false` removes the command. | | `commands.adminKey` | string | `'adminkey'` | Name of the staff command that creates a key. `false` removes the command. | These keys are only the defaults. Each player can rebind them in the GTA key settings. ### Shared job keys · `sharedKeys` | Option | Type | Default | What it does | | --------- | ------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `enabled` | boolean | `true` | `false` disables shared keys. | | `jobs` | table | example jobs | Per job: `vehicles` is the list of models every member can use without a personal key, and `requireOnduty = true` limits it to members on duty. | The jobs and models in the file are examples. Replace them with your own. ### Theft | Option | Type | Default | What it does | | ------------------------------- | --------- | -------------------- | ----------------------------------------------------------------------------------------------- | | `hotwire.enabled` | boolean | `true` | Lets a player in the driver seat without a key search the vehicle with the search key. | | `hotwire.minTime` / `maxTime` | number | `20000` / `40000` | Shortest and longest duration of the search, in milliseconds. | | `hotwire.chance` | number | `0.50` | Chance, from 0 to 1, that the search starts the engine. `0.0` disables the search. | | `hotwire.keysChance` | number | `0.10` | Chance of also finding the key, on a successful search. Never for a vehicle that has an owner. | | `hotwire.timeBetween` | number | `5000` | Milliseconds before the player can search again. | | `lockpick.normal.item` | string | `'lockpick'` | Item of the basic lockpick. | | `lockpick.normal.breakChance` | number | `0.4` | Chance, from 0 to 1, that the lockpick breaks on each use. | | `lockpick.advanced.item` | string | `'advancedlockpick'` | Item of the advanced lockpick. Its skill check has three steps instead of four. | | `lockpick.advanced.breakChance` | number | `0.0` | Chance that the advanced lockpick breaks. | | `carjack.enabled` | boolean | `false` | `true` lets players rob a vehicle driven by an NPC by aiming a weapon at the driver. | | `carjack.time` | number | `7000` | Duration of the robbery, in milliseconds. | | `carjack.cooldown` | number | `10000` | Milliseconds between attempts. | | `carjack.chanceByWeaponGroup` | table | by weapon group | Chance of success, from 0 to 1, for each weapon group. A group that is not listed always fails. | | `carjack.noWeapons` | string\[] | melee and throwables | Weapons that cannot be used for a carjack. | ### Police alerts · `dispatch` | Option | Type | Default | What it does | | ---------------- | ------- | ----------------- | -------------------------------------------------------------------------------------------------------- | | `enabled` | boolean | `true` | `false` sends no alerts. | | `resource` | string | `'cuxial_police'` | Resource that receives the alert. `''` disables it. No alert is sent while that resource is not running. | | `chance` | number | `0.75` | Chance of an alert during the day, from 0 to 1. | | `nightChance` | number | `0.25` | Chance of an alert during the night. | | `nightStartHour` | number | `18` | Hour at which the night starts. Uses the real clock of the server machine, not the in-game time. | | `nightDuration` | number | `6` | Hours the night lasts. | | `cooldown` | number | `10000` | Milliseconds before the same player can trigger another alert. | Alerts are sent on a successful lockpick, a successful search and a successful carjack. `sounds` and `animations` set the sounds, animations and props of the key; they work as delivered. ## Impound · `data/impound.lua` | Option | Type | Default | What it does | | -------------- | --------- | ------------ | --------------------------------------------------------------------------------------------------------------------------- | | `jobs` | string\[] | example jobs | Jobs allowed to impound with the command. They also get access to every depot that has no job list of its own in the panel. | | `defaultPrice` | number | `500` | Fee suggested in the impound form, and the one used when no fee is given. | | `command` | string | `'impound'` | Name of the impound command. | | `maxDistance` | number | `5.0` | Metres within which the command finds the nearest vehicle. | How an impound works: * The officer stands next to the vehicle and uses the command. The form asks for the fee, the reason, the depot and whether the owner can retrieve the vehicle alone. * A vehicle with no owner is simply removed. * An occupied vehicle cannot be impounded. * At the depot, the owner pays the fee and drives away or sends the vehicle to a public garage. If the officer blocked self-retrieval, the owner cannot take it back alone: a job with access to the depot has to release it. * An authorized job can release a vehicle and ask a nearby player to pay. That player gets a prompt and must accept. ## Rentals · `data/rental.lua` Rental points, their catalogue and their prices are created in the admin panel. This file sets the rules shared by all of them. ### General | Option | Type | Default | What it does | | -------------------- | ------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ | | `enabled` | boolean | `true` | `false` turns rentals off. | | `ticketItem` | string | `'rentalticket'` | Inventory item that represents the contract. Using it opens the receipt while the rental is active. | | `giveTicketItem` | boolean | `true` | `false` rents without handing out the item. Contracts are then checked at the rental point. | | `platePrefix` | string | `'RENT'` | Prefix of the plate of rented vehicles, up to 4 characters, followed by 4 digits. | | `maxActivePerPlayer` | number | `2` | Active rentals a player can have at once. `0` = no limit. | | `interactDistance` | number | `8.0` | Metres the server accepts between the player and the point to rent or return. | | `markerDistance` | number | `16.0` | Metres at which the marker appears. | | `openRange` | number | `1.6` | Metres at which a player on foot can open the point. | | `returnRange` | number | `5.0` | Metres at which a player driving a rental can return it. | | `sweepExpression` | string | `'* * * * *'` | How often active contracts are checked, as a cron expression. Every minute by default. A longer interval delays warnings by up to that interval. | | `license.resource` | string | `'cuxial_license'` | Resource that provides licences. While it is not running, offers that require a licence are locked for everyone. | ### Late returns · `overdue`, `decay`, `condition` | Option | Type | Default | What it does | | ------------------------- | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `overdue.graceSeconds` | number | `300` | Seconds after the end of the contract with no late fee. | | `overdue.feePerHour` | number | `250` | Late fee per hour or part of an hour. Taken from the deposit, never more than the deposit. | | `overdue.forfeitAfter` | number | `3600` | Seconds of delay after which the vehicle is removed and the rest of the deposit is lost. | | `decay.enabled` | boolean | `true` | `true` damages the engine of an overdue rental while someone drives it. | | `decay.tickMs` | number | `2000` | Milliseconds between each loss of engine health. | | `decay.stages` | table | 3 stages | Each stage has `after` (seconds since the contract ended), `engineLoss` (engine health lost per tick, out of 1000), `fire = true` to kill the engine and `notify` (locale key of the message shown when the stage starts). | | `condition.minBodyHealth` | number | `700.0` | Body health, out of 1000, below which the vehicle counts as damaged on return. | | `condition.damageFee` | number | `1500` | Amount taken from the deposit for a damaged vehicle. | {% hint style="info" %} If you add a stage with a new `notify` key, add the same key to `locales/en.json` and `locales/es.json`. A stage with no `notify` starts silently. {% endhint %} ### Warnings · `warnings` | Option | Type | Default | What it does | | --------------------- | --------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `enabled` | boolean | `true` | `false` sends no warnings. | | `beforeMinutes` | number\[] | `{ 30, 10, 0 }` | Minutes before the end at which a warning is sent. `0` = when the contract ends. Do not use steps shorter than the interval of `sweepExpression`. | | `allowExtendFromMail` | boolean | `true` | `true` adds a button to the mail that extends the contract by one hour, at the hourly price. | | `sender` | string | configurable | Name shown as the sender of the mail. | Warnings are sent as mail when `lb-phone` is running and the player has a phone equipped. Otherwise they appear as a notification on screen. ### New point defaults · `defaults` and `blips` | Option | Type | Default | What it does | | ------------------- | --------- | -------------------- | ------------------------------------------------------------------------------------------- | | `defaults.presets` | number\[] | `{ 1, 2, 4, 8, 24 }` | Duration buttons, in hours, of a new rental point. | | `defaults.maxHours` | number | `24` | Longest rental of a new point, in hours. | | `defaults.deposit` | number | `2000` | Deposit suggested for a new point. | | `blips` | table | by class | Blip (`sprite`, `color`, `scale`) for each class of point: `ground`, `air`, `sea`, `mixed`. | ## Vehicle cleanup · `data/carwipe.lua` | Option | Type | Default | What it does | | --------------------- | ------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | `enabled` | boolean | `true` | `false` removes the cleanup, its commands and its exports. | | `command` | string | `'carwipe'` | Name of the command that starts a cleanup. | | `cancelCommand` | string | `'cancelwipe'` | Name of the command that cancels it. | | `adminAce` | string | `'group.admin'` | ACE group allowed to use both commands. | | `countdown` | number | `60` | Seconds of warning when the command is used without a number. | | `returnOwnedToGarage` | boolean | `true` | `true` sends abandoned owned vehicles back to their garage. `false` leaves owned vehicles untouched. | | `protectNearPlayers` | number | `30.0` | Owned vehicles with a player within this many metres are not touched. | | `deleteNPCVehicles` | boolean | `true` | `true` removes vehicles with no owner. `false` leaves them. | | `occupiedRadius` | number | `5.0` | Radius, in metres, used by the server pass to treat a vehicle with no owner as in use. | | `auto.enabled` | boolean | `false` | `true` runs the cleanup on a schedule. | | `auto.expression` | string | `'0 */3 * * *'` | Schedule as a cron expression: minute, hour, day, month, weekday. | | `auto.countdown` | number | `120` | Seconds of warning before a scheduled cleanup. | | `texts` | table | countdown texts | Texts shown in the countdown, edited in this file. `urgentThreshold` is the number of seconds from which the counter turns urgent. | | `protectedZones` | table | example zones | Zones where no vehicle is ever removed. Replace the examples with your own. | Each protected zone has a `type` and a `name`: | Type | Fields | | ---------- | ---------------------------- | | `'sphere'` | `coords`, `radius` | | `'box'` | `coords`, `size`, `rotation` | | `'poly'` | `points`, `minZ`, `maxZ` | {% hint style="info" %} A cleanup treats job fleet vehicles and rentals as vehicles with no owner. To keep them, add the places where they are parked to `protectedZones` or set `deleteNPCVehicles = false`. {% endhint %} ## Interaction and marker · `data/zones.lua` | Option | Type | Default | What it does | | ------------------ | ------ | ---------------------------- | ----------------------------------------------------------------------------------------------- | | `interactDistance` | number | `8.0` | Metres the server accepts between the player and the access point to store, take out or return. | | `markerDistance` | number | `16.0` | Metres at which the marker of a garage appears. | | `openRange` | number | `1.6` | Metres at which a player on foot can open the garage. | | `storeRange` | number | `5.0` | Metres at which a driver can store or return the vehicle. | | `occupiedRadius` | number | `2.5` | Radius used to decide that a parking spot is taken. | | `marker.textures` | table | by type | Texture of the marker for each type of point: `public`, `depot`, `job`, `rental`. | | `marker.default` | string | `'garage'` | Texture for the types that are not listed. | | `marker.size` | table | `0.819` on each axis | Size of the marker. | | `marker.rotation` | table | `x = 90`, `y = 180`, `z = 0` | Rotation of the marker. | | `marker.color` | table | white, `a = 230` | Colour and opacity: `r`, `g`, `b`, `a`. | | `marker.height` | number | `0.0` | Height of the marker above the access point. | | `marker.bounce` | table | enabled | Up and down movement: `enabled`, `amplitude`, `speed`. | | `marker.fallback` | table | blue arrow | Plain marker drawn when the texture file cannot be loaded. | ## Common changes ### Charge cash only {% code title="shared/config.lua" %} ```lua payment = { account = 'cash', allowCashFallback = false, }, ``` {% endcode %} ### Limit vehicles per garage Enable the option, then set the number on each garage in the admin panel. {% code title="shared/config.lua" %} ```lua capacity = { enabled = true, }, ``` {% endcode %} ### Let police and mechanics impound {% code title="data/impound.lua" %} ```lua jobs = { 'police', 'mechanic' }, ``` {% endcode %} ### Share keys of a job fleet {% code title="data/keys.lua" %} ```lua sharedKeys = { enabled = true, jobs = { police = { requireOnduty = true, vehicles = { 'police', 'police2' } }, }, }, ``` {% endcode %} ### Run a cleanup every day at 4 am {% code title="data/carwipe.lua" %} ```lua auto = { enabled = true, expression = '0 4 * * *', countdown = 120, }, ``` {% endcode %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.cuxial.com/scripts/core/cuxial-garages/configuration.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.