Components reference

Components live in the components{…} object of an item definition. Each one attaches a behaviour to the worn item: a lock, struggle resistance, a gag, a collar, and so on.

{
  "type": "tiedup:bondage_item",
  "display_name": "Ball Gag",
  "model": "tiedup:models/gltf/gags/ball_gag.glb",
  "regions": ["MOUTH"],
  "components": {
    "lockable": {},
    "resistance": { "id": "gag" },
    "gagging": { "material": "ball" },
    "adjustable": {}
  }
}

Note

There are exactly 10 component keys: lockable, resistance, gagging, blinding, shock, gps, choking, adjustable, ownership, built_in_lock. Any other key is logged with a WARN and ignored — check your logs after /reload if a component seems to do nothing. Most components are valid as an empty object ("choking": {}); that empty object is a marker that turns the behaviour on.

Don't confuse the component with the top-level field

lockable exists both as a top-level item field and as a component, and they are not the same lever (see lockable below). Likewise resistance is a component only — there is no working top-level resistance_id field, despite what an old parser comment suggests.

Quick reference

Component	What it does	Status
lockable	Per-item lock resistance (worn-item lock gate is elsewhere)	✅ Available
resistance	Struggle resistance from a config preset	✅ Available
gagging	Muffles chat by gag material	✅ Available
blinding	No-op marker; blackout comes from the EYES region	❌ Planned
shock	Shock collar (manual + auto interval)	✅ Available
gps	GPS tracking + safe zone	✅ Available
choking	Choke collar (air drain)	⚠️ Partial
adjustable	Y-offset adjustment slider	✅ Available
ownership	Collar registration + owner tooltips	✅ Available
built_in_lock	Permanently locked, no padlock	✅ Available

---

lockable

✅ Available

Stores a per-item lock resistance — how hard a padlock on this item is to break by struggling. Almost every shipped item declares it as an empty object and inherits the global default.

"lockable": {}

"lockable": { "lock_resistance": 300 }

• lock_resistance (int, default 250, clamped ≥ 0) — added to the struggle cost when a padlock is attached. Shows up on the advanced (F3+H) tooltip.

The component does NOT decide whether a padlock can be applied

The worn-item padlock gate is the top-level can_attach_padlock field (default true, independent of anything else). The top-level lockable field is read only by furniture code, not worn items. So for a worn item:

• to allow a padlock → leave can_attach_padlock at its default (or set true);
• to set how strong that padlock is → use this lockable component’s lock_resistance;
• to make an item permanently locked with no padlock at all → use built_in_lock instead.

---

resistance

✅ Available

Sets the base struggle resistance for escaping the item. The normal, shipped way is to point at a named config preset with id — the actual number is then taken from the server config at runtime, so server owners can retune it.

"resistance": { "id": "gag" }

id resolves through the server config’s bind-resistance table. Built-in preset keys you can reference:

rope   chain   armbinder   wrap   straitjacket   latex_sack
ribbon vine    web         slime  tape           gag
blindfold       collar

An id that doesn’t match a configured key falls back to 100 at runtime (no crash). A few item names are aliased to a shared preset (e.g. shibari → rope, beam_cuffs → chain, leather_straps/medical_straps/dogbinder → armbinder) — reference the preset key, not the item name.

Note

There is also a base field ("resistance": { "base": 150 }, default 100, clamped ≥ 0) that hardcodes the value instead of reading config. It only applies when no id is set. It is a legacy/untested path — prefer id. If you set both, id wins.

Tip

resistance is a component, not a top-level field. An older parser comment shows a top-level resistance_id — it is never parsed. Put it inside components.

---

gagging

✅ Available

Muffles the wearer’s chat. The real lever is material, which selects a gag profile (comprehension + how far the muffled text carries).

"gagging": { "material": "ball" }

Valid material values (case-insensitive):

cloth   ball   tape   stuffed   panel   latex
ring    bite   sponge baguette

An unknown material is logged with a WARN and the item falls back to default muffling (stuffed is the typical heavy gag; ball is a common medium one). The material also drives the gag tooltip line.

comprehension is inert

⚠️ Partial

gagging.comprehension is parsed but has no effect — muffling always uses the material’s built-in comprehension value. Do not present it as configurable; set the material instead.

Note

gagging.range (max blocks the muffled speech carries) only takes effect when no material is set — a material always overrides it. Since every shipped gag sets a material, range is effectively unused. If you truly want a custom range, omit material and set "range": 8.0.

---

blinding

❌ Planned

Nominally “marks the item as a blindfold” — but the component does nothing functional. The blackout is driven entirely by the EYES body region, not by this component. You can write it as an empty marker, but it changes no behaviour:

"blinding": {}

The component is a no-op; the overlay field is inert

The blackout overlay is hardcoded to tiedup:textures/misc/blindfolded.png and is triggered by the item occupying the EYES body region, not by this component. A blindfold needs only "regions": ["EYES"]; adding "blinding": {} changes nothing — the one place that checks for the component (SelfBondageInputHandler) is an unreachable fallback for data-driven items, which are already handled earlier.

The blinding.overlay field is parsed but never read — you cannot supply a custom overlay texture this way. Do not document it as configurable.

---

shock

✅ Available

Turns a collar into a shock collar. The working lever is auto_interval — the number of ticks between automatic shocks (20 ticks = 1 second). 0 (the default) means manual-only, triggered through a controller.

"shock": {}

"shock": { "auto_interval": 200 }

• auto_interval (int, default 0, clamped ≥ 0) — 0 = manual shock only; any positive value auto-shocks on that cadence. With auto enabled, the tooltip shows the interval in seconds.

shock.damage is inert

⚠️ Partial

shock.damage is parsed but has no effect — every shock deals a fixed amount of damage in code regardless of what you write. The shipped collars carry a "damage": 2.0 line that the game ignores; don’t rely on it.

A real shock collar pairs shock with ownership so the wearer is registered and the owner can trigger it:

"components": {
  "ownership": {},
  "lockable": {},
  "resistance": { "id": "collar" },
  "shock": { "auto_interval": 200 }
}

---

gps

✅ Available

Tracks the wearer and defines a safe zone.

"gps": { "safe_zone_radius": 50 }

• safe_zone_radius (int, default 50, clamped ≥ 0) — radius in blocks. 0 = tracking only, no safe zone. This value works (it drives the safe-zone / GPS-shock logic) and adds a tooltip line.

public_tracking is inert

⚠️ Partial

gps.public_tracking is parsed but has no effect — the runtime “who can track” flag is read from the collar’s NBT, not from this JSON field. Setting it here does nothing; don’t present it as configurable.

---

choking

⚠️ Partial

Turns a collar into a choke collar that drains air. Present it as an empty marker:

"choking": {}

choking fields are inert — marker only

The air-drain rate and the master/non-lethal behaviour are hardcoded in the effect. Both config fields are parsed but ignored:

• choking.air_drain_per_tick — no effect; drain rate is fixed in code.
• choking.non_lethal_for_master — no effect; the master/non-lethal logic is fixed in code.

Treat "choking": {} as an on/off marker only. Do not document these fields as tunable.

---

adjustable

✅ Available

Lets the wearer (or owner) nudge the item’s vertical position with an in-GUI slider — useful for gags and blindfolds that need to sit a little higher or lower per body shape.

"adjustable": {}

"adjustable": { "default": 0.5 }

• default (float) — the starting Y-offset used as the fallback before the player adjusts it. Clamped into the working slider range.

min / max / step are inert

⚠️ Partial

adjustable.min, max, and step are parsed but have no effect — the slider always clamps to a fixed range (−4.0 … 4.0) with a fixed increment, regardless of what you write. Only default is honoured. Don’t present the bounds as configurable.

---

ownership

✅ Available

Marks the item as a collar with an owner. This is a real, non-trivial component (omitted from older guides) used by the five shipped collars. On equip it registers the wearer in the collar registry against the NBT owner list; on removal it fires the owner-alert / unregister flow. It also drives the nickname and owner-count tooltip lines.

"ownership": {}

It takes no config — just the empty marker. Combine it with the collar capability components:

"components": {
  "ownership": {},
  "lockable": {},
  "resistance": { "id": "collar" },
  "gps": { "safe_zone_radius": 50 }
}

Note

The collar’s owners and nickname live in the item’s NBT, set in-game — not in the definition JSON. The component is what wires the registration and the owner-aware tooltips.

---

built_in_lock

✅ Available

The “permanently locked, no padlock” mechanic for organic restraints — slime, vine, web, tape. Used by eight shipped items. While worn, the item always blocks unequip (it behaves as if locked), and a padlock cannot be attached to it.

"built_in_lock": {}

It takes no config. A built_in_lock item should declare "can_attach_padlock": false to match its behaviour, and typically omits the lockable component (there is no padlock to resist):

{
  "type": "tiedup:bondage_item",
  "display_name": "Web Bind",
  "model": "tiedup:models/gltf/binds/web_bind.glb",
  "regions": ["ARMS"],
  "can_attach_padlock": false,
  "components": {
    "resistance": { "id": "web" },
    "built_in_lock": {}
  }
}

Tip

Use built_in_lock for restraints that are escaped purely by struggling and can never be padlocked (organic/sticky materials). Use lockable + can_attach_padlock for hard-restraint gear that a key-holder padlocks shut.

---

Putting it together

A gag

gagging (material) + resistance (id: "gag") + adjustable, plus lockable if it can be padlocked.

A collar

ownership + resistance (id: "collar") + a capability: shock, gps, or choking.

An organic bind

resistance + built_in_lock, with can_attach_padlock: false. No lockable.

A blindfold

regions: ["EYES"] does the blackout; add blinding as a marker, adjustable to fine-tune fit.

For the surrounding item fields (regions, pose_priority, can_attach_padlock, icon, animations…) see The item JSON.