> ## Documentation Index
> Fetch the complete documentation index at: https://docs.czautoz.co.uk/llms.txt
> Use this file to discover all available pages before exploring further.
# Global Settings
> mod_config.json — server-wide settings affecting all helicopters: cargo modules, repair, toggles, and logging.
Edit `$profile:\CZAutoz_Heli\mod_config.json` to change settings that apply to **all helicopters** on your server.
As of v0.2 the file is organised into clear **sections** — `logging`, `features`, `gameplay`, `repair`, `refuel`, `extraModules` and `admin`. Each setting below is shown by its full path (for example `features.autoHoverEnabled`).
Delete this file and restart to regenerate it with all default values.
These settings are safe to adjust freely — they control gameplay features like cargo, repair, fuel warnings, logging, and server-wide toggles. Unlike the per-helicopter flight physics values, there is no risk of breaking flight behaviour by changing these.
Since **v0.2.3**, a mod update **migrates `mod_config.json` in place** along with every other config — new keys are added, removed keys cleaned up, and all your custom values are kept (originals are still backed up first to `$profile:\CZAutoz_Heli\Backups\v_\`). Only when first moving from v0.2.2-or-earlier onto a v0.2.3+ build might a one-time re-apply be needed.
Editing these settings from the in-game **Admin Panel** applies them **live** (since v0.2.3) — every spawned helicopter and connected player updates instantly, no restart or reconnect. Only **direct edits to the JSON config files** need a server restart, since those are read on startup.
***
## Extra Cargo Modules
Each extra module adds **1,000 inventory slots**. Maximum **10 modules** per helicopter.
| Setting | Helicopter | Max total slots |
| ------------------------ | ---------------- | --------------- |
| `extraModules.md500` | MD500 Civilian | 10,250 |
| `extraModules.mh6` | MH-6 Little Bird | 10,250 |
| `extraModules.sa342m` | SA342M Gazelle | 10,250 |
| `extraModules.uh1h` | UH-1H Iroquois | 10,500 |
| `extraModules.blackhawk` | MH-60L Blackhawk | 10,500 |
| `extraModules.merlin` | AW101 Merlin | 11,000 |
| Setting | What it does | Default |
| ---------------------------- | ------------------------------------------------------------------------ | ------- |
| `features.seatedCargoAccess` | `1` = crew can open extra cargo while seated. `0` = locked while seated. | `1` |
***
## Repair
All repairs require HelicopterRepairKit in hands, engine off, helicopter grounded.
| Setting | What it does | Default |
| ------------------------ | ----------------------------------------------------------------------- | ------- |
| `repair.kitUses` | Number of repairs a kit can perform before going ruined. | `5` |
| `repair.rotorRepairTime` | Hold time in seconds to repair a rotor. | `45` |
| `repair.zoneRepairTime` | Hold time in seconds to repair a body/engine/chassis/fuel zone. | `30` |
| `repair.globalHpPct` | Global HP fraction added per repair (0.10 = +10% global HP per action). | `0.10` |
Zone repair is progressive — one hold repairs one damage level. Full repair of a heavily damaged zone may require multiple holds.
***
## Refuelling
Controls how much fuel each container type adds and how quickly it drains during the refuel action.
### Refuel Amounts
The amount of fuel added is expressed as a fraction of the helicopter's total tank capacity — so the same setting applies consistently regardless of which helicopter is being refuelled.
| Setting | What it does | Default |
| -------------------- | --------------------------------------------------------------------------------------------------------------------- | ------- |
| `refuel.canisterPct` | Fraction of tank added per full `CanisterGasoline` (jerry can). `0.10` = 10% per can, 10 cans to fill any helicopter. | `0.10` |
| `refuel.drumPct` | Fraction of tank added per full `CZAutoz_HeliDrum`. `0.50` = 50% per drum, 2 drums to fill any helicopter from empty. | `0.50` |
| `refuel.bottlePct` | Fraction of tank added per full `Bottle_Base` item (water bottles, glass bottles, etc.). | `0.005` |
| `refuel.defaultPct` | Fraction of tank added per full unrecognised container (catch-all for modded fuel items). | `0.005` |
### Refuel Drain Speed
Controls how fast the container empties during the refuel action. Higher values drain the container faster, reducing the wall-clock time to complete a fill.
| Setting | What it does | Default |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- |
| `refuel.canisterRate` | Drain speed multiplier for `CanisterGasoline`. `1.0` = \~40 s for a full can. `2.0` = \~20 s. | `1.0` |
| `refuel.drumRate` | Drain speed multiplier for `CZAutoz_HeliDrum`. Default `5.0` makes a full drum take the same wall-clock time as a full canister despite holding 5× the fuel. | `5.0` |
| `refuel.bottleRate` | Drain speed multiplier for `Bottle_Base` items. | `1.0` |
| `refuel.defaultRate` | Drain speed multiplier for unrecognised containers (catch-all). | `1.0` |
***
## Thresholds & Toggles
| Setting | What it does | Default |
| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `gameplay.fuelWarnThreshold` | Fuel fraction at which warning beeps begin. `0.20` = starts at 20% remaining. | `0.20` |
| `gameplay.playerCrashDamageMax` | Max HP damage to crew per hard impact (requires `damage.playerCrashDamageEnabled = 1` in the helicopter's config). | `75` |
| `gameplay.engineHoldTime` | Hold duration in seconds for the Start Engine and Stop Engine action circles. | `1.0` |
| `features.rotorBladeShear` | `1` = rotor blades shear off on geometry contact (trees, buildings, terrain). `0` = no shear. | `1` |
| `features.rotorDiscCollision` | `1` = spinning rotor disc has physical collision. `0` = no disc collision. | `1` |
| `features.rotorPlayerKillEnabled` | `1` = players entering a spinning rotor disc are instantly killed. `0` = disabled. | `1` |
| `features.groundFlipRecovery` | `1` = pressing `X` while grounded and inverted flips the helicopter upright. `0` = disabled. | `0` |
| `features.autoHoverEnabled` | `1` = Autohover works normally. `0` = disabled server-wide (`X` key does nothing). | `1` |
| `features.cabinModeEnabled` | `1` = Cabin Mode enabled. `0` = disabled server-wide for all helicopters. **Cabin Mode is being reworked and ships OFF by default as of v0.2.4 — keep it disabled until a future hotfix.** | `0` |
| `features.freeLookAlwaysOn` | `1` = free look is always active for the pilot (no need to hold the key). `0` = default DayZ hold-to-free-look behaviour. | `0` |
| `features.autoShutdownOnExit` | `1` = engine shuts off automatically when the pilot exits their seat while the helicopter is grounded and the engine is running. `0` = disabled. | `0` |
| `features.autoHoverOnExit` | `1` = Autohover automatically engages when the pilot exits their seat while the helicopter is airborne — helicopter holds position until a new pilot boards. `0` = no autohover on exit (helicopter continues on its current trajectory). | `1` |
| `features.doorAction3rdPerson` | `1` = the seated door open/close action also appears in 3rd-person view. `0` = 1st-person only. | `0` |
***
## Admin Access — Roles & Permissions
The `admin` section controls who can use the in-game **Admin Panel** (default key **F10**) and what each role may do. This is easiest to manage from the Admin Panel's **Roles** page in-game — the JSON below is simply what that produces.
| Setting | What it does | Default |
| ----------------------------- | ----------------------------------------------------------------------------------------------------- | ------- |
| `admin.whitelistRetryMinutes` | How often (in minutes) the server re-checks the whitelist if the first check fails. | `15` |
| `admin.entries` | Array of admins. Each entry has a `steamID64`, a `role`, and an optional list of extra `permissions`. | `[]` |
| `admin.roles` | Array of custom roles. Each has a `name` and a list of `permissions`. | `[]` |
```json theme={null}
"admin": {
"whitelistRetryMinutes": 15,
"entries": [
{ "steamID64": "76561198000000000", "role": "owner", "permissions": [] }
],
"roles": [
{ "name": "admin", "permissions": ["heli.list.refuel", "heli.list.delete", "tools.spawn"] }
]
}
```
The built-in **owner** role always has every permission and can never be locked out. Other roles only get the permissions you grant them — actions a role lacks are still visible in the panel but show **"Access denied"** when clicked. The mod-config and per-helicopter pages are never editable by non-owner roles. Manage all of this from the Admin Panel → Roles page.
***
## Logging
| Setting | What it does | Default |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `logging.CZAutoz_logDebug` | `1` = verbose debug output written to `CZAutoz_Heli_debug.log`. Only enable when troubleshooting — do not leave on in production. | `0` |
| `logging.CZAutoz_logActivity` | `1` = all player helicopter events logged to a daily file at `$profile:\CZAutoz_Heli_Activity_YYYY-MM-DD.log`. Each entry includes the player's display name and Steam GUID. **Recommended to enable on all servers.** | `0` |
| `logging.CZAutoz_logPhysics` | `1` = physics/flight diagnostics written to the debug log, for tuning and flight-issue investigation. Leave off in production. | `0` |
### Activity Log Events
The activity log is designed as an **admin tool for investigations, compensation, and dispute resolution**. Every significant player interaction with a helicopter is recorded with a precise timestamp, player display name, and Steam GUID — giving you a complete, chronological picture of exactly what happened, who was involved, and when.
Common admin use cases:
* **Combat logging** — confirm whether a player left a helicopter mid-fight or mid-pursuit
* **Theft and griefing** — identify who took a helicopter, who was flying it, and what was removed from cargo
* **Compensation requests** — verify whether a crash was caused by server-side damage, a rotor shear, or pilot error before compensating
* **Dispute resolution** — cross-reference a player's account of events against the timestamped log
* **Rotor kills** — confirm who was piloting when a player was killed by a rotor disc, including both victim and pilot GUIDs
When `logging.CZAutoz_logActivity = 1`, every event is recorded with a timestamp, the helicopter classname, and the player's display name and Steam GUID where applicable. All seat, engine, and physics events also include the helicopter's **world position** (X/Z coordinates) at the time of the event.
#### Helicopter Presence
| Event | What is logged |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `HELI_SPAWNED` | Fires once on the first server tick for each helicopter — helicopter classname and world position. Covers persisted, mission-spawned, and admin-spawned helicopters |
#### Engine
| Event | What is logged |
| -------------- | -------------------------------------------------- |
| `ENGINE_START` | Player name, GUID, helicopter type, world position |
| `ENGINE_STOP` | Player name, GUID, helicopter type, world position |
#### Seats
| Event | What is logged |
| ---------------- | --------------------------------------------------------------------------------------------------- |
| `PILOT_ENTER` | Player name, GUID, helicopter type, world position |
| `PILOT_EXIT` | Player name, GUID, helicopter type, world position (voluntary exit only) |
| `PILOT_KILLED` | Player name, GUID, helicopter type, world position (body detected in seat with `IsAlive() = false`) |
| `COPILOT_ENTER` | Player name, GUID, helicopter type, world position |
| `COPILOT_EXIT` | Player name, GUID, helicopter type, world position (voluntary exit only) |
| `COPILOT_KILLED` | Player name, GUID, helicopter type, world position |
| `CARGO_ENTER` | Player name, GUID, seat index, helicopter type, world position |
| `CARGO_EXIT` | Player name, GUID, seat index, helicopter type, world position (voluntary exit only) |
| `CARGO_KILLED` | Player name, GUID, seat index, helicopter type, world position |
#### Cabin Mode
| Event | What is logged |
| ------------- | ---------------------------------------------------------- |
| `CABIN_ENTER` | Player name, GUID, origin seat index, helicopter type |
| `CABIN_EXIT` | Player name, GUID, destination seat index, helicopter type |
#### PvP Kill Detection
| Event | What is logged |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CREW_KILLED_BY_PLAYER` | Victim name + GUID, killer name + GUID, kill context (`seat 0`/`seat 1`/`seat 2+`, `cabin walk`, `on deck`, `free walk`), helicopter type, world position. Only fires when the killer is another player — environment and crash deaths are covered by `PILOT_KILLED`, `CARGO_KILLED`, and `CREW_CRASH_DAMAGE` |
#### Combat & Damage
| Event | What is logged |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `CREW_CRASH_DAMAGE` | Fires for each crew member who takes damage in a hard impact — player name, GUID, exact damage value, helicopter type, world position |
| `CRASH` | Pilot name, GUID, impulse value, hit zone, helicopter type, world position |
| `WATER_SLAM` | Pilot name, GUID, impact speed (m/s), helicopter damage, player damage dealt, world position |
| `ROTOR_KILL` | Victim name + GUID, pilot name + GUID, helicopter type |
| `ROTOR_DEAD` | Which rotor (main/tail), pilot name + GUID, helicopter type |
| `ROTOR_SHEAR` | Which rotor (main/tail), pilot name + GUID, helicopter type |
| `FUEL_EMPTY` | Pilot name + GUID, helicopter type |
| `DESTROYED` | Killer name + GUID (or `environment` if not a player), pilot name + GUID, helicopter type, world position |
#### Flight Systems
| Event | What is logged |
| -------------------- | ---------------------------------------------------------------------------------------------- |
| `AUTOPILOT_ON` | Pilot name, GUID, hold altitude (m), helicopter type |
| `AUTOPILOT_OFF` | Pilot name, GUID, helicopter type |
| `AUTOROTATION_ENTER` | Pilot name, GUID, rotor spool value, current descent rate, helicopter type |
| `AUTOROTATION_EXIT` | Pilot name, GUID, helicopter type (fires when engine spools back up and normal flight resumes) |
| `FLIP_RECOVERY` | Player name, GUID, helicopter type (requires `features.groundFlipRecovery = 1`) |
#### Maintenance & Repairs
| Event | What is logged |
| --------------- | ------------------------------------------------------------------------------------------------------ |
| `REFUEL` | Player name, GUID, fuel percentage after fill, helicopter type |
| `ZONE_REPAIR` | Player name, GUID, zone repaired (body/engine/chassis/fuel), helicopter type |
| `ROTOR_REPAIR` | Player name, GUID, which rotor (main/tail), helicopter type |
| `ITEM_ATTACHED` | Item classname, slot name, helicopter type. The acting player cannot be identified at the engine level |
| `ITEM_DETACHED` | Item classname, slot name, helicopter type. The acting player cannot be identified at the engine level |
#### Lights & Controls
| Event | What is logged |
| -------------- | ---------------------------------------------------------------------------------------- |
| `SPOTLIGHT` | Pilot name, GUID, new state (ON/OFF), helicopter type |
| `NAV_LIGHTS` | Pilot name, GUID, new state (ON/OFF), helicopter type |
| `WINDOW` | Player name, GUID, which window (left/right), new state (OPENED/CLOSED), helicopter type |
| `RAMP` | Player name, GUID, new state (opened/closed), helicopter type |
| `LANDING_GEAR` | Player name, GUID, new state (deployed/retracted), helicopter type |
**We strongly recommend enabling activity logging on all servers.** It has no meaningful performance impact and gives you the full picture you need to handle compensation requests, combat log reports, theft disputes, and any helicopter-related staff situation confidently and fairly. Without it, you are relying entirely on player accounts of what happened.
This mod logs all helicopter-specific interactions, but it does not cover general server-wide PvP kills. For complete kill accountability — including who shot who, with what weapon, and when — we recommend also running a dedicated **PvP logging mod** alongside this one. The two logs complement each other: helicopter activity records the context, a PvP logger records the kill chain.
### Whitelist Logs
The mod also generates two dedicated whitelist log files on every server start, regardless of `logging.CZAutoz_logActivity`:
| File | Contents |
| --------------------------------------------- | ----------------------------------------------------------------- |
| `$profile:\CZAutoz_Heli_whitelist_status.log` | Human-readable whitelist check result — overwritten on each start |
| `$profile:\CZAutoz_Heli_whitelist_debug.log` | Detailed whitelist API diagnostics — appended on each check |
See [Common Issues](/getting-started/common-issues#logging--diagnostics) for how to use these when troubleshooting.