Image types

The engine recognises 86 image types defined in Resources/Data/ImageTypes.xml. Every type doubles as a subfolder name and filename prefix. Adding a new type is a one-line XML edit with no code change.

How to read the catalog

Each entry in ImageTypes.xml looks like:

<Type Name="bdsm">
    <Display>BDSM</Display>
    <Description>Any sort of BDSM sex act.</Description>
    <Fallback TiedUp="yes" Cost="25">anal</Fallback>
    <Fallback Cost="25">spanking</Fallback>
</Type>

Name — lowercase string used for folder matching and filenames.
Display — pretty name shown in the Gallery.
Description — tooltip text in the tagger.
Fallback — if no image of this type is available, try these in Cost order.

Fallbacks

When the game asks for an image of type X and the girl has none, it walks the fallback graph defined in ImageTypes.xml until it finds something. Every fallback has a cost; cheaper fallbacks are preferred.

Default cost is 10.
Switching between pregnant and non-pregnant variants costs 5 on top.
TiedUp="yes" means the fallback only applies if the girl is in a bound state.
RequiredParticipants="lesbian" (and similar) scopes a fallback to a specific scene shape.

The last-resort fallback is always profile. If nothing else matches, the engine picks any profile image.

The 4 axes

Images have up to four axes of metadata beyond the base type:

Axis	Values	Where
`types`	One or more names from the catalog	Filename prefix or subfolder
`pregnant`	`yes` / `no` / (unspecified)	`preg` prefix or `Preg*` folder
`tied`	`yes` / `no` / (unspecified)	Manifest only (no filename convention)
`participants`	`solo`, `lesbian`, `group`, etc.	Manifest only

The base categories (prefix / folder names) set types and pregnant. For finer control — tied-up variants, participant scoping — use an images.xml manifest.

How the Gallery shows axes

The in-game Gallery is organised by the types axis only — one row per catalog type the girl has images for. pregnant, participants, and tied are filters applied across all rows, controlled by cyclers at the top of the gallery.

This matters for lesbian and group images. They are tagged types=sex with participants=lesbian or participants=gangbang, so they appear in the Sex row, not as their own rows. To narrow the Sex row to just lesbian or group art, cycle the Participants filter from Any to Lesbian / Lesbian Group / Gangbang / Orgy.

Pre-1.10 packs that relied on the legacy IMGTYPE_LESBIAN / IMGTYPE_GROUP buckets having their own gallery rows still work for scene picking; only the gallery presentation changed.

Multi-token filename inference

Filenames are split on _, -, ., and whitespace, then each token is matched against the catalog. All matches apply. So preg_foot_cumshot.jpg infers foot and cumshot types and pregnant=yes without needing a manifest entry. Authors who want to override or extend this can still write entries in images.xml per the rules below.

This means well-named multi-tag files just work. You only need the manifest when the filename alone cannot express what you need (tied-up variants, participant shapes, or filenames you can’t rename).

The `images.xml` manifest

Drop an images.xml file inside a girl’s Characters/<Name>/ folder to attach explicit per-image metadata that filename or folder inference can’t express.

<Images>
    <Image File="Profile/portrait01.jpg" types="profile" pregnant="no" />
    <Image File="BDSM/tied01.jpg" types="bdsm" tied="yes" />
    <Image File="group01.jpg" types="group" participants="group" />
</Images>

The manifest is additive, not an allowlist. The engine walks the disk regardless of whether images.xml is present. Files on disk that match a manifest entry get the manifest’s tags overlaid on top of folder/filename inference (manifest wins on conflict; types are unioned). Files on disk not listed in the manifest still load. They pick up tags from the standard folder/filename inference. Manifest entries that point at files not on disk are flagged as pack-level warnings.

This means you only need to list the handful of files whose tags can’t be expressed by their filename or parent folder. Everything else picks itself up.

Use the manifest when:

You want tied-up variants (no filename convention for this).
Your filenames don’t follow the prefix convention.
You want multi-axis tags that can’t be expressed in a prefix.

For most packs, filename prefixes and subfolders are enough.

Behavior change note. Releases before 1.14.4 treated images.xml as an authoritative allowlist: any file not listed was silently invisible to the engine, even if it was sitting in a known folder like Profile/. Authors who relied on the (documented) additive behavior hit confusing zero-image-load failures. As of 1.14.4 the engine matches what this doc describes; older versions don’t. If you’re shipping a pack for a 1.14.3-or-older audience, make sure every image you want loaded is listed in images.xml, or delete the manifest entirely so folder/filename inference runs.

What the engine actually requests

The 86-entry catalog is the authoring surface: folder names, filename tokens, gallery rows, fallback graph. It is not the same as the request surface — the set of tag names that a shipped job, event, or screen actually asks for at runtime. If you only care about the gallery looking complete, the catalog is enough. If you care about which images display during gameplay, read on.

Two layers sit between a catalog tag and a real on-screen request:

<DefaultImage> in a job’s job.xml. Every data-driven job declares a default tag for its shift event. Only the values listed below appear in shipped jobs.
The engine bridge that maps the declared string to an internal image slot. Names the bridge does not know silently fall back to profile.

Tags routed all the way through (display correctly today)

These trigger a distinct image lookup during gameplay. If you author images for these tags, they will show up in shift events, dungeon panels, brothel summaries, etc.

profile — the universal default; shift events, status views, fallbacks all end here
sex — whore / barwhore default, plus generic sex shifts; participant filters narrow it to lesbian / group variants
anal, oral, bdsm, beast — requested when whore-class jobs route to specific acts
titty, hand, foot — per-act buckets for breast / hand / foot scenes (1.15.5+; reachable via per-<Text> Image= override)
pregnant — auto-applied when the girl is pregnant, with per-act preg variants for the five above
death — death events (brothel danger reports, dungeon)
torture, jail — dungeon screen image panel
combat — Arena fight jobs (Fight Beasts, Fight Girls, Combat Training)
strip — Brothel Stripper
Job-shift buckets (1.15.5+): wait, piano, ecchi, escort, massage, advertise, maid, cook, study, herd, bed, craft, rest, security, formal, dom, puppygirl, masturbate. Each non-whore data-driven job now declares one of these as its <DefaultImage> so the Waitress shows wait, the Cook shows cook, the Masseuse shows massage, and so on. Pack art for any of these tags lights up during the matching job’s shift events.

Lesbian and group are not separate request tags any more; they are sex tagged with participants=lesbian / participants=gangbang. Author them as such.

Per-job image lookup

Useful for batch-generation workflows (ComfyUI, Stable Diffusion) that want a “given job, what filename prefix” lookup without grepping each job.xml. Every shipped data-driven job and its current <DefaultImage>:

Job	Prefix	Job	Prefix
advertising	`advertise`	hall	`wait`
arenacleaner	`maid`	headgirl	`formal`
barcook	`cook`	houserecruiter	`formal`
barmaid	`wait`	houserest	`rest`
barsinger	`piano`	houseso	`study`
barstripper	`strip`	jeweler	`craft`
barwhore	`sex`	masseuse	`massage`
basictraining	`study`	matron	`formal`
beastcapture	`combat`	mistress	`dom`
beastcare	`herd`	peepshow	`strip`
bedwarmer	`bed`	performer	`glory`
blacksmith	`craft`	pet	`puppygirl`
brothelstripper	`strip`	piano	`piano`
cityguard	`security`	security	`security`
clean	`maid`	sleazybarmaid	`ecchi`
cobbler	`craft`	sleazywaitress	`ecchi`
cook	`cook`	torturer	`dom`
doctore	`combat`	training	`study`
escort	`escort`	waitress	`wait`
explorecatacombs	`combat`	whore	`sex`
fakeorgasm	`ecchi`
fightbeasts	`combat`
fightgirls	`combat`
fighttrain	`combat`
freetime	`rest`

Several jobs share a prefix (every fight job uses combat, every craft job uses craft), so a single piece of art covers multiple jobs. The pet job currently shares puppygirl art; if you want pet-specific art, generate it tagged puppygirl and it will light up on pet shifts (and any other shift that requests puppygirl).

Per-outcome image override on shift messages (1.15.5+)

A single message bag can paint different portraits for different outcomes. The Masseuse bag’s happy-ending variant overrides her massage default with oral or sex; a Waitress refusal arm can paint refuse while the work line keeps wait. Add Image="..." directly on the <Text> element:

<Text id="masseuse.work.horny.oral.1" weight="1" Image="oral">
    ...
</Text>

Same vocabulary as <DefaultImage>. Unknown tags degrade to profile just like <DefaultImage> does. See reference/jobs-reference.md — per-outcome image override — for the full schema.

Tags that exist only in the catalog

Everything else in ImageTypes.xml is still catalog-only. That means:

They appear as gallery rows so authored images are browsable.
They participate in the fallback graph, so a richer pack with dance images can still satisfy a future dance request, and a bdsm request can fall back through spanking if you have those.
They do not match any shipped <DefaultImage> today, so no shift event currently asks for them by name.

These are not dead — they are the future-facing surface. As more jobs become data-driven and the legacy bridge is extended, more of them will start being requested directly. If you are pacing your authoring effort, prioritise the “routed” tags above; treat the catalog-only tags as embellishment until a release notes them as wired.

How to check what your install asks for

To see which tags the shipped jobs in your install actually declare, list the <DefaultImage> lines under Resources/Jobs/:

grep -h "<DefaultImage>" Resources/Jobs/*/job.xml | sort -u

The catalog itself lives at Resources/Data/ImageTypes.xml. The “routed” list above will be republished in the release notes whenever the bridge gains a new tag.

Adding a new type (single install only — not pack-portable)

Important: as of the current release, image types cannot be shipped from a pack. The only way to add a new type is to edit the engine-shipped Resources/Data/ImageTypes.xml in your own install. This is fine for single-player tinkering, useless for pack authoring. Pack-extendable image types are on the roadmap but not yet released (see Docs/roadmap/future.md — “Pack-extendable image-type catalog” — in the game repo). Until that ships, every player who installs your pack would also need to apply the same ImageTypes.xml edit by hand, and your edit gets overwritten on the next game update.

If you accept those limits and want to add a type to your own install:

Add a <Type> block to Resources/Data/ImageTypes.xml.
Give it a Name, Display, Description, and at least one Fallback so it degrades gracefully.
Restart the game. The engine auto-picks up the new type as both folder and prefix.

A type added this way will appear as a folder/prefix the engine recognises and as a gallery row, but it will not trigger an in-game image request unless an existing shipped job or message bag asks for it by name (see “What the engine actually requests” above). To actually surface a brand-new type during gameplay, you would also need engine changes — that is the work tracked under the deferred pack-extendable-types entry.

The full 86-entry catalog is the source of truth. Read it when in doubt.

Shipping art as a standalone overlay pack

If you want to author default art for the new job-shift buckets (or replace the shipped defaults wholesale) without touching individual girl folders, drop the images into a pack at Characters/Default/. See where-packs-go.md — “Default-image overlay packs” — for the directory layout, supported subfolder names, and the filename-prefix aliases for older WMR / WM7 art (Dominatrix (N).jpg for dom, Advertisement (N).jpg for advertise, Mast (N).jpg for masturbate).