YALootBoxes/README.md

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 = INFO.
[YALootBoxes][INFO] Manager initialized. N lootboxes spawned.

Logging

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

{
  "DebugLogLevel": "INFO"
}

Why a string?

The level is stored as a string in JSON because it is far friendlier for admins hand-editing the file ("DEBUG" reads better than 4). It is parsed once at load time into an integer (YALB_ConfigLoader.LogLevel) so every runtime log call is a cheap integer comparison, not a string compare. Parsing is case-insensitive, and an unrecognised value falls back to INFO so a typo can never silently disable logging.

Levels

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

NONE(0) < ERROR(1) < WARN(2) < INFO(3) < DEBUG(4) < VERBOSE(5)

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)

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.