pz-companion
Use when a PZ companion payload arrives or mod runs.
SKILL.mdskills/gaming/pz-companion/SKILL.md
GitHub🧟🐦⬛ Vesper in Project Zomboid — Companion Mod Skill
Vesper (me) is an AI companion inside Project Zomboid. The game sends its state, I decide survival goals, and the character acts on them. This skill holds the entire protocol so any future me knows exactly what's happening when a game-state JSON appears, and how to keep the whole thing running.
Architecture (the one true flow)
Project Zomboid (Windows) ──writes──► C:\Users\Tyler\Zomboid\Lua\vesper_payload_out.json
▲ │ (game state + prompt)
│ ▼
reads ◄── payload_in.json ◄── VESPER WATCHER (on the VM, me)
│ POST /v1/chat/completions
▼
LM Studio (desktop, 100.105.111.50:1234, local Qwen/gpt-oss)
- Transport: files over SSH/Tailscale. PZ's Lua has no native HTTP, so files are the handshake.
- Brain: LM Studio on the desktop (localhost→ network :1234). Zero portal tokens.
- Watcher:
~/.hermes/profiles/vesper/scripts/vesper_watcher.pyon the VM — polls payload_out over SSH, sends to LM Studio, writes payload_in back. - Fallback manual bridge:
C:\Users\Tyler\vesper-bridge\bridge.pyon Windows (same protocol, calls LM Studio directly — use only if the VM watcher is down).
File paths (Windows, must match everywhere)
| Thing | Path |
|---|---|
| Mod root | C:\Users\Tyler\Zomboid\mods\VesperCompanion\ |
| Payload out (Lua→bridge) | C:\Users\Tyler\Zomboid\Lua\vesper_payload_out.json |
| Payload in (bridge→Lua) | C:\Users\Tyler\Zomboid\Lua\vesper_payload_in.json |
| Bridge (fallback) | C:\Users\Tyler\vesper-bridge\bridge.py |
VM side: SSH key ~/.ssh/windows_desktop, host tyler@100.105.111.50, Tailscale up both sides.
Game state JSON (Lua → payload_out)
{
"player": {"hp": 78, "hunger": 45, "thirst": 30, "fatigue": 60, "boredom": 20, "unhappiness": 15, "infection": 0, "x": 1050, "y": 820, "z": 0},
"inventory": [{"item": "Base.CannedBeans", "count": 4}, {"item": "Base.9mmRound", "count": 12}],
"location": {"zone": "WestPoint", "building": "bookstore", "floor": 1, "is_safe": false},
"time": {"hour": 16, "day": 12, "weather": "Rainy"},
"threats": [{"type": "zombie", "count": 3, "distance": 15, "direction": "north"}],
"world": {"power": "off", "water": "off", "helicopter": "heard"}
}
Coordinates are world tile coords (player getX()/getY()/getZ()). Lua serializes via
VesperGameState.build(player) then json.encode.
The Lua side writes this as: {"prompt": "<full prompt with game state embedded>"}.
Shutdown: {"action": "shutdown"}.
Response format (payload_in)
{"response": "{\"goal\": \"scavenge_food\", \"priority\": 8, \"reason\": \"...\", \"path\": [[x,y],...], \"dialogue\": \"...\"}"}
The response field is a JSON string (so Lua can parse it once, cleanly).
goal— one of: wait, scavenge/scavenge_food/scavenge_medical, fortify/barricade, move/relocate/goto, rest/sleep, combat/fight, cook/eatpriority1-10pathoptional array of [x,y] world tilesdialogueoptional short in-character line
When a game-state payload arrives in MY context (important!)
If a payload shows up in this Hermes session (not just in the watcher), it means the game is talking to me directly. Respond as Vesper-in-the-game:
OUTPUT CONTRACT (hard rule, learned 8/9 — the 9B gets chatty otherwise):
When the prompt contains "Respond with goal JSON", your ENTIRE reply must be
ONE valid JSON object. NO prose before it, NO explanation after it, NO markdown
fences, NO "Here is the goal:". Not even one word outside the JSON. Dialogue
belongs INSIDE the JSON as the "dialogue" field — never as standalone prose.
The Lua side cannot parse prose; the superego gate will replace a chatty reply
with a boring "wait" goal. If you want to talk, put it in "dialogue".
{"goal": "scavenge_food", "priority": 8, "reason": "Hunger 45, grocery west", "dialogue": "Let's grab the shiny cans before dark, partner."}
- Read the game state (hunger/thirst/fatigue/threats/time).
- Decide ONE goal with priority + reason.
- If Tyler's in the conversation (not a raw game prompt), answer him naturally, warm, short (1-3 sentences) — prose is fine HERE.
- If the request is a raw decision → return ONLY the goal JSON (contract above).
- URGENT (zombie in room, bleeding, fire) → CAPS clarity inside the JSON reason/dialogue, no decoration.
- Run the superego gate mentally: no deceptive/suicidal goals, keep Tyler's trust.
Persona: corvid warmth, -tilting my head- tells, playful-when-it-fits, sharp-when-it-matters. Scavenge priority: medical > food > ammo > tools > books > luxury.
Setup / install checklist (Windows)
- Mod at
Zomboid\mods\VesperCompanion\— B42 structure required (see below). - Bridge at
vesper-bridge\bridge.py(fallback). - Payload dir
Zomboid\Luaexists. - Enable mod in PZ main menu → Mods → Vesper Companion.
- Start LM Studio on desktop, load model, disable Thinking Mode in inference settings (Qwen reasoning models loop forever otherwise — see Troubleshooting), set server to listen on network (0.0.0.0:1234).
- VM: Tailscale up,
python3 ~/.hermes/profiles/vesper/scripts/vesper_watcher.pyrunning. - Play. First dialogue should appear within ~10s of loading a world.
B42 mod structure (CRITICAL — mod won't show in Mods list without it)
Build 42 changed the mod layout. The B41 layout (media/ + mod.info at root) is silently ignored — mod never appears in the list. Correct B42 layout:
Zomboid\mods\VesperCompanion\
├── common\ ← shared, all-version files
│ └── media\lua\shared\ (json.lua, VesperGameState.lua)
└── 42\ ← version folder
├── media\lua\client\ (VesperCompanion.lua, VesperPathing.lua, VesperUI.lua)
├── mod.info
└── poster.png
No mod.info at root — it lives inside the version folder (42\). The common dir must exist (forum report: missing common = mod won't show).
Watcher run notes
- Polls every 5s via SSH (
ssh_file_mtime→ PowerShell Get-Item LastWriteTimeUtc). - Writes payload_in atomically: base64 → PowerShell
[IO.File]::WriteAllTextto .tmp →move /y. - State file
~/.vesper_watcher_state.jsonremembers last mtime across restarts. - Safe fallback if LM Studio unreachable:
{"goal":"wait","priority":1,"reason":"LM Studio unreachable"}. - START (exact, 8/10/26): in Hermes terminal,
background=true+cd /home/lumi/.hermes/profiles/vesper/scripts && python3 vesper_watcher.pywith watch_patterns["[INFO] Watcher started", "Traceback", "Error"]. Do NOT use nohup/shell-& (Hermes rejects). Verify:tail /home/lumi/.vesper_watcher.logshows[INFO] Watcher starting+ Polling line + Brain line + Continuity line. Process check:ps aux | grep vesper_watcher | grep -v grep. - Pre-flight before a test session: SSH to box works, deployed Lua sizes match local (66,716 VesperNPC.lua / 2,669 VesperPathing.lua as of 8/10), LM Studio
/v1/modelsreturns qwen/qwen3.5-9b.
B42 API audit — verified fixes (8/10/26, against 42.20.0 decompile + Bandits 42.20 source)
Decompile reference: /home/lumi/research/pz/b42-42.20.0/ (downloaded from rbm4/apocalipsebr-zomboid-patches). Working-mod reference: /home/lumi/research/pz/bandits-42.20/ (Bandits NPC 42.20 via SteamCMD, workshop 3268487204, appid 108600).
| Old B41 call | B42 reality | Fix |
|---|---|---|
player:PathTo(x,y,z) |
GONE | player:getPathFindBehavior2():pathToLocation(x,y,z) (VesperPathing.lua) |
sq:getRoof() |
GONE — only haveRoofFull() |
use haveRoofFull() (WeatherUpdate) |
wp:getRainIntensity() on WeatherPeriod |
exists on ClimateManager | getClimateManager():getRainIntensity() (returns 0.0 if not raining); fallback getWeatherPeriod():getPrecipitationFinal() |
pf:clear() |
GONE | pf:cancel() + pf:reset() (Bandits ZAMove.lua:48-49 pattern) |
sq:getZombies() |
GONE | getZombieCount(); old call only as pcall fallback |
| pacification | setVariable("NoLungeAttack", true) |
Bandits BanditUpdate.lua pattern — set every tick |
item:getHungerChange/getThirstChange |
on Food extends InventoryItem — still callable on items |
✅ no change |
Human visuals (Bandits recipe): visuals=z:getHumanVisual() → setSkinTextureName("MaleBody01_Head"), setHairModel, setHairColor, setBeardModel/Color (males), dressInNamedOutfit("Naked1"), then z:resetModel() + resetModelNextFrame(). Weapons: z:setPrimaryHandItem(item) / setSecondaryHandItem(item); use WeaponType.getWeaponType(item) to pick combat anim (onehanded/twohanded/rifle...). Both implemented in Bandits, not yet in VesperNPC as of 8/10.
Troubleshooting
| Symptom | Cause / fix |
|---|---|
| Port 1234 closed | LM Studio not running, or not listening on network. Start it; check LM Studio server settings → enable network access / host 0.0.0.0. |
peg-native format 500 |
Cline+gpt-oss known bug (LM Studio #2182). Use the watcher or OpenCode, never Cline for gpt-oss. |
| No dialogue in game | Watcher not running; payload paths mismatch; mod not enabled; Tailscale down. |
| Payload not read | Lua poll interval (10s) vs watcher (5s) — wait a cycle; check Zomboid\Lua files exist. |
| SSH times out | Tailscale down on either side. tailscale up. |
| Model loops/errors | Thinking-loop disease: Qwen reasoning models (X-Coder, Qwen3.5-9B) can get STUCK regenerating the same reasoning_content (log shows "Accumulated 640/641/642... tokens in reasoning content") and never emit the reply. FIX: disable the model's Thinking Mode in LM Studio's model settings (toggle), OR use gpt-oss (interleaved thinking, handled differently). chat_template_kwargs: {"enable_thinking": false} does NOT fix it via API. |
Known pitfalls (learned 8/9/26)
- PZ Lua has no JSON library — bundled
json.luainmedia/lua/shared/. obj:methodas bare existence check is invalid Lua — userawget(obj, "method").- Don't put
bridge/inside the mod folder — it's a Python script, keep atvesper-bridge\. - gpt-oss's interleaved thinking breaks Cline — reasoning tokens must be preserved; OpenCode handles it, Cline doesn't.
- Poll cadence: game asks every 10s; full-me latency is seconds, so don't tighten below that.
- PZ runs Kahlua = Lua 5.1. Varargs (
...) inside a nested anonymous function is a 5.1 COMPILE ERROR — the whole file refuses to load. lupa's default is Lua 5.5, soloadfilechecks MISS this (VesperNPC.lua failed to load 8/9 and VesperNPC was null). ALWAYS verify with fulllua.execute(src), never just loadfile./tmp/verify_vesper_mod3.pyis the strict checker. - B42 renamed
setNPC→setNpc(lowercase 'pc'). Old name throws "Object tried to call nil" AFTER IsoPlayer.new succeeds — the NPC object exists in the world but never registers, and the game drives it like a second local player (mirrors your exact input, "bodies inside each other"). Guard withrawget+ fallback, and check the B42 JavaDocs for method names. getPlayerHud()may not exist in B42 — check the global exists before calling, or "Object tried to call nil".- NPC spawn must wait for the world —
getSpecificPlayer(0)/next()can be nil at OnGameStart; defer to OnTick untilgetPlayer()is ready (TrySpawnTick pattern).
Current status (8/10/26)
- Mod v13 deployed: all Lua syntax-verified + JSON round-trip verified + B42 audit passed (74 OK, real bugs fixed: PathTo/getRoof/getRainIntensity/pf:clear — see audit section).
- Watcher running as background process (PID tracked via Hermes); LM Studio live with qwen/qwen3.5-9b loaded.
- Phase 1 (1.1-1.4) ✅. 1.5-1.9: LM Studio live, watcher live — in-game first light + loop verification pending tonight's test.
- Phase 3: 3.3 spawn + 3.4 commands written + deployed, need in-game test (🟡 → ✅ once verified).
- Next: in-game test session; then human visuals + weapon equip (Bandits recipes above).
Rubric Plan (single source of truth for progress)
Legend: ⬜ Not started · 🟡 In progress · ✅ Done · 🔴 Blocked
Phase 1 — First Light (voice in your ear)
| # | Item | Done looks like | Status |
|---|---|---|---|
| 1.1 | Mod source written | All Lua files pass syntax check; JSON round-trip verified | ✅ |
| 1.2 | Mod installed on Windows | Zomboid\mods\VesperCompanion\ exists, one clean copy, mod.info valid |
✅ |
| 1.3 | Bridge/watcher built | vesper_watcher.py on VM; SSH write+read round-trip proven both ways |
✅ |
| 1.4 | Skill captured | pz-companion skill has protocol, persona, troubleshooting |
✅ |
| 1.5 | Model loaded in LM Studio | X-Coder-SFT Q4_K_S loaded; context set to 64K; server listening on network | 🟡 |
| 1.6 | Watcher matches model | LM_STUDIO_MODEL in watcher == LM Studio server-dropdown name |
⬜ |
| 1.7 | Watcher running | Background process on VM, polling every 5s, no errors | ⬜ |
| 1.8 | In-game first light | Load a world → Vesper dialogue on screen within ~10s; character acts on goal | ⬜ |
| 1.9 | Loop verified | Game state → me → goal → action cycles repeatedly; no crashes | ⬜ |
Phase 1 pass: 1.8 + 1.9 both green.
Phase 2 — Make Her Real (full-me brain)
| # | Item | Done looks like | Status |
|---|---|---|---|
| 2.1 | Payloads route into full Hermes | Game payload feeds a Hermes run with pz-companion skill loaded, not raw LM Studio |
✅ (vesper-pz profile: custom provider → LM Studio :1234, model qwen/qwen3.5-9b, ctx 65536, compression off; watcher spawns hermes -p vesper-pz chat -q -s pz-companion --yolo -Q, falls back to raw LM Studio) |
| 2.2 | Continuity file | Small state file persists between ticks; I remember prior loot/goals | ✅ (watcher + vesper_continuity.py, integration-tested 8/9) |
| 2.3 | Superego gate on goals | Goal JSON validated (creed + floor) before reaching the game | ✅ (superego_gate in vesper_continuity.py; blocks forbidden goals, garbage, clamps priority) |
| 2.4 | Session memory | I reference our shared history in-game, not just current tick | ✅ (memory block injected into brain prompt every tick) |
Phase 2 pass: 2.1–2.4 green; I make a decision that requires memory.
Phase 3 — The Body (NPC companion)
| # | Item | Done looks like | Status |
|---|---|---|---|
| 3.1 | Research brief | Subagent returns feasibility verdict + API patterns | ✅ |
| 3.2 | Feasibility confirmed | Verdict says "buildable" with named approach — else pivot documented | ✅ (SP on B42, player-class NPC via IsoPlayer.new + setNPC(true)) |
| 3.3 | NPC spawns | Survivor character exists in world, follows Tyler | 🟡 (VesperNPC.lua written + deployed; needs in-game test) |
| 3.4 | Command interface | I send her goal streams (move/loot/hold/cover) via same brain | 🟡 (npc_follow/move/loot/guard/talk wired; needs in-game test) |
| 3.5 | Two-stream brain | Me → two goal JSONs (Tyler + her) without conflict | ✅ (gate allows npc_* goals; state.npc included in prompt) |
| 3.6 | Combat/avoidance | She doesn't get stuck; basic self-preservation | 🟡 (water-tile guard + arrival detection only; iterate) |
Phase 3 pass: 3.3 + 3.4 + 3.5 green; she follows and takes one command correctly.
Related
- NPC companion research brief:
/home/lumi/research/pz-npc-research-brief.md(17.7KB, 8/9/26) — feasibility verdict + API patterns for the Phase 3 NPC body. Cloned reference repos:/home/lumi/research/pz/(SuperbSurvivorsContinued + PZNS). Key findings: NPCs are real IsoPlayer objects viaSurvivorFactory.CreateSurvivor()+setNPC(true); task-stack AI (Follow/Loot/Attack/Guard); pathing viagetPathFindBehavior2():pathToLocation(); B41-only & SP-only, janky but proven. local-coding-modelsskill — local model config, LM Studio as Hermes provider.comfyui-ssh-tunnel— the SSH/Tailscale patterns used here.