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)
`SmWeapon`	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 (1.11+)	`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 (1.11+):

<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 (1.12+)

Engine 1.12 introduced 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.

Pack requirement. Add RequiresEngine="1.12.0" to your package.xml if any item in your pack uses the new schema. Older engines silently skip the new elements.

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 (1.12+)
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="..."/>`
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.

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.

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>
        <effect type="stat" name="magic" value="2"/>
        <narration>{girl} rubs the lamp. A column of smoke rises.</narration>
    </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.