Items reference

Items live in Items.itemsx files. One file can hold any number of items. Pack items are pooled with the core item list at load time.

Item structure

<Item
    Name="Lucky Charm"
    Desc="A small trinket that brings good fortune. (+10 Confidence)"
    Type="Necklace"
    Badness="0"
    Special="None"
    Cost="500"
    Rarity="Shop25"
    Infinite="false"
    GirlBuyChance="10">
    <Effect What="Stat" Name="Confidence" Amount="10" />
</Item>

Attributes

Attribute	Required	Purpose
`Name`	Yes	Unique display name. Used everywhere.
`Desc`	Yes	Shown in inventory and shop tooltips.
`Type`	Yes	Slot. See below.
`Cost`	Yes	Gold price in shop. See pricing.md for how the engine applies markups and discounts on top of this base value.
`Rarity`	Yes	Where and how often it appears. See below.
`Badness`	No	Moral weight of owning/using. Default 0.
`Special`	No	`None`, `AffectsAll`, or `Temporary`. Default `None`. See below.
`Infinite`	No	`true` = stockable, never runs out. Default `false`. Write `true` or `false`, exactly: anything else (`True`, `TRUE`, `tru`) the validator reports as an error, and the game logs at load and treats as off.
`GirlBuyChance`	No	0-100: chance the girl buys it herself with her cut.
`Once`	No	`true` = a consumable that changes a character once. See below. Default `false`. `true` or `false` exactly, as for `Infinite`. Game 1.21, unreleased.

`Once="true"`: one use per character (game 1.21, unreleased)

For a consumable (Food, Makeup, or an item with a <use> block): the first use on a character applies as usual and is remembered for her, by item name. A second use on the same character is refused with a message and the item is not used up. Shedding a trait the item granted does not reopen it for her; another character may still use it. The record is by name, so a renamed item is a new item. The shipped example is the Tiger Shark Tooth in Items.itemsx.

One fact to keep in mind when writing effects: the engine has no Strength stat. Trait files that say strength are read as Combat, and no item can raise a stat that does not exist; Strong is a trait, earned by Constitution.

Item types (slots)

Values the engine accepts:

Type	Slot
`Ring`	Finger (up to 8)
`Dress`	Full-body clothing (1)
`Shoes`	Feet (1)
`Food`	Consumable, single use
`Necklace`	Neck (1)
`Weapon`	Combat weapon (up to 2)
`Makeup`	Face, single use
`Armor`	Body armor worn over dress (1)
`Misc`	Anything that doesn’t fit a slot; effect applies passively
`Armband`	Arms (up to 2)
`Small Weapon`	Small hidden weapon (1)

Rarity

Controls where and how often the item shows up. Values the engine accepts:

Value	Means
`Common`	Appears freely in the normal shop
`Shop50`	50% chance in the normal shop
`Shop25`	25% chance in the normal shop
`Shop05`	5% chance in the normal shop
`Catacomb15`	15% chance as a catacomb reward
`Catacomb05`	5% chance as a catacomb reward
`Catacomb01`	1% chance as a catacomb reward (very rare)
`ScriptOnly`	Never randomly generated; only awarded by script
`ScriptOrReward`	Like `ScriptOnly`, but also awarded for objectives

`Special` attribute

Accepted values:

Value	Means
`None`	Default. No special behaviour.
`AffectsAll`	Effects apply to the whole brothel, not just the wearer
`Temporary`	Item is consumed on use

`<Effect>` elements

An item can have any number of effects. Each is applied when the item is equipped (or consumed, for food). The engine parses three attributes: What, Name, Amount.

`What`	What it does	`Name` expects
`Stat`	Modify a stat by `Amount`	A stat name (see below)
`Skill`	Modify a skill by `Amount`	A skill name (see below)
`Trait`	Add a trait (`Amount >= 0`) or remove (negative)	A trait name
`GirlStatus`	Give or suppress a girl status (see below)	A status name
`PregAdvance`	Advance or delay pregnancy in weeks	`WeeksPreg`

No Chance or Duration attributes. The engine ignores them. Effects are always permanent while the item is equipped, and always fire. If you need probabilistic or time-limited behaviour, do it via a Lua script instead of an item effect.

Stat and skill names

Name must match the engine’s own spelling exactly. The accepted values:

Stats: Charisma, Happiness, Libido, Constitution, Intelligence, Confidence, Mana, Agility, Fame, Level, AskPrice, House, Exp, Age, Obedience, Spirit, Beauty, Tiredness, Health, PCFear, PCLove, PCHate.

Skills: Anal, Magic, BDSM, NormalSex, Beastiality, Group, Lesbian, Service, Strip, Combat, Performance, Farming, AnimalHandling, Crafting, Herbalism, Brewing, Cooking, Medicine, OralSex, TittySex, Handjob, Footjob. Eleven of these arrive with game 1.21, which is not released yet, and they are not all in the same state. OralSex, TittySex, Handjob and Footjob are already weighed by the Escort job, so setting them does change a shift. The seven occupational skills (Farming, AnimalHandling, Crafting, Herbalism, Brewing, Cooking, Medicine) are accepted everywhere but no job reads them yet, so setting one changes nothing in a shift until the Farm jobs are wired to them.

Spellings that catch authors out: the skill is NormalSex with no space, Beastiality carries the extra “a” the engine uses, and AnimalHandling is one word. There is no Oral skill.

An unknown name drops that effect. If Name does not match a known stat, skill, or status, the game discards that one <Effect> and writes the bad name to the log. The rest of the item still works normally. Earlier versions kept the effect and silently aimed it at the wrong attribute (a mistyped skill landed on Anal), so an effect that seems to do nothing, or changes the wrong skill, is almost always a misspelled Name.

Girl statuses (`GirlStatus`)

A status is an on/off condition on a girl, separate from stats and traits. Your items can give or suppress any of the engine’s statuses, which is how the base game’s mind-control jewelry works, and you can make your own items that do the same. What you cannot do from a pack is invent a brand new status: the list of statuses lives in the engine, so a Name outside this list is dropped like any other unknown name.

The accepted names, spelled and spaced exactly like this (statuses are stricter about spelling than stats):

None, Poisoned, Badly Poisoned, Pregnant, Pregnant By Player, Slave, Has Daughter, Has Son, Inseminated, Controlled, Catacombs

Amount picks the direction for most statuses:

Amount="1" gives the status.
Amount="0" suppresses the status.

The pregnancy family is not a plain switch. For Pregnant, Pregnant By Player, and Inseminated, Amount on a giver feeds the engine’s conception logic (it acts as a chance input, runs the real impregnation roll, and prints its own outcome message), and using a remover carries a small chance of leaving the girl Sterile. Treat these three as fertility items with their own rules, not as on/off bits. The rest of the list behaves as a plain switch.

How long it lasts follows the item, the same way it does in the base game:

On an equippable item (ring, necklace, armband…), the status holds while the item is worn and reverses on unequip.
For a consumed (permanent) status change, copy the shipped Brainwashing Oil recipe: Type="Food" with Special="None". The girl eats it, the status sticks, and there is nothing to take off.

Do not put GirlStatus on a Special="Temporary" item. The temporary-item path applies stats and skills through the self-fading channels and deliberately skips GirlStatus effects, so the status is silently never applied. Type="Food" with Special="None" is the working consumable recipe.

Controlled is the one with real gameplay teeth (1.18.1+). A Controlled girl does not refuse work: control overrides her own objections, including fear, hate, and dignity, but it never overrides your own conduct policy, a customer walking away, or a job’s hard requirements. The base game’s Necklace of Control and Disguised Slave Band are “while worn” givers, the brainwashing consumables are permanent, and the Epic Necklace and Epic Bracer of Babeosity are “while worn” suppressors. Your own control items slot into the same rules automatically.

Unequip semantics (1.18.1+): when a status item comes off, the engine consults the girl’s other worn items instead of blindly flipping the bit. Removing a giver keeps the status if another worn item still grants it, so two givers stack safely. Removing a suppressor restores the status only if a worn item actively grants it; a suppressor worn and removed on a girl who was never given the status leaves her untouched. One honest limitation remains: a status granted by a consumable has no item backing it afterwards, so wearing and removing a suppressor over it clears it permanently, and the engine cannot tell a consumable-granted status from one granted by an item she has since taken off.

Conditional effects: `<When>` on `<Effect>` (1.15.5+)

Add a <When> child to an <Effect> to gate that one effect on properties of the wearer. The effect contributes only while both the item is equipped (or consumed, for food) and the condition is satisfied. An item can mix unconditional and conditional effects in the same <Item> block, and each conditional effect is independent of the others.

<Item Name="Aggressor's Ring" Desc="+15 Combat for fighters." Type="Ring"
      Cost="600" Rarity="Shop25" Infinite="false">
    <Effect What="Stat" Name="Combat" Amount="15">
        <When><Trait id="Aggressive"/></When>
    </Effect>
</Item>

The condition is re-checked whenever the engine resolves the wearer’s effective stats. A ring that gates on <Stat name="Beauty" ge="80"/> starts contributing the moment her Beauty crosses 80 and stops the moment it drops back below, no equip / unequip needed.

<When> accepts the full condition grammar: leaves (<Trait>, <Stat>, <Skill>, <Status>, <Girl name="...">, <TraitCategory>, etc.) and combinators (<All>, <Any>, <None>, <Not>). See when-conditions for the complete reference.

Patterns

Signature gear: only works for one named heroine.

<Item Name="Alice's Pendant" Desc="+20 Charisma, but only for Alice."
      Type="Necklace" Cost="2000" Rarity="ScriptOnly" Infinite="false">
    <Effect What="Stat" Name="Charisma" Amount="20">
        <When><Girl name="Alice"/></When>
    </Effect>
</Item>

Anti-affinity: everyone except one girl.

<Item Name="Cursed Locket" Desc="A heirloom only one girl can stomach."
      Type="Necklace" Cost="800" Rarity="Shop05" Infinite="false">
    <Effect What="Stat" Name="Happiness" Amount="-50">
        <When><Not><Girl name="Alice"/></Not></When>
    </Effect>
</Item>

Trait-conditional skill bonus.

<Effect What="Skill" Name="Combat" Amount="10">
    <When>
        <Trait id="Aggressive"/>
        <Stat name="Spirit" ge="40"/>
    </When>
</Effect>

Anti-shyness ring: buffs Charisma only when the girl is not Shy.

<Effect What="Stat" Name="Charisma" Amount="15">
    <When><Not><Trait id="Shy"/></Not></When>
</Effect>

If a <When> fails to parse (unknown leaf, missing comparison op, malformed combinator), the bad <Effect> is dropped and the failure is written to the log: the rest of the item still works the same way an unknown Name is handled.

Tags (1.15.6+)

Add any number of <Tag> children to an item to label it. Tag names are free text; the game keeps the set of distinct tags on each item, and a worker “has” a tag when any item in her inventory carries it, worn or not.

<Item Name="Officer's Sabre" Desc="A regulation blade." Type="Large Weapon" Cost="900">
    <Effect What="Stat" Name="Combat" Amount="10" />
    <Tag>military</Tag>
    <Tag>quality</Tag>
</Item>

Job definitions can test for a tag with <When><HasItemTag tag="quality"/></When>. Tags do nothing on their own; they are a hook for jobs and packs to react to what a worker carries.

Worked examples

A simple stat-boost necklace:

<Item Name="Charm of Grace" Desc="+5 Agility" Type="Necklace"
      Cost="300" Rarity="Shop25" Infinite="false">
    <Effect What="Stat" Name="Agility" Amount="5" />
</Item>

A consumable with a side effect:

<Item Name="Confidence Tonic" Desc="+15 Confidence, leaves her exhausted."
      Type="Food" Special="Temporary" Cost="150" Rarity="Shop25" Infinite="false">
    <Effect What="Stat" Name="Confidence" Amount="15" />
    <Effect What="Stat" Name="Tiredness"  Amount="20" />
</Item>

A trait-granting item:

<Item Name="Training Whip" Desc="Teaches submission over time."
      Type="Misc" Cost="200" Rarity="ScriptOnly" Infinite="true">
    <Effect What="Trait" Name="Meek" Amount="0" />
</Item>

A high-Badness item with a trait side effect:

<Item Name="Slave Collar" Desc="A heavy iron collar."
      Type="Necklace" Cost="100" Rarity="Shop25"
      Badness="5" Infinite="false">
    <Effect What="Stat"  Name="Happiness" Amount="-10" />
    <Effect What="Trait" Name="Meek"      Amount="0" />
</Item>

A pregnancy potion:

<Item Name="Midwife's Brew" Desc="Brings labour on by about a month."
      Type="Food" Special="Temporary" Cost="400" Rarity="Shop05" Infinite="false">
    <Effect What="PregAdvance" Name="WeeksPreg" Amount="4" />
    <Effect What="Stat"        Name="Tiredness" Amount="15" />
</Item>

Consumables

The engine supports a richer item schema that lets a girl consume an item mid-shift and react automatically. This is data-only; no Lua required for the common case.

The new schema at a glance

Old items use <Effect What="Stat" .../> child elements. New consumables use a <use> block instead:

<Item Name="Coffee" Type="Food" Cost="20" Rarity="Shop50" Charges="3" Badness="0"
      Desc="A strong cup of black coffee. Pushes back exhaustion for a few hours.">
    <use narration="{girl} took a long drink of her Coffee.">
        <effect type="stat" name="tiredness" value="-15"/>
        <effect type="stat" name="charisma"  value="3" weeks="1"/>
    </use>
    <auto_use when="tiredness &gt; 80" cooldown="3 events"/>
    <on_use_count count="20">
        <effect type="grant_trait" name="Caffeine Addict"/>
        <event>{girl} reaches for the coffee tin more than the till these days.</event>
    </on_use_count>
    <refusal type="stat_min" name="obedience" value="40"/>
</Item>

Key differences from old items

Feature	Old schema	New schema
Effects	`<Effect What="Stat" Name="X" Amount="N"/>`	`<effect type="stat" name="X" value="N"/>` inside `<use>`
Duration	Not supported	`weeks="N"` on any effect
Auto-fire	Not supported	`<auto_use when="..." cooldown="..." phase="..." source="..." priority="N"/>`
Refusal logic	Not supported	`<refusal type="..."/>`
Threshold events	Not supported	`<on_use_count count="N">`
Charges per stack	Always 1	`Charges="N"` attribute

Both schemas can coexist in the same .itemsx file.

New attributes

Attribute	Purpose
`Charges="N"`	Uses per copy before the item disappears. Default 1.

Effect types inside `<use>`

`type=`	`name=`	`value=`	`weeks=`	What it does
`stat`	Stat name (case-insensitive)	Signed int	optional	Instant modification (clamped 0-100). With `weeks=`: decays one week per turn.
`grant_trait`	Trait name	-	optional	Permanent trait. With `weeks=`: temporary.
`remove_trait`	Trait name	-	-	Removes the named trait from the consumer. See remove_trait.

Auto-use conditions

The when= string is a simple boolean expression:

tiredness > 80
health < 30
obedience >= 60

You can chain clauses with and or or (not both in the same expression):

tiredness > 80 and health > 20

Stat and skill names are case-insensitive.

Cooldown

cooldown="3 events": after firing, the item is blocked for 2 more events, then eligible again. Period = 3. A girl working 6 customers per shift using cooldown="3 events" can fire up to twice per shift.

Other units: "1 week" (once per turn), "lifetime" (once ever, per girl).

Refusal

Up to four refusal types: stat_min, stat_max, skill_min, skill_max, has_trait, lacks_trait. Multiple rules are OR-ed; any one match means she refuses.

Turn-end auto-use and shared inventory

By default an <auto_use> rule fires mid-shift, drawing from the girl’s own inventory. Three new attributes let the rule run once per turn instead, draw from the player’s shared item pool, and order multiple rules explicitly:

<auto_use phase="turn_end" source="either" priority="10">
    <When>
        <HasTrait name="Chlamydia"/>
    </When>
</auto_use>

phase= — when this rule may fire.

shift (default) — runs mid-shift, between work events. Use for stat-restorers (coffee, healing salves).
turn_end — runs once per girl per turn. Use for cure items that check a standing condition.

source= — which inventory the engine draws from.

girl (default) — the girl’s own 40-slot inventory.
shared — the player / shared item pool. Currently backed by the building’s general inventory; the name is intentionally future-facing so per-building inventories can reuse the same schema later.
either — girl inventory first, shared pool second when no girl-side item satisfies.

priority= — integer, default 50. Lower numbers are tried first when multiple rules could fire on the same call:

priority="10" — tried early (specific cures).
priority="50" — normal default.
priority="90" — fallback / last resort (multi-condition items like Elixir of Ultimate Regeneration).

Trait predicates: `<When><HasTrait>`

To check a trait inside an <auto_use> rule, add a <When> child with one or more <HasTrait> leaves. Multiple <HasTrait> children combine as AND.

<auto_use phase="turn_end" source="either" priority="10">
    <When>
        <HasTrait name="Chlamydia"/>
    </When>
</auto_use>

The string DSL when="..." and the <When> child are independent — both must pass when both are present. OR semantics are expressed by multiple <auto_use> blocks on the same item; the engine picks the matching block with the lowest priority.

A rule with neither when= nor <HasTrait> is invalid — the loader skips it with a warning. Coffee has when=; cures have <When>.

`remove_trait`

Removes the named trait from the consumer. Used by cures and condition-fix items.

<effect type="remove_trait" name="Chlamydia"/>

value= and weeks= are ignored. There is no timed-removal semantics — if the trait re-applies later (e.g. the girl re-catches the disease), that is the disease loop’s job, not the cure’s.

Encounter-script trigger (1.15.6+)

A consumable can launch a Lua script when it is used. Add a single <on_use_script> element naming a Lua file:

<Item Name="Genie Lamp" ...>
    <use narration="{girl} rubs the lamp. A column of smoke rises.">
        <effect type="stat" name="magic" value="2"/>
    </use>
    <on_use_script name="genie_grant.lua"/>
</Item>

The script fires after the <use> block applies effects, narration is written, and the charge is consumed. The girl who used the item is the script’s wm.girl. Inside the script you can call:

wm.give_player_random_special_item() – grant the player one rare item
wm.create_named_girl{...} – spawn a specific named girl from a template
any other wm.* API documented in [lua-scripting](/docs/pack-authoring/reference/lua-scripting/)

Path resolution: the engine looks for resources/packages/<your-pack>/scripts/<filename> first (lowercase scripts; case matters on Linux), then falls back to resources/scripts/<filename> for core scripts. If neither exists, a [consumables] warning is logged and the item still works (no script runs).

<on_use_script name="..."/> and <on_use_script>name</on_use_script> are both accepted.

Cross-reference

For ready-to-paste recipes, see items-cookbook.

Recipes

Recipe: Data-driven cure

A cure item that auto-applies when the girl has a specific condition, drawing from the player’s shared pool.

<Item Name="Chlamydia Cure" Type="Food" Cost="1000" Charges="1">
    <use narration="You had {girl} take a chlamydia cure. She loses some charisma but is cured.">
        <effect type="stat" name="Charisma" value="-5"/>
        <effect type="remove_trait" name="Chlamydia"/>
    </use>
    <auto_use phase="turn_end" source="either" priority="10">
        <When><HasTrait name="Chlamydia"/></When>
    </auto_use>
</Item>

The cure runs once per turn (phase="turn_end") and pulls from either the girl’s inventory or the shared pool (source="either"). Priority 10 means it fires before any priority-90 fallback that might also match the same condition.

Recipe: Multi-condition fallback

A universal cure that backs up multiple specific cures. Each condition gets its own <auto_use> block at priority="90", so specific cures (at priority="10") always run first when both are available.

<Item Name="Universal Cure" Type="Food" Cost="5000" Charges="1">
    <use narration="{girl} drinks a universal cure.">
        <effect type="remove_trait" name="Chlamydia"/>
        <effect type="remove_trait" name="Syphilis"/>
        <effect type="remove_trait" name="AIDS"/>
    </use>
    <auto_use phase="turn_end" source="either" priority="90">
        <When><HasTrait name="Chlamydia"/></When>
    </auto_use>
    <auto_use phase="turn_end" source="either" priority="90">
        <When><HasTrait name="Syphilis"/></When>
    </auto_use>
    <auto_use phase="turn_end" source="either" priority="90">
        <When><HasTrait name="AIDS"/></When>
    </auto_use>
</Item>

If both a Chlamydia Cure (priority 10) and a Universal Cure (priority 90) sit in the shared pool, the engine picks the specific Chlamydia Cure first. The Universal Cure only fires when no priority-10 match is available.