YALootBoxes/CLAUDE_TASK.md

# YALootBoxes — Polish, Verify, and Extend Logging

**Project root:** `P:\YALootBoxes`
**Context:** This is a DayZ server mod (Enforce Script). It was originally scaffolded under the name `LootboxSpawner` and has since been renamed to `YALootBoxes`. The mod spawns lockable lootboxes at config-defined locations; players need a specific held item to attempt opening one via a hold-to-open action; success unlocks+fills the box, failure rolls one random negative effect. All settings live in four JSON files under `$profile:YALootBoxes\`.

This is a **source-level review and polish pass**. There is no DayZ Server/Tools setup available yet, so do not attempt to pack a PBO or boot a server — focus on static correctness, consistency, and completeness of the Enforce Script source and JSON schemas.

Work through the phases below **in order**. Do not skip ahead. At the end of each phase, summarize what you found/changed before moving to the next.

---

## Phase 0 — Orientation

1. Recursively list all files under `P:\YALootBoxes`.
2. Read every `.c`, `.cpp`, and `.json` file you find.
3. Build a mental (or written, in scratch notes) map of: mod folder structure vs. the expected layout below, and flag any structural differences immediately.

**Expected layout:**
```
YALootBoxes/
├── config.cpp
├── Prefix.cpp
└── scripts/
    └── 4_World/
        ├── YALootBoxes_Config.c
        ├── YALootBoxes_Lootbox.c
        ├── YALootBoxes_ActionOpen.c
        └── YALootBoxes_Manager.c
```
(File names above assume the rename also touched filenames — verify and report actual names found, don't assume.)

---

## Phase 1 — Rename Audit (the user says rename "should" be complete — verify, don't trust)

Search the **entire** project for every leftover instance of the old naming scheme. Check ALL of:

- [ ] String `LootboxSpawner` (any casing) — in `.c`, `.cpp`, `.json`, comments, file names, folder names
- [ ] String `LB_` prefix on classes/functions/constants (e.g. `LB_Log`, `LB_MainConfig`, `LB_ConfigLoader`, `LB_BoxTypeDef`, `LB_FailEffect`, `LB_ActionOpenLootbox`, `LB_ApplyRandomFailEffect`, etc.) — decide on and apply a **consistent new prefix** (suggest `YLB_` or `YALB_`) if these were meant to be renamed too
- [ ] `CfgPatches` / `CfgMods` class name (`LootboxSpawner`) in `config.cpp`
- [ ] `CfgVehicles` class names (`LootboxSpawner_Crate_Military`, `_Medical`, `_Industrial`) — these **must** exactly match the `className` fields inside `box_types.json`, so check both sides together
- [ ] `$profile:LootboxSpawner\` path constant — should become `$profile:YALootBoxes\`
- [ ] Any `displayName` strings, log prefixes (`Print("[LootboxSpawner] ...")`), or code comments referencing the old name
- [ ] `Prefix.cpp` content itself

**Action:** Fix every occurrence found. Keep a running checklist in your response of exactly what was renamed, file by file, so the user can review the diff. Do not silently rename things — call out each change.

**Cross-check after renaming:** confirm `box_types.json`'s `className` values still exactly match the `CfgVehicles` class names in `config.cpp` post-rename (this is the #1 way these mods silently fail to spawn anything — a one-character mismatch and the server just won't spawn the object, often without an obvious error).

---

## Phase 2 — Structural / Completeness Review

Go file by file and check for the following. This codebase was written without ever being compiled against the real DayZ SDK headers, so treat it as a first draft that needs adversarial review, not a finished product.

### General Enforce Script correctness
- [ ] Confirm every class that's referenced is actually defined somewhere (no dangling references to types that don't exist, e.g. double check `ContinuousInteractActionInput`, `ActionContinuousBase`, `CCINone`, `CCTObject`, `UAMaxDistances` are real DayZ API symbols available in the modding SDK — if you have access to DayZ SDK docs/headers via web search, verify; otherwise flag as "needs verification against SDK" rather than assuming correctness)
- [ ] Check `RegisterNetSyncVariableBool` usage — confirm sync var registration pattern matches how `ContainerObject`/`ItemBase` subclasses normally do it in DayZ mods
- [ ] Check for null-safety: every place a JSON-loaded reference (`m_TypeDef`, `LB_ConfigLoader.MainConfig`, etc.) is used, confirm there's a null check or a guaranteed-non-null path
- [ ] Check `GetActions()` override signature/pattern is correct for hooking custom actions onto a `ContainerObject`-derived class — this was a best-effort implementation and deserves scrutiny
- [ ] Verify `eAgents` enum members used (`SALMONELLA`, `INFLUENZA`, `CHOLERA`, `BRAIN`, `WOUND_AGENT`) are the real DayZ agent enum names
- [ ] Verify `GetBleedingManagerServer()`, `GetHealthDamageManager()`, `SetFracture()`, `InsertAgent()` are real PlayerBase/HealthDamageManager API calls and used with correct signatures

### Config loading
- [ ] Confirm `JsonFileLoader<T>.JsonLoadFile` / `JsonSaveFile` usage matches real DayZ API (class name and static usage pattern)
- [ ] Confirm the `map<string, ref array<ref LB_LootEntry>>` (or renamed equivalent) is a supported Enforce Script generic — DayZ's Enforce Script has known limitations with nested generic containers in JSON deserialization. **This is a likely problem area** — flag clearly if you believe `JsonFileLoader` cannot deserialize a `map<string, array<...>>` directly. If so, propose a fix: e.g. restructure `loot_lists.json` as an array of `{type, entries}` objects instead of a map, since flat arrays deserialize far more reliably in Enforce Script's JSON layer.
- [ ] Check that `EnsureDirectoryExists` / `MakeDirectory` calls match the real API (case, return type)
- [ ] Confirm default-object construction (e.g. `LB_MainConfig()` constructor) actually runs before `JsonLoadFile` overwrites fields, so a partially-specified JSON file doesn't leave other fields zero/null

### Lifecycle & manager logic
- [ ] Re-derive the despawn timer logic by hand against the user's original spec: locked boxes despawn/respawn after N minutes (config-driven per box type) **even if never opened**; opened boxes despawn N minutes after becoming unlocked. Confirm `HasExpiredUnopened` / `HasExpiredAfterOpening` actually implement this without overlap or gaps.
- [ ] Check for a race/edge case: what happens if a box is mid-open-action (channeling) at the exact moment the lifecycle tick deletes it for expiring? Flag this as a known edge case if not already handled, and propose a minimal guard (e.g. skip despawn-delete if an action is actively targeting it, or just accept and document the rare edge case).
- [ ] Check `CallLater(..., true)` repeating-timer usage is correct DayZ API usage (3rd param = repeat flag, confirm order of args).
- [ ] Verify location pool logic (`m_FreeLocationNames`, `m_LocationInUse`) doesn't have an off-by-one or duplicate-assignment bug when `SpawnOneAtRandomFreeLocation` recurses on failure.

### Action / interaction logic
- [ ] Confirm the "fixed channel time, instant roll, but failure can interrupt early" requirement is actually satisfiable with `ActionContinuousBase` + `OnFinishProgressServer` — i.e. confirm that bailing out early (releasing the button) does NOT call `OnFinishProgressServer` and does NOT roll anything. Flag if the current code doesn't clearly guarantee this.
- [ ] Confirm the proximity message system (manager's `TickProximityMessages`) and the action's "show prompt when holding right item" are not redundant/conflicting — i.e. one always shows "Requires: X", the other only enables the action — and that nothing in the action class duplicates the proximity broadcast.
- [ ] Verify `RPCSingleParam` / `ERPCs.RPC_USER_ACTION_MESSAGE` is a real, appropriate way to send a HUD text message to a single client in DayZ's API. If this is not correct, propose the standard pattern used by DayZ mods for "send toast/notification to one player" (often a custom RPC type registered in `Init.c`/`Missions`, since `RPC_USER_ACTION_MESSAGE` may not exist or may not behave as a generic toast).

### Config/JSON schema consistency
- [ ] Confirm every field referenced in `.c` files has a matching field (same name, same casing) in the example JSON files, and vice versa.
- [ ] Confirm `failEffects[].chance` semantics are documented clearly as "weight" not "independent probability" (since the code does a weighted pick among effects, not N independent rolls) — fix any comment/naming that implies otherwise.

Produce a written list of every issue found in this phase, categorized as:
- 🔴 **Will likely fail to compile or run** (must fix)
- 🟡 **Will likely behave incorrectly at runtime** (should fix)
- 🟢 **Style/maintainability nit** (optional)

Fix all 🔴 and 🟡 items. For 🟢 items, list them but ask before changing anything purely stylistic.

---

## Phase 3 — Add Debug Logging Levels

Extend the logging system to support **NONE / ERROR / WARN / INFO / DEBUG / VERBOSE** levels, replacing the current single `EnableDebugLogging: bool`.

### Requirements:
1. In the main config class, replace `EnableDebugLogging` (bool) with `DebugLogLevel` (string or int — your call, but document which and why; string is more admin-friendly for hand-editing JSON, int is cheaper to compare at runtime — consider storing as string in JSON but parsing to an int enum at load time for fast comparisons).
2. Define the level ordering: `NONE(0) < ERROR(1) < WARN(2) < INFO(3) < DEBUG(4) < VERBOSE(5)`. A message at level X is printed only if `DebugLogLevel >= X`.
3. Replace the single `LB_Log(string msg)` (or renamed equivalent) helper with level-specific variants, e.g.:
   - `Log_Error(string msg)`
   - `Log_Warn(string msg)`
   - `Log_Info(string msg)`
   - `Log_Debug(string msg)`
   - `Log_Verbose(string msg)`

   Each should prefix output appropriately, e.g. `[YALootBoxes][ERROR] ...`, and route to both `Print()` (.log/.rpt via engine default) and, if straightforward, `ErrorEx()` for ERROR-level messages specifically (DayZ's standard pattern for messages that should be prominent in the `.RPT` file) — verify `ErrorEx` is real API before using it; if uncertain, just use `Print()` consistently and note the limitation.
4. Go through **every existing log call in the codebase** and reclassify it to the correct level based on its actual content:
   - Config file missing / failed to parse / unknown class referenced → `ERROR` or `WARN` depending on whether it's recoverable
   - "Spawned box at location X", "Manager initialized" → `INFO`
   - Per-tick lifecycle summaries ("removed N, active now M") → `DEBUG`
   - Per-player proximity message sends, per-effect-roll details → `VERBOSE`
5. Update the example `main_config.json` to use the new field with a sensible default (`INFO` recommended for normal server operation).
6. Update the default-constructor fallback value to match.

Add a short section to the project's README (create one at `P:\YALootBoxes\README.md` if it doesn't exist) documenting:
- What each log level is meant to be used for
- The config field name and JSON example
- A reminder that VERBOSE will be noisy and is meant for active debugging sessions only, not production

---

## Phase 4 — Final Consistency Pass

1. Re-read every file once more, top to bottom, now that renaming and logging changes have landed, specifically checking that:
   - No file still calls the old single-arg `LB_Log(...)` (or its renamed equivalent) — every call site should now use a leveled function
   - No JSON file and `.c` file have drifted out of sync on field names again as a side effect of your edits
   - All four JSON example files are valid JSON (mentally parse them, or note if you want to validate via a tool)
2. Produce a final summary report with these sections:
   - **Renames applied** (file-by-file list)
   - **Bugs fixed** (🔴 and 🟡 items from Phase 2, with before/after description)
   - **Known limitations / things that need real DayZ SDK to verify** (be explicit — this matters since nothing has been compiled yet)
   - **Logging system** (what changed, default level, example config)
   - **Suggested next steps** for the user once they have DayZ Tools available (e.g. "pack PBO, boot test server, spawn near a military crate empty-handed, confirm proximity message text, pick up a crowbar, confirm action prompt appears, hold to open, confirm one of the two outcomes fires correctly")

---

## Ground rules throughout

- **Do not invent DayZ API behavior you're not confident about.** If you can't verify something against real SDK docs/headers, say so explicitly in the summary rather than presenting a guess as fact. This is real game-server code the user intends to run.
- **Do not silently delete functionality.** If you think something should be removed (e.g. a redundant message path), propose it and explain why before removing it, in your phase summary.
- **Keep commit-sized changes traceable** — if this is a git repo, make small logical commits per phase rather than one giant diff; if it's not a git repo, mention that initializing one would make this kind of iterative work much easier to review going forward.
- This is **review + polish + logging**, not a redesign. Don't change the core mechanics (proximity message always shown, fixed-channel hold-to-open, weighted single fail-effect roll, post-open despawn timer) unless you find them to be actually broken as currently spec'd — flag concerns rather than unilaterally redesigning.