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 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: a manifest whose File= paths have drifted from disk reality (typos, leftover entries from a reorg, files listed in a layout that no longer matches).

The manifest is additive, not an allowlist: 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 rather than dropping silently. So a drifted manifest no longer hides your images, but its broken entries are worth cleaning up. Run the pack validator (tools/pack-validator/pack-validator.exe path/to/your/pack) and it will tell you exactly which manifest entries don’t resolve.

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 file the installer accepts is a <Package> with a non-empty Id, and the Id must be the same as the folder name:

<Package Id="MyPack" Name="My Pack" />

A bare <Package/> is refused by the drag-and-drop installer (“missing a non-empty Id attribute”). Dropped in by hand, it loads characters, traits and items but silently skips the pack’s jobs and buildings. See package.xml reference.

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. If you meant to give an existing character more art, engine 1.20 has no way to do it from another pack: her own folder is closed to everyone but the pack that ships her. What an addon can do is supply fallback art; see Package roles.

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 88 types in ImageTypes.xml and isn’t one of the recognised aliases.

Fix: either rename to a recognised category (see filename-cheatsheet), 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" Type="finger" Participants="solo" />

Using Type= to move an image out of its folder

Symptom: an image turns up in scenes you never meant it for. Nude art appears during advertising or cooking, farm art during beast scenes, lesbian art in ordinary sex scenes.

Cause: a manifest Type= adds a category, it does not swap one. An image in advertise/ with Type="nude" ends up as both advertise and nude, so it is offered for both. There is no way to remove the category an image gets from its folder.

Fix: move the file into the folder you want it in. Keep Type= for adding a second category that genuinely fits the same picture, such as a position on an image already in sex/, or oral on a deepthroat shot.

Worth knowing alongside it: most scene requests do not check who is in the picture. Only Lesbian and Group scenes do. So a lesbian image that also carries an everyday category will be offered for everyday scenes, while the reverse does not happen.

Threesome images tagged for Group scenes

Symptom: you put threesomes in group/ with Participants="ffm" or "mmf" and they never appear in group scenes.

Cause: group scenes accept only gangbang and orgy. A threesome counts as ordinary sex. Writing Participants in the manifest also replaces what the folder said, so the image stops being a group picture entirely: it serves ordinary sex scenes instead and is never offered for a group one.

Fix: decide which it is. Leave it tagged ffm or mmf and let it serve ordinary sex scenes, or tag it gangbang if you want it in group scenes. The same applies in lesbian/: a non-lesbian Participants value there moves the image out of lesbian scenes and into ordinary ones, which is rarely what anyone intends.

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. 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.

Id in package.xml does not match the folder name

Symptom: the pack’s characters, traits and items load, but its jobs never appear in any building and its building definitions do nothing. gamelog.txt says the declared Id differs from the folder name.

Cause: the game identifies a pack by its folder. When Id="marina_pack" sits in a folder called Marina/, everything that is addressed by pack id (jobs, buildings, heritage) is skipped.

Fix: make the folder name and the Id identical. The drag-and-drop installer always creates the folder from the Id, so this only happens to packs copied in by hand or renamed afterwards.

Expecting RequiresEngine to warn players

Symptom: a player on an older game version installs your pack and gets silently broken items or traits instead of a warning.

Cause: the game does not read RequiresEngine. Only the pack validator does, to check your pack against the version you declared.

Fix: still declare it (the validator’s version-gated checks need it), and also state the minimum game version in your pack’s README or download page, because that is the only place a player will see it.

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.