Editor setup

How to set up VS Code (or another IDE) so editing a pack is not a chore. Covers syntax highlighting, autocomplete, running the validator, and the file associations that make .girlsx and friends act like XML.

TL;DR for VS Code

1. Install VS Code if you don’t have it.
2. Open the game folder as a workspace: File -> Open Folder and pick the root (the one containing Resources/, tools/, and the .exe).
3. When VS Code prompts for recommended extensions, click Install. (The prompt comes from a pre-configured .vscode/extensions.json that ships with the game.)
4. Done. You now have Lua autocomplete, XML syntax highlighting for .girlsx / .itemsx / .traitsx / .rgirlsx, and Ctrl+Shift+B runs the pack validator.

The game ships with a .vscode/ folder at the install root. That folder is what tells VS Code how to treat pack files, which extensions to suggest, and what the validator task does. If you ever delete or break it, restore it by copying tools/pack-authoring-kit/snippets/.vscode/ back to the game root.

The rest of this page fills in the detail and covers what each piece does.

Why open the whole game folder

The language servers need to see Resources/Scripts/definitions/wm.lua (for Lua completions), Resources/Data/Traits/ and friends (for cross-referencing), and your pack under Resources/Packages/YourPack/. Opening just the pack folder starves them. Open the root.

If you prefer a multi-root workspace (so you can keep the game folder and a separate pack-in-progress folder side by side), VS Code supports that via File -> Add Folder to Workspace.

Recommended extensions

Install these once and forget them.

Extension	Why
Lua (sumneko.lua)	Autocomplete and type checking for wm.* API
XML (redhat.vscode-xml)	Syntax highlighting and validation for pack XML
GitLens (eamodio)	Optional, useful if you version your pack with git

You can install all three from the command line:

code --install-extension sumneko.lua
code --install-extension redhat.vscode-xml
code --install-extension eamodio.gitlens

Or use the Extensions panel in VS Code (Ctrl+Shift+X) and search by name.

File associations

By default, VS Code doesn’t know that .girlsx, .rgirlsx, .itemsx, and .traitsx are XML. The shipped .vscode/settings.json fixes that:

{
    "files.associations": {
        "*.girlsx": "xml",
        "*.rgirlsx": "xml",
        "*.itemsx": "xml",
        "*.traitsx": "xml",
        "*.roomsx": "xml",
        "*.script": "xml"
    }
}

If you’re working on a pack outside the game folder (for example, developing in a separate git repo), copy the shipped .vscode/ into that folder too, or merge these entries into your existing settings.

Lua support in detail

The game ships Resources/Scripts/definitions/wm.lua with LuaLS @meta annotations for the whole API. Once the Lua extension is installed and the workspace is opened at the game root, you get:

• Autocomplete: type wm. and see every function.
• Signature help: parameter types show as you type.
• Type checking: wrong argument types get squiggles.
• Go to definition: Ctrl+Click on any wm.* call jumps to the definition in wm.lua.

No configuration required. If LuaLS is not finding wm.lua, check that the workspace root includes Resources/Scripts/definitions/ (it does if you opened the game folder).

See lua-scripting.md for the script lifecycle, trigger types, and writing your first encounter.

Running the pack validator from VS Code

The validator is a CLI tool at tools/pack-validator/pack-validator.exe. Two ways to run it from VS Code:

Terminal (simplest): open the integrated terminal (Ctrl+`), then:

./tools/pack-validator/pack-validator.exe

The validator walks up to find Resources/Data/config.xml and scans everything. No arguments needed as long as you run it from somewhere inside the game tree.

Task (one-key): add to .vscode/tasks.json:

{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "Validate packs",
            "type": "shell",
            "command": "./tools/pack-validator/pack-validator.exe",
            "group": "build",
            "presentation": { "panel": "dedicated", "clear": true }
        }
    ]
}

Now Ctrl+Shift+B runs the validator. A copy of this tasks.json lives at snippets/.vscode/tasks.json.

Scaffolding a new pack from VS Code (1.15.6+)

Ctrl+Shift+P → Tasks: Run Task → New pack…. VS Code prompts for a pack name (e.g. My Custom Pack) and an optional pack id (leave blank to derive my_custom_pack from the name). The task creates Resources/Packages/<Name>/, drops in a customised package.xml, and copies the kit’s starter Items.itemsx / Traits.traitsx / Girls.girlsx / images.xml so you have something to read and adapt rather than a blank folder.

The task refuses to overwrite an existing folder — delete or rename the old one first if you’re regenerating.

The task is a wrapper over tools/pack-authoring-kit/tools/scaffold-new-pack.py. You can also call the script directly from the terminal:

python3 tools/pack-authoring-kit/tools/scaffold-new-pack.py --name "My Pack" [--id my_pack] [--no-templates]

--no-templates creates just package.xml (useful if you’d rather pull files in one at a time via the kit’s pkg-manifest, item, trait, … snippets in the editor).

Requirements: Python 3 must be on PATH (macOS / most Linux distros ship with it; on Windows install from python.org and tick “Add to PATH” during the installer). The shipped task auto-picks python3 on macOS / Linux and py -3 on Windows.

Other editors

JetBrains (IntelliJ IDEA, PyCharm, etc.)

• Lua: install the Lua plugin (IntelliLua works; sumneko’s LuaLS is not native but usable via the LSP4IJ bridge).
• XML: built-in, no setup needed. Add file associations for the .girlsx family: Settings -> Editor -> File Types -> XML -> + and add *.girlsx, *.rgirlsx, *.itemsx, *.traitsx.

Neovim

• Lua: nvim-lspconfig with sumneko’s lua-language-server. Workspace library should include Resources/Scripts/definitions/.
• XML: lspconfig.lemminx gives you the same language server VS Code uses (redhat.vscode-xml is a wrapper around lemminx).
• File type mapping in init.lua:

  vim.filetype.add({ extension = { girlsx = 'xml', rgirlsx = 'xml', itemsx = 'xml', traitsx = 'xml' } })

Notepad++

• XML highlighting: Language -> X -> XML on each file, or permanently via Settings -> Style Configurator -> XML and add the extensions under “User ext”.
• No Lua autocomplete; read wm.lua in a split for reference.

Sublime Text

• Lua: install the LSP package and LSP-lua from Package Control. Point it at Resources/Scripts/definitions/ as a library.
• XML: built-in highlighting works once you map the extensions via View -> Syntax -> Open all with current extension as… -> XML.

Workspace layout

The shipped .vscode/ at the game root contains three files:

File	What it does
settings.json	File associations (.girlsx -> XML, etc.), tab size, and disables XML validation (no .xsd schemas yet)
tasks.json	Ctrl+Shift+B runs pack-validator.exe; “New pack…” (in the Run Task palette) scaffolds a fresh pack under Resources/Packages/<Name>/
extensions.json	Recommends the sumneko Lua and Red Hat XML extensions on first open

If you deleted or edited the shipped config and want the defaults back, a pristine copy lives in tools/pack-authoring-kit/snippets/.vscode/.

Git and version control (optional)

Treat your pack folder as a git repo. Modders who ship packs this way get:

• Easy rollback when a change breaks loading.
• A public repo URL to share alongside the zip.
• Change history that helps when another modder asks “what changed between v1.0 and v1.1?”.

A minimal .gitignore for a pack:

# Generated files
*.bak
*.tmp

# Editor clutter
.vscode/
.idea/

Keep the pack itself (XML, images, scripts) committed. Ignore editor state.

Troubleshooting

XML files still show as plain text after adding the association. Reload the window: Ctrl+Shift+P, “Developer: Reload Window”.

Lua autocomplete shows wm. but no functions. The workspace root is probably not the game folder. Check: File -> Open Folder should point at the directory containing Resources/, not at your pack folder directly.

Validator runs but says “could not locate Resources/Data/config.xml”. You’re invoking it from outside the game tree. Either open the game root in VS Code, or pass the game root as an argument: pack-validator.exe "C:/games/WMR".

Red squiggles in .girlsx files complaining about missing DTD. The XML extension is trying to validate against a schema. There is no .xsd for WMR XML yet; safe to ignore. To silence: add "xml.validation.enabled": false to your workspace settings.json.