Authoring Guide

A start-to-finish walk-through for your first pack. Assumes you have the game installed and can find its Resources/Packages/ folder.

0. Set up your editor first

Before touching any files, get VS Code (or your editor of choice) configured for pack work. Takes two minutes and saves hours of squinting at unhighlighted XML.

1. Install VS Code.
2. Open the game folder (the one containing Resources/, tools/, and the exe) via File -> Open Folder.
3. VS Code detects the shipped .vscode/ and prompts you to install the recommended extensions (Lua by sumneko, XML by Red Hat). Click Install.

You now have XML highlighting for pack files, Lua autocomplete against the wm.* API, and Ctrl+Shift+B to run the pack validator. See reference/editor-setup.md for other editors (JetBrains, Neovim, Notepad++, Sublime) and troubleshooting.

1. Pick a scope

Before you open a text editor, decide what your pack is. The common shapes:

• A new girl (or two, or ten). Most packs are this. You need images and a Girls.girlsx entry for each girl.
• A set of items. Potions, equipment, consumables. One Items.itemsx file, no characters needed.
• Custom traits. New personality or physical traits other packs can reference.
• An addon to someone else’s pack. Extra images for an existing girl, or extra traits they asked for.

Pick one. You can always add the other kinds later.

2. Create the folder

Under Resources/Packages/, create a folder named after your pack. Use a short, filesystem-friendly name. This folder name becomes your pack’s identifier if you don’t set one explicitly.

Resources/Packages/
    MyPackName/
        package.xml

package.xml is required. Without it the loader skips your folder silently. The smallest valid file is:

<Package Name="My Pack Name" Id="my_pack_name" Author="You" Version="1.0" />

See snippets/package.xml for the full set of optional fields, and reference/girlsx-schema.md for what each one does.

Shortcut (VS Code, 1.15.6+): Ctrl+Shift+P → Tasks: Run Task → New pack… prompts for a name and an optional id, then scaffolds Resources/Packages/<Name>/ with a customised package.xml and the starter content files described in step 3 below. See reference/editor-setup.md (“Scaffolding a new pack from VS Code”) for the full description. Without VS Code, run python3 tools/pack-authoring-kit/tools/scaffold-new-pack.py --name "My Pack" from the game root.

3. Add content

Pick one (or more) based on step 1:

• Girls: create Girls.girlsx in the pack root. Copy from snippets/Girls.girlsx and fill in. For each girl, create Characters/<GirlName>/ and put her images inside. Folder name must match the girl’s Name attribute exactly.
• Items: create Items.itemsx in the pack root. Copy from snippets/Items.itemsx.
• Traits: create Traits.traitsx in the pack root. Copy from snippets/Traits.traitsx.

You can have all three in the same pack.

4. Add images

If your pack has girls, each girl needs at least one profile image. Two ways to organise them:

Subfolders (recommended for new packs):

Characters/Jane/
    Profile/
        portrait.jpg
        casual.jpg
    Sex/
        scene1.jpg
    Oral/
        bj1.jpg

Filenames inside don’t matter. The subfolder name is the category.

Prefix filenames (legacy, still supported):

Characters/Jane/
    profile01.jpg
    profile02.jpg
    sex01.jpg
    oral01.jpg

The filename prefix is the category.

Full list of recognised categories is in reference/filename-cheatsheet.md. The authoritative set of image types is Resources/Data/ImageTypes.xml (86 entries).

5. Validate

Run the pack validator:

tools/pack-validator/pack-validator.exe path/to/your/pack

It checks XML is well-formed, required fields exist, referenced image folders aren’t empty, and girl folder names match their Name attributes. Fix whatever it flags before loading in-game.

6. Load in-game

Start the game. Your pack should appear in the Content Manager (top-bar menu). If it doesn’t, check the log under logs/; the loader writes a line per pack it finds or skips.

If the pack is listed but a girl has no images, it’s almost always a folder-name mismatch (case-sensitive) or images in the wrong subfolder.

7. Share

Zip the pack folder. Name the zip after your pack and its version (MyPack-v1.0.zip). Include a short README so players know what’s inside. Post wherever your community lives.

Include a text file describing the licence terms you want; see the spec for notes on redistribution.

Consumables (optional, 1.12+)

If your pack includes Food-type items that should fire automatically during a girl’s shift, use the 1.12 consumables schema. A consumable can drop a stat, grant a temporary trait, or trigger a named trait after enough lifetime uses, all without a Lua script.

The simplest possible consumable is a food item with a <use> block and an <auto_use> condition. The canonical example (Coffee + Caffeine Addict) is worked through step-by-step in examples/items-cookbook.md. The full attribute and effect reference is in reference/items-reference.md#consumables-112.

Add RequiresEngine="1.12.0" to your package.xml if any item in your pack uses the new schema.

Custom scripts (optional)

If you want a girl to have a custom encounter, dialogue, or branching event, add a triggers.xml and a .lua file to her folder:

Characters/Jane/
    Profile/
        portrait.jpg
    triggers.xml
    MeetGirl.lua

Editor setup, the script lifecycle, and API reference are covered in reference/lua-scripting.md. Skeletons are in snippets/triggers.xml and snippets/MeetGirl.lua.

VS Code with the sumneko Lua extension gives you autocomplete and type checking for the whole wm.* API; point it at the game folder and it picks up Resources/Scripts/definitions/wm.lua automatically.

Job data (optional, v1.11+)

If your pack includes custom job data, the engine reads one directory per job from resources/Jobs/<id>/. Each directory can contain up to six files: job.xml (required), effects.xml, performance.xml, wage.xml, gains.xml, and a messages/ folder for shift text. Jobs that earn gold need performance.xml and wage.xml; training and rest jobs usually need only effects.xml.

Three worked examples, from a simple rest job through to a parameterized multi-slot job, are in examples/jobs-cookbook.md. The full attribute and element reference is in reference/jobs-reference.md. Copy-paste starters for the most common effect patterns are in snippets/effects.xml.

Next steps

• reference/ pages for the fields you didn’t understand.
• reference/when-conditions.md: eligibility gates for jobs, text variants, factors, and trait gains.
• reference/jobs-reference.md: full schema reference for job data directories.
• examples/jobs-cookbook.md: three worked job recipes.
• examples/items-cookbook.md for common consumable recipes.
• examples/common-mistakes.md for the traps every first pack falls into.