Common mistakes

The traps every first pack falls into, and how to avoid them.

Random girls have no images

Symptom: every random girl who shows up in the slave market, in your brothels, or via gang capture loads with placeholder art (or no portrait at all). Named girls work fine; only the procedurally-generated ones are blank.

Cause: pack authors typically ship images for named .girlsx girls but not for .rgirlsx templates. None of the shipped sample packs image their random templates, so the convention isn’t obvious from reading examples. The mechanism is real and has been in the engine all along.

Fix: random girls load images from Characters/<TemplateName>/ exactly the same way named girls do. The template’s <Girl Name="..."> attribute is the folder name.

Concrete steps:

1. Open RandomGirls.rgirlsx (or your pack’s equivalent) and find the template you want to image. Note the Name= attribute, e.g. <Girl Name="Spunky Girl" ... >.
2. Create Characters/Spunky Girl/ beside the .rgirlsx (or <YourPack>/Characters/Spunky Girl/ for a pack layout).
3. Drop images in using the standard conventions. Profile/, Sex/, Anal/ subfolders, or profile01.jpg / sex01.jpg filename prefixes. Same rules as named girls.

Every random girl spawned from that template will load those images. The pack validator (1.14.2+) reports an INFO line for every template missing an image folder; run it once and you’ll get a checklist of templates worth imaging:

info: Random template 'Spunky Girl': no image folder at 'Characters/Spunky Girl/' ...

Shared-folder caveat. All “Spunky Girl” spawns share the same image folder, so if you have ten of them running around the brothel they’ll all look identical. For visual variety, ship multiple templates with distinct names (Spunky Girl 1, Spunky Girl 2, …). Each gets its own folder. Same stats and skill ranges, different Name= and folder. Crude but functional, and matches how named girls work.

A “one template, pool of N image variants per spawn” feature does not exist today. It’s on the long-term roadmap.

I added images.xml and lost all my images

Symptom: a pack that worked fine without an images.xml suddenly shows zero images for the affected girls after you add one. The Content Manager still reports the on-disk file count correctly, but the slave market, brothel overview, girl details, and gallery all come up empty.

Cause: releases before 1.14.4 treated images.xml as a strict allowlist. Any file not listed in the manifest was silently invisible to the engine, even if it was sitting in a known folder like Profile/. If your manifest’s File= paths drifted from disk reality (typos, leftover entries from a reorg, listing files in a layout that no longer matches), the engine would happily load zero images and give you no warning anywhere.

This was a documentation bug. The docs always promised additive behavior, but the engine did the opposite. As of 1.14.4 the engine matches the docs. The manifest is additive: files on disk that match a manifest entry pick up its tags as an overlay, files not listed fall back to folder/filename inference, and manifest entries pointing at files not on disk surface as pack-level warnings instead of dropping silently.

If you’re on 1.14.4 or newer: the symptom shouldn’t happen any more. If it does, run the pack validator (tools/pack-validator/pack-validator.exe path/to/your/pack). It will tell you exactly which manifest entries don’t resolve.

If you’re shipping a pack for a 1.14.3-or-older audience: the allowlist trap is still live. Either list every image you want loaded in images.xml, or delete images.xml entirely and rely on folder/filename inference. The validator catches both cases.

Folder name doesn’t match the girl’s Name

Symptom: the girl loads in the Content Manager but has no images. Every scene shows placeholder art.

Cause: Characters/ subfolder name differs from the Name attribute, usually by case (Jane vs jane), spacing, or a stray character.

Fix: the folder name must match Name exactly. It is case-sensitive. “Jane Doe” with a space works; so does underscore or hyphen, as long as both sides agree.

Missing package.xml

Symptom: the pack never appears in the Content Manager at all. Log shows Skipping <PackName> (no package.xml).

Cause: the loader treats package.xml as the pack marker. Without it, your folder is invisible.

Fix: create package.xml. The smallest valid file is <Package/>.

Status="Normal" on slave-market girls

Symptom: your girl loads fine but never shows up in the caravan.

Cause: the slave market only lists girls with Status="Slave". Default is Normal, which means “not for sale”.

Fix: set Status="Slave" on each <Girl> you want in the caravan.

Images in the wrong folder depth

Symptom: Content Manager counts fewer images than you have.

Cause: the scanner walks one level deep. Files in Characters/Jane/Profile/Extras/subfolder.jpg are ignored. Only Characters/Jane/Profile/image.jpg and Characters/Jane/image.jpg are seen.

Fix: keep images at the top of the girl folder or one level inside a category subfolder. No deeper.

Duplicate girl names across packs

Symptom: one of your girls doesn’t show up, or shows with the wrong images.

Cause: two packs define a girl called “Jane”. The game keeps both as separate entries but their folders compete. If folder names collide, one wins.

Fix: rename. Or use the addon mechanism if you meant to extend an existing girl. See pack-format.md addon rules.

Duplicate item or trait names

Symptom: your custom item/trait never works; core or another pack’s version is used.

Cause: core content always wins. For pack-vs-pack, first-loaded wins.

Fix: pick a unique name. Grep Resources/Data/Traits/ and Items.itemsx before choosing.

Filename prefix buried inside a category folder

Symptom: you put profile01.jpg inside Sex/ and it’s being used for sex scenes.

Cause: subfolder wins over filename prefix. If it’s in Sex/, it’s a Sex image, regardless of filename.

Fix: either move the file to Profile/ (or the girl root), or rename it to not have a misleading prefix.

Unrecognised category

Symptom: files show up in the Gallery’s <UNMATCHED> row and never appear in scenes.

Cause: your folder or prefix isn’t one of the 86 types in ImageTypes.xml and isn’t one of the recognised aliases.

Fix: either rename to a recognised category (see filename-cheatsheet.md), tag the files explicitly with an images.xml manifest, or add a new type to ImageTypes.xml if you’re defining a whole new kink.

FootJob / HandJob / Masturbation folders are unmatched

Symptom: you put images in FootJob/, HandJob/, Masturbation/, or FingerSolo/ and they end up in the Gallery’s <UNMATCHED> row.

Cause: those folder names look obvious but aren’t in the catalog. The catalog uses the bare names foot, hand, finger. There are no -job or -solo aliases.

Fix: rename folders to Foot/, Hand/, Finger/. For solo masturbation specifically (no partner), keep Finger/ and add a manifest entry per file:

<Image File="Finger/solo01.jpg" types="finger" participants="solo" />

Lesbian / Group images don’t get their own Gallery row

Symptom: you put images in Lesbian/ or Group/ and they show up under the Sex row instead of as separate Lesbian / Group rows.

Cause: this is by design from 1.10 onward. Lesbian and Group are participant tags on sex images, not catalog types. The Gallery groups by type only; participant is a separate filter.

Fix: nothing; it’s working. To see only the lesbian images in the Sex row, cycle the Participants filter at the top of the gallery from Any to Lesbian. To see only group images, cycle to Gangbang / Lesbian Group / Orgy depending on shape. Scene picking (whore job, customer events) finds these images correctly without any extra effort.

Missing engine version requirement

Symptom: pack uses 1.11-only features (like PregAdvance items), players on 1.10 silently get broken items.

Cause: no RequiresEngine declared.

Fix: set RequiresEngine="1.11.0" on <Package>. The engine will warn older versions they need to update.

XML not well-formed

Symptom: pack doesn’t load, log shows a TinyXML parse error with a line number.

Cause: unescaped ampersand, unclosed tag, smart quotes copy-pasted from Word.

Fix: run the pack validator (tools/pack-validator/pack-validator.exe). It prints the line and column of the first error.

Images too large

Symptom: game runs slow on load; girl folder takes forever to scan.

Cause: 20MB PNGs.

Fix: nothing game-breaking, but consider resizing large art to something reasonable (1920 wide at most for full scenes, 512 wide for profile thumbnails). JPEG or WebP compresses much better than PNG for photographic art.

Not testing with the validator

Symptom: you find out about the bug when a player tells you.

Cause: you loaded the pack in-game and it worked for you.

Fix: always run the validator before shipping. It catches XML, path, and schema problems the game might silently tolerate.