{ "contract": "container", "version": 1, "origin": "https://opengdd.org/contracts/container-1", "summary": "A delivery is items arriving at a container, such as a bag or chest, that holds distinct items. This contract says when it is full and what happens when some items do not fit. It also says which items it accepts and which slot fills or empties first. It covers slots and size budgets. Version 1 excludes item footprints; counted amounts such as gold use the Ranged value contract.", "mechanism": [ "One container holds items. Two items of one type are interchangeable; items differing within a type — wear, charges — are separate types here, or this game's prose. A slot holds one stack: items of one type together.", "The container's own order is the order the game's material numbers or lists its slots; first and last below mean first and last in it. A container with no slots has none. Containers where an item occupies a width-and-height footprint, including attaché cases and grid inventories, are outside version 1.", "A put offers a type and an amount — a delivery. A take asks for a type and an amount; one larger than the holdings yields what is held and reports the shortfall.", "A delivery that fits is accepted whole; one that does not is settled by partial-acceptance, and anything left over by leftover-destination.", "A stack never holds more than the stack limit on its type's row. Past it, an amount starts a new stack in a free slot, or counts as not fitting if there is none. Under type-restriction any-item, where slots alone set the limit, a type with no row stacks one item per slot and is unmovable in a forced removal, as though when-forced-out were never; under a size budget an unlisted type has no size, so it is refused intact until a row names its size.", "A forced removal is an item leaving without a take: the container shrank, its rules changed, or its owner is gone. Each item row says what becomes of its type and when its turn comes. In a container with slots, the last occupied slot within one type goes first.", "One adoption file describes one container; two are two files with their own rows. Moving an item between them is a take then a delivery, and nothing binds them. Rearranging by hand is input. In a container with slots, a sort re-delivers the contents in the order the sort names; each delivery then lands by the fill-order answer. A slotless container's sort changes nothing observable.", "The same delivery from the same contents lands the same way; the same take comes from the same slot." ], "questions": { "capacity-limit": { "asks": "What makes this container full?", "rationale": "Capacity changes what the container can hold and how it fills. This contract supports one size measure. Containers where items occupy a width-and-height footprint are outside version 1.", "options": { "slot-count": { "meaning": "A fixed number of slots makes it full. A shop's twenty stock slots refuse a new kind of item when all twenty hold stacks. A matching stack with room can still accept it." }, "size-budget": { "meaning": "A size-budget container has no slots. A card deck with a thirty-point build budget may spend those points across cards of different costs." }, "slots-and-size": { "meaning": "A slot limit and a size budget both apply. A bag with three free slots can still refuse an anvil when its weight budget is full." }, "no-limit": { "meaning": "It never fills. A new item always has room, so nothing is refused because the container ran out of space.", "rationale": "Use this when room can never run out. It avoids a fake large limit that readers may mistake for a real cap." } } }, "partial-acceptance": { "asks": "A delivery reaches the container, but not all the items fit. What goes in?", "rationale": "Two containers with the same free space can act differently. One accepts what fits; the other refuses the whole delivery.", "when": { "flag": { "capacity-limit": [ "slot-count", "size-budget", "slots-and-size" ] } }, "options": { "all-or-nothing": { "meaning": "The whole delivery is refused. A ten-arrow pickup adds no arrows when the container has room for only five. Each offered type and amount is one delivery. A craft with several outputs makes several deliveries, so some outputs may enter before another is refused. The refused items stay with whatever offered them, and what that action does next is the game's own rule." }, "fill-what-fits": { "meaning": "Everything that fits goes in. A ten-arrow pickup adds five when only five fit; the other five remain outside." } } }, "leftover-destination": { "asks": "What happens to the items that do not fit?", "rationale": "Items that stay outside still need a clear home. Otherwise one build may return them while another drops or destroys them.", "when": { "flag": { "partial-acceptance": [ "fill-what-fits" ] } }, "options": { "back-to-the-sender": { "meaning": "The leftover goes back to its source. Arrows that do not fit return to the chest or pickup that offered them." }, "left-where-it-is": { "meaning": "The leftover stays where the delivery arrived. Arrows that do not fit become a loose pickup beside the bag." }, "another-store": { "meaning": "The leftover moves to another store named by your game. Arrows that do not fit may go to a stash." }, "destroyed": { "meaning": "The leftover is destroyed. Arrows that do not fit disappear instead of returning, dropping, or moving elsewhere." } } }, "fill-order": { "asks": "Several slots could hold a new item. Which slot gets it?", "rationale": "Two teams building the same spec can fill the same container differently. That changes what players see and what the game removes later. Rules that score slots, rotate between containers, or use a custom sequence stay in your game's prose.", "when": { "flag": { "capacity-limit": [ "slot-count", "slots-and-size", "no-limit" ] } }, "options": { "top-up-then-first-empty": { "meaning": "Matching stacks fill before empty slots open. A potion tops up the first potion stack with room, then uses the first empty slot." }, "first-slot-that-fits": { "meaning": "The first slot that can hold the item gets it. An empty first hotbar slot wins over a later matching stack with room." }, "append": { "meaning": "New items go after everything already held. An empty slot in the middle stays unused until the items after it are gone. A bag with a slot limit can count as full while that gap remains." }, "not-applicable": { "meaning": "Choose this only when each item has one reserved slot. If slots are unlimited, choose Append instead." } } }, "draw-order": { "asks": "The game needs an item for one of its own rules. Which matching slot does it take from?", "rationale": "Automatic use needs a stable choice because it can change which stack remains for the player. A rotating choice over counted amounts belongs in the Ranged value contract.", "options": { "first-in-order": { "meaning": "The first matching slot supplies the item. Crafting uses the earliest stack in the bag before later stacks." }, "last-in-order": { "meaning": "The last matching slot supplies the item. Crafting empties the last matching stack before earlier stacks." }, "newest-first": { "meaning": "The stack that received items most recently supplies them first. Topping up an older potion stack makes it the newest again." }, "oldest-first": { "meaning": "The stack that began first supplies items first. Topping up an old potion stack does not make it newer.", "rationale": "Use this when the longest-held stack must leave first, such as a magazine or queue." }, "not-applicable": { "meaning": "The game never has to choose between matching slots. The player chooses a slot, only one can match, or the container has no slots." } } }, "type-restriction": { "asks": "Which kinds of item can this container hold?", "rationale": "A clear item rule prevents silent differences between what the game accepts and what the designer intended. Rules built from another list or a code callback stay in your game's prose.", "options": { "only-these": { "meaning": "Only listed item types can enter. A potion bag says no to a sword. The sword stays where it was; nothing is destroyed. An empty list means the container accepts nothing." }, "any-item": { "meaning": "Every item type may enter once the contract knows how much room it needs. Where slots alone set the limit, an unlisted type — a quest letter no row names — uses one slot per item and cannot be forced out. Under a size budget, it is refused intact until a row names its size." }, "by-slot": { "meaning": "Each slot has its own item rule. An armour slot accepts a helmet but refuses a potion without destroying it. List every kind that needs a stacking or forced-out rule.", "semantics": "Each item row's slot-rules-declared-in citation is binding. It points to prose that lists every slot and every item kind that slot accepts; an item not accepted there is refused intact." } } } }, "declares": { "values": { "slot-count": { "description": "How many slots the container has. Use at least one when slots set capacity. Use zero when this container has no slot limit. If your game stores this number elsewhere, move it here so two copies cannot disagree." }, "size-budget": { "description": "The largest total size the container holds. Your game chooses the unit, such as kilograms or bulk. Every item uses the same unit. Use zero when size does not limit the container." } }, "rows": { "items": { "description": "The item types whose rules this contract records. Use one row for each type. For a restricted container, the rows are also the allowed list. An empty list means no listed types. For any-item, the rows plus the unlisted-type defaults fully decide entry, stacking, and forced removal for every type. The validator checks each row's fields; a reviewer checks that the game's own prose does not give unlisted types a rule different from the defaults.", "record": { "id": { "type": "string", "required": true, "pattern": "kebab-case", "unique": true, "description": "The item type's name, written as your game names it." }, "slot-rules-declared-in": { "type": "citation", "when": { "flag": { "type-restriction": [ "by-slot" ] } }, "description": "The place in this game's prose that lists every slot and every item kind it accepts. This citation is the binding rule for the slots. Use the same citation on every row when one section holds the whole list." }, "stack-limit": { "type": "integer", "when": { "flag": { "capacity-limit": [ "slot-count", "slots-and-size", "no-limit" ] } }, "description": "How many items of this type fit in one slot. It is required whenever the container has slots, including when it never fills. Use one for an item that does not stack, or another positive whole number." }, "size": { "type": "number", "when": { "flag": { "capacity-limit": [ "size-budget", "slots-and-size" ] } }, "description": "How much of the size budget one item uses. Use the same unit as the container's budget. Use zero or more." }, "when-forced-out": { "type": "string", "required": true, "options": [ "never", "dropped-nearby", "moved-to-another-store", "destroyed" ], "description": "What happens to this item when the container must give items up. It may stay, drop nearby, move to another store, or be destroyed. An item marked to stay is skipped. The container tries other types in their chosen order. It refuses the forced removal if too few items can leave. If destroying an item could make the game impossible to finish, say so and test it in your own rules." }, "forced-out-order": { "type": "integer", "unique": true, "when": { "row": { "when-forced-out": [ "dropped-nearby", "moved-to-another-store", "destroyed" ] } }, "description": "The order in which item types leave, lowest number first. Give each movable type a different number. Items of one type leave from its last occupied slot first. The size of the gaps between numbers does not matter." } } } } }, "pack": "sha256:8f40a54e650b683136852e7a5b47976ebe709f810057f847424d6d8ab3b41b20", "rules": { "slot-count-not-negative": "slot-count >= 0", "size-budget-not-negative": "size-budget >= 0" } }