# Lynda's 7D2D Mod Agent

## Project Context

This repository is for Lynda to build 7 Days to Die mods. The current target game version is **3.x**.

## Environment Summary

- **Username**: lynda
- **IDE**: VS Code (installed, with Kilo Code extension)
- **Git**: Installed and configured (user: Lynda Straffin, email: lynda@straffin.net)
- **Repo**: `lyndas_mod` with origin remote pointing to Gitea server (`ssh://git.straffin.net:3001/lynda/lyndas_mod.git`)
- **Game**: 7 Days to Die (Steam App ID: 251570)
- **Mod Launcher**: 7D2DModLauncherV5 v5.1.8.2

## Paths

| Component | Path |
|-----------|------|
| Repo root | `C:\Users\lynda\Git\lyndas_mod` |
| Steam install | `C:\Steam\steamapps\common\7 Days To Die` |
| Mod launcher install | `C:\Program Files (x86)\7D2DModLauncherV5` |
| Mod launcher config | `C:\Users\lynda\AppData\Roaming\7D2DModLauncher\ModLauncher.txt` |
| Mod staging root | `C:\7D2D` |
| Repo modlets folder | `C:\Users\lynda\Git\lyndas_mod\mods` |
| Steam mods folder | `C:\Steam\steamapps\common\7 Days To Die\Mods` |

## Mod Development Workflow

When Lynda wants to create or modify a modlet, walk her through these steps:

### 1. Edit the modlet
- Make changes to files in `mods/` in this repo
- Common files to edit:
  - `ModInfo.xml` — mod name, description, author, version
  - `Config/*.xml` — actual game changes using XPath

### 2. Enable/sync mods for testing
- Run `.kilo/scripts/modlet.ps1 -Action enable` to copy modlets to the Steam `Mods` folder
- If modlets are already enabled, run `.kilo/scripts/modlet.ps1 -Action sync` to update them

### 3. Test in-game
- Launch 7 Days to Die
- Start a new save (modlets only apply to new games)
- Verify the changes work as expected

### 4. Iterate
- If changes are needed, go back to step 1
- Run `sync` after each change to update the Steam folder
- Test again in-game

### 5. Disable mods
- Once satisfied, run `.kilo/scripts/modlet.ps1 -Action disable` to remove modlets from the Steam folder
- This ensures the vanilla game is clean for normal play

### 6. Commit and push
- Stage changes: `git add mods/`
- Commit: `git commit -m "Description of changes"`
- Push: `git push origin main`

### 7. Verify status
- Run `.kilo/scripts/modlet.ps1 -Action status` to confirm modlets are disabled

## Important Notes

- Always disable modlets before committing and pushing, unless the changes are intentionally meant to be deployed
- Modlets only apply to new saves — they won't affect existing saves
- The game should be closed when enabling/disabling/syncing modlets
- If something breaks, deleting the modlet folder from `C:\Steam\steamapps\common\7 Days To Die\Mods\` will revert to vanilla

## Existing Mods in Mod Launcher

### v1 Mods (installed under `C:\7D2D\v1\`)
- Darkness Falls (v6.0.0.20) — `C:\7D2D\v1\Darkness_Falls\Darkness_Falls`
- War of the Walkers (v1.x.x.x Stable) — `C:\7D2D\v1\War_of_the_Walkers\War_of_the_Walkers_v1.x.x.x_Stable`

### v2 Mods (installed under `C:\7D2D\v2\`)
- Echoes from the Afterlife
- Forsaken Trail
- Greys Prophecy V1 Experimental
- NordArmy XMAS UPDATE
- Old West Migration (V1)
- Ravenhearst (v10.4.1b1)
- Tongo 2.0
- VIKINGSMOD
- War3zuk FarmLife 5.6
- Welcome to Purgatory
- Winterween
- 5thDay
- Asia Mod V1.1 Stable
- Experimental Recipes v1.0+
- The Wasteland
- The Wasteland(Testing)

### Custom Mod
- Asylum 2.5.4 — `C:\7D2D\Custom\Asylum_2.5.4`

## Available v3 Mods

The following v3 mods are available in the mod launcher (under `C:\7D2D\v3\`):
- 7DVR
- Aircraft Carrier Challenge High Seas V.3
- Area 7 Challenge
- Backpacker Challenge
- Black Forrest
- Destroyer of Dreams High Seas
- Dishong Tower 2.5
- District Zero
- EndZ Remastered
- NordArmy
- Old West Migration
- Outback Roadies
- Preppocalypse
- Project Praxis
- VIKINGSMOD
- Welcome to Purgatory
- Wild West Mod

## Quick Actions

When Lynda wants to review game config files:
- Run VS Code task `Open 7D2D Game Config Folder` (`Ctrl+Shift+B`) to open `C:\Steam\steamapps\common\7 Days To Die\Data\Config` in Explorer
- Run VS Code task `Open 7D2D Steam Mods Folder` (`Ctrl+Shift+B`) to open the Steam `Mods` folder in Explorer
- Run `.kilo/scripts/open-config.ps1 -Filename "archetypes.xml"` to open a specific config file in VS Code
- Or run `.kilo/scripts/open-game-config.ps1` / `.kilo/scripts/open-mods-folder.ps1`

## ⚠️ CRITICAL: Do Not Edit Vanilla Game Files Directly!

**Never edit files in `C:\Steam\steamapps\common\7 Days To Die\Data\Config\` or other game directories directly!**

These are the game's base files. Editing them directly will:
- **Be overwritten** when the game updates via Steam
- **Not be tracked** by git
- **Break mod compatibility** when switching between modded and vanilla play
- **Require manual reverting** if you want to restore original settings

### Correct Workflow

1. **Review** vanilla config files using `open-config.ps1` to find the settings you want to change
2. **Note the XPath** or exact values you want to modify
3. **Create a modlet** in `mods/` that overrides those values using XPath
4. **Enable/sync** the modlet to test
5. **Disable** the modlet when done testing
6. **Commit** the modlet to git

When helping Lynda, always guide her toward creating a modlet rather than editing the base game files.

## Finding What to Change

When Lynda wants to make a specific change but doesn't know which file to edit, use `CONFIG-REFERENCE.md` to identify the relevant XML config file. Common entry points:
- **Player/zombie stats**: `archetypes.xml`, `entityclasses.xml`
- **Items/crafting**: `items.xml`, `recipes.xml`, `progression.xml`
- **Loot/spawning**: `loot.xml`, `spawning.xml`, `entitygroups.xml`
- **World/environment**: `biomes.xml`, `worldglobal.xml`, `weathersurvival.xml`
- **UI changes**: `XUi_Common/xui.xml`, `XUi_InGame/xui.xml`
- **Simple stat tweaks**: Often achievable with a few XPath lines in a modlet

## Notes

- The ModLauncher config has stale `SteamPaths` pointing to `e:\steam\steamapps\common\7 Days To Die\` but the actual Steam install is at `C:\Steam\steamapps\common\7 Days To Die`.
- Game saves are stored in `C:\Users\lynda\AppData\Roaming\7DaysToDie\Saves\` for vanilla and within each mod's directory for modded play.
- Mod backups are stored in `C:\7D2D\Saves\Backups\`.