d28cebd5d6
Structure / module placement: - Add scripts/5_Mission/YALootBoxes_MissionServer.c: a modded MissionServer that self-starts the manager in OnInit(). No init.c edit required anymore. - config.cpp: bind 5_Mission to missionScriptModule (4_World stays on worldScriptModule). Core logic correctly stays in 4_World; only the mission-lifecycle bootstrap lives in 5_Mission. Config create/read/write: - LoadAll now writes populated defaults for ALL four JSON files when missing (previously only main_config.json was generated; box_types/loot_lists/ spawn_locations were left empty, so a fresh install spawned nothing). - Add default-data factories (YALB_MkReq/MkFail/MkLoot/MkLoc/MkBoxType) and DefaultBoxTypes/DefaultLootLists/DefaultSpawnLocations builders mirroring configfiles.readme. The mod is now self-provisioning on first run. Docs: - Prefix.cpp: refreshed folder-layout summary; dropped stale init.c / simulationModule notes. - Manager.c: bootstrap comment now points to the 5_Mission self-start. - README.md: add Install & first-run section. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
96 lines
4.3 KiB
Markdown
96 lines
4.3 KiB
Markdown
# 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`:
|
|
|
|
```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)
|
|
|
|
```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.
|