Equipment changes capability through a contract

684. Lesson identity

Module

2.5 — Inventory, equipment, and crafting

Lesson

Equipment changes capability through a contract

Academic type

Guided Build

Schema type

Practical

Order

Lesson 2

Estimated time

30–40 minutes

685. Learning objective

After this lesson, you can map equipment and unequipment selections to gameplay effects by defining slots, modifiers, empty states, and derived capability without duplicating authority between inventory and gameplay systems.

686. Why this matters

An inventory can record that an item is owned, but ownership alone does not make the item active. Equipment introduces another state: which owned item, if any, is selected for a capability slot. A separate interpretation step then derives the gameplay effect from that selection.

The phrase if any is part of the contract. A slot can be empty before the player equips an item, after an explicit unequip request, or after another rule clears an invalid selection. If the empty state is left undefined, gameplay may retain a stale modifier even though the interface shows no equipped item.

Keeping possession, selection, and interpretation separate makes implementations easier to inspect, test, and extend.

687. Prior knowledge

You should be able to describe inventory as the authority for possession and quantity, as established in Inventory owns possession, not every item meaning. You should also be familiar with assigning one authoritative owner to each game fact. Use the implementation cycle input → rule → presentation → feedback when describing how equip and unequip requests become observable capabilities.

688. Core concept

Equipment is a contract between three layers:

1. Selection state: which item ID, or an explicit empty value, occupies a named slot.
2. Modifier data: what capability changes an equipped item declares.
3. Derived capability: the gameplay result produced by interpreting the current selections.

The equipment system owns selection state. It does not own inventory quantities, item descriptions, or every gameplay calculation. A capability system reads the selection and item data to derive a result such as tool strength, movement capacity, or protection value.

A useful contract is:

Equipment selection + item modifier data → derived capability

For one tool slot, the selected value might be either an item ID or none:

tool slot = fold_cutter | rusty_cutter | none

none is a valid equipment state, not an error and not a missing implementation. Its capability result must also be defined. In the example used here, an empty tool slot derives cuttingPower = 0.

The same item may therefore be:

• owned but unequipped;
• equipped in one valid slot;
• replaced by another valid item; or
• returned to an owned-but-unequipped state when the slot is cleared.

The inventory remains the source for whether the item is in the player's possession. Equipment records the active choice or the absence of one. Capability interpretation reads that contract without creating a second inventory.

689. Mental model

Use the SELECT → INTERPRET → APPLY model:

Keep the authority map explicit:

The player provides input by requesting equip or unequip. A selection rule accepts or rejects the request and communicates the result. An accepted request changes the equipment state, the capability is recalculated, and presentation and feedback expose the result. Another request can then test the contract again.

690. Concrete example

Suppose the player owns two tools:

rusty_cutter:
  slot: tool
  cuttingPower: 1

fold_cutter:
  slot: tool
  cuttingPower: 3

The player begins with an empty tool slot:

equipment.tool = none

Selecting fold_cutter produces this transition:

selection request: equip fold_cutter
→ inventory confirms possession
→ item data confirms slot = tool
→ equipment assigns fold_cutter to the tool slot
→ capability interpretation derives cuttingPower = 3
→ the cutting interaction uses cuttingPower = 3

Unequipping produces a second valid transition:

selection request: unequip tool
→ equipment assigns none to the tool slot
→ capability interpretation derives cuttingPower = 0
→ the cutting interaction uses cuttingPower = 0

Unequip does not remove the item from inventory. It only clears the active selection. Repeating unequip tool while the slot is already empty should leave the state empty and should not restore an old modifier.

The inventory does not store cuttingPower, and the interaction does not search the inventory to guess which tool is active. Each system reads the contract it needs.

691. AI-native workflow

Use AI as an implementation partner, not as the authority that decides the architecture.

1. State the contract before asking for code: inventory owns possession, equipment owns an item ID or empty value for each slot, item data owns modifiers, and capability interpretation derives the active value.
2. Ask the AI to propose a small data model and identify the authority for every fact.
3. Inspect the proposal for duplicated state. Reject designs that store both equippedItem and a separately editable activeCuttingPower unless the second value is explicitly derived and refreshed through one defined rule.
4. Check that the proposal represents an empty slot deliberately. Do not accept code that treats a missing key, an outdated item ID, and an intentional unequip action as indistinguishable states without a stated policy.
5. Ask the AI to implement the smallest equip and unequip flow with one valid slot and two items.
6. Test the implementation against the evidence conditions below. If behavior is wrong, ask for a diagnosis of the contract violation before requesting a rewrite.

A useful prompt is:

Implement a minimal equipment contract for one tool slot. Inventory owns item possession. Equipment owns either the selected item ID or an explicit empty value. Item data provides cuttingPower. A capability function derives active cutting power from the current selection and returns 0 for an empty slot. Reject equip requests when the item is unowned or does not fit the slot. An unequip request clears the slot without removing the item from inventory. Show the authority of each value before writing code.

692. Common mistakes

Duplicating an item's effect

An equipment menu might set cuttingPower = 3, while an interaction script separately searches for a tool and calculates another value. These paths can disagree when an item is replaced, removed, modified, or unequipped. Store the selection once, declare the modifier once, and derive the capability through one visible interpretation path.

Clearing the interface but not the contract

Hiding the selected item in the interface is not sufficient to unequip it. If equipment still stores fold_cutter, gameplay can continue using its modifier. Unequip must mutate equipment state to the explicit empty value and trigger capability reinterpretation. Presentation then reflects the new state.

693. Guided practice

Build or adapt a one-slot equipment slice.

Step 1: Declare the contract

Write a short authority table containing:

• owned item IDs and quantities;
• selected item ID or empty value for the tool slot;
• item-to-modifier data;
• derived cuttingPower capability;
• presented item and capability text.

For each entry, name exactly one authority. Define the empty-slot result explicitly as cuttingPower = 0 for this slice.

Step 2: Define equip and unequip rules

Implement or describe commands with this behavior:

• reject an equip request for an item that is not present in inventory;
• reject an equip request for an item whose declared slot is not tool;
• accept a valid item and replace the current tool selection;
• accept an unequip request and assign the explicit empty value to tool;
• leave inventory possession unchanged when unequipping;
• derive the capability after either selection changes or the slot is cleared.

Do not add a second inventory count to equipment state. Do not retain the previous modifier when the slot becomes empty.

Step 3: Connect presentation and feedback

Make the equipment presentation show the selected item ID or name. When the slot is empty, show a deliberate empty-state label such as No tool equipped rather than a stale item name.

Make gameplay feedback expose the resulting cuttingPower when the player attempts the relevant interaction. The feedback must come from the derived capability, not from a hard-coded interface value.

Step 4: Make one removal-policy decision

Choose what happens when an equipped item is removed from inventory:

• automatically clear the slot;
• block the removal; or
• mark the selection invalid until the player resolves it.

This inventory-removal policy is separate from explicit unequip. Unequip clears the active selection while leaving possession intact. Inventory removal changes possession and must reconcile any equipment reference.

Choose one removal policy, state which system enforces or coordinates it, and explain how it prevents stale selections or modifiers. The lesson does not prescribe one universal policy; the contract must be explicit.

694. Validation and evidence

Your build is acceptable when you can point to all of the following:

• an authority table with one owner for possession, selection, modifiers, derived capability, and presentation;
• an explicit representation for an empty slot;
• a valid equip request that changes the selected item and derived capability;
• an invalid equip request that is rejected without changing active equipment;
• an unequip request that clears the slot without changing inventory possession;
• an empty slot that derives the defined baseline capability rather than retaining a stale modifier;
• visible presentation of both equipped and empty states;
• gameplay feedback that reflects the derived capability;
• no duplicate inventory count or independently editable gameplay modifier;
• a documented policy for removing an equipped item from inventory.

Run at least these checks:

1. Begin with an empty tool slot and verify that cuttingPower = 0.
2. Own rusty_cutter and fold_cutter; equip each in turn and verify that the derived value changes from 1 to 3.
3. Unequip the current tool and verify that the slot becomes empty, both items remain owned, and the derived value returns to 0.
4. Unequip again while the slot is empty and verify that no previous modifier reappears.
5. Attempt to equip an unowned item and verify that the current selection remains unchanged.
6. Attempt to equip an item assigned to another slot and verify that the request is rejected.
7. Apply your inventory-removal policy and verify that the capability does not silently retain a stale modifier.

695. Knowledge check

696. Key takeaways

• Inventory owns possession; equipment owns the active item ID or empty value for each slot.
• Unequipping clears selection without removing the item from inventory.
• An empty slot is a valid state with a defined derived result.
• Modifiers describe item contributions; they are not a second inventory or equipment state.
• Selection validation protects ownership and slot compatibility.
• Explicit removal and empty-state policies prevent stale selections and modifiers.

697. Next lesson

Continue to 2.5 L3 — Crafting is a transaction, not a second economy.

698. Knowledge check