# YALootBoxes

A DayZ server mod that spawns lockable lootboxes at config-defined locations.
Players need a specific held item to attempt opening a box via a hold-to-open
action: success unlocks and fills the box; failure rolls one random negative
effect. Locked boxes despawn/respawn on a timer so the loot stays fresh; opened
boxes despawn a configurable number of minutes after being unlocked.

All settings live in four JSON files auto-generated on first run at
`$profile:YALootBoxes\`:

| File | Purpose |
|------|---------|
| `main_config.json`     | Global tunables (limits, timers, logging) |
| `box_types.json`       | Box definitions: required items, open chance, fail effects |
| `loot_lists.json`      | Per-type loot tables |
| `spawn_locations.json` | Named world positions and which box type spawns there |

> Edit the copies under `$profile:YALootBoxes\`, **not** the ones inside the PBO.
> Reference/default versions of all four are in `configfiles.readme`.

## Install & first run

1. Pack the mod into `@YALootBoxes\addons` and add `@YALootBoxes` to the
   server's `-mod=` list (after any frameworks it uses).
2. Start the server. On first run the mod **auto-generates all four JSON files
   with working defaults** at `$profile:YALootBoxes\`, so boxes spawn
   immediately — no manual config needed.
3. **No `init.c` edit is required.** The mod self-starts via a modded
   `MissionServer` (`scripts/5_Mission/YALootBoxes_MissionServer.c`).
4. Stop the server, edit the generated JSONs to taste, restart.

Confirm it loaded by looking for these lines in the server `.RPT`:

```
[YALootBoxes][INFO] Config loaded: 3 box types, 7 spawn locations, 3 loot lists. Log level = 3.
[YALootBoxes][INFO] Manager initialized. N lootboxes spawned.
```

## Logging

Logging verbosity is controlled by a single **numeric** field in `main_config.json`:

```json
{
  "DebugLogLevel": 3
}
```

The value is read once at load into `YALB_ConfigLoader.ActiveLogLevel` and
clamped to 0–5, so every runtime log call is a cheap integer comparison.

### Levels

Levels are ordered. A message is printed only when the configured level is
**at or above** the message's level:

`0 = off  <  1 = ERROR  <  2 = WARN  <  3 = INFO  <  4 = DEBUG  <  5 = VERBOSE`

Set `DebugLogLevel` to the highest level you want to see; everything more severe
is included. Default is `3` (INFO), recommended for production.

| Level | When to use | Examples in this mod |
|-------|-------------|----------------------|
| `NONE`    | Silence all mod logging. | — |
| `ERROR`   | The mod cannot do its job; needs admin attention. Routed through `ErrorEx()` so it stands out in the `.RPT`. | `box_types.json` / `spawn_locations.json` missing; an entity class failed to spawn. |
| `WARN`    | Recoverable problem; the mod continues with degraded behaviour. | Unknown `boxType` on a spawn location; `loot_lists.json` missing (boxes open empty); unknown fail-effect type. |
| `INFO`    | Normal high-level operational milestones. **Recommended for production.** | Manager initialized; config loaded summary; box spawned; box unlocked and filled. |
| `DEBUG`   | Periodic internal state useful when diagnosing behaviour. | Per-tick lifecycle summary (`removed N, active now M`). |
| `VERBOSE` | Very high-frequency, per-player / per-roll detail. | Each proximity message sent; each fail-effect roll resolved. |

Setting the level to `X` enables `X` **and everything more severe**. For example
`DEBUG` shows ERROR + WARN + INFO + DEBUG, but not VERBOSE.

### A note on VERBOSE

`VERBOSE` fires on hot paths (proximity messages run every ~1.5s per nearby
player; fail-effect rolls run on every failed open). It will flood your `.RPT`
on a populated server and is intended **only for active debugging sessions**.
Leave production servers at `INFO` (or `WARN`/`ERROR` if you want it quieter).

## Log code API (for modders)

```c
Log_Error("...");    // ERROR — also ErrorEx() to the .RPT
Log_Warn("...");     // WARN
Log_Info("...");     // INFO
Log_Debug("...");    // DEBUG
Log_Verbose("...");  // VERBOSE
```

Each prefixes its output as `[YALootBoxes][LEVEL] ...` and self-gates on the
configured level — no need to check the level at the call site.