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`.
`GirlBuyChance`	No	0-100: chance the girl buys it herself with her cut.

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`	Set a girl-status bit. Rarely used by modders.	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.

Two spellings catch authors out: the skill is NormalSex with no space, and Beastiality carries the extra “a” the engine uses.

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.

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 reference/when-conditions.md 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.

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 New (1.15.6)

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>` New (1.15.6)

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` New (1.15.6) {#remove_trait-new}

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

Path resolution: the engine looks for <packsRoot>/<your-pack>/Scripts/<filename> first, 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 the full schema specification, DSL grammar, and implementer notes, see docs/modding-and-packages/pack-format.md (Consumables section). For ready-to-paste recipes, see examples/items-cookbook.md.

Recipes New (1.15.6)

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.