@spawnite/engine 0.1.0-beta.15

package/dist/wiki/engine/behaviours/inventory.md

@@ -0,0 +1,266 @@
+---
+title: Inventory
+description: A bag of slots that holds stacks of the items a game registers by name.
+useCases:
+    - inventory backpack
+    - item slots with stacking
+    - equip armor and weapons
+    - use a potion from the bag
+    - register an item
+    - drag items between slots
+    - equipment stat bonuses
+    - save the player's inventory
+sidebar:
+    order: 11
+---
+
+Inventory gives an entity a bag: a fixed number of slots, each empty or holding one stack of an item. You register each item once by name, give the entity `<Inventory slots={20} />`, and the verbs add, remove, move, split and count the stacks. The player's character needs none in a game that lists `inventory()` in its plugins: the plugin gives her a bag of 16 slots, or as many as [`<CharacterSpawn>`](/engine/entities/player/#what-she-holds)'s `bagSlots` says, and the equipment slots. The player's save keeps both where the game's save includes `inventory`, as [Saving progress](https://wiki.spawnite.com/learn/saving-progress/) says; a game that does not keeps no bag across a reload. A room gives her the same bag and slots, empty each time she joins, and restores them from her save where the game includes `inventory`.
+
+Its props are in [`InventoryProps`](https://wiki.spawnite.com/reference/inventory/inventoryprops/).
+
+## Items
+
+An item's definition is registered by name, as a model is, and every copy shares it:
+
+- `displayName` is what a player reads.
+- `model` is the registered model a [Loot](/engine/behaviours/loot/) and a dropped copy are drawn as.
+- `color` is the colour of the glowing gem a Loot draws when the item names no `model`. It defaults to white.
+- `maxStack` is the most one slot holds. It defaults to 1, so a sword takes a slot of its own.
+- `equip` says where it is worn and what it changes while it is, as [Equipment](#equipment) describes.
+- `use` says what using it does, as [Using an item](#using-an-item) describes.
+- `tags` are the words a [target](#targets) matches the item by: `["key", "gold"]`.
+
+A copy in a bag is an [`ItemStack`](https://wiki.spawnite.com/reference/inventory/itemstack/): `{ item, count, data? }`. `item` is the registered name and `count` is how many copies the slot holds. `data` holds only what differs for this copy, such as a rolled modifier.
+
+Two stacks merge only when their `item` and their `data` are equal. A copy with rolled data never stacks with a plain one, so an item needs no flag to say it is unique.
+
+## The verbs
+
+All take the entity and come from `@spawnite/engine/core`, so a system and a component call them alike:
+
+- `addItem(entity, stack)` fills the stacks it can merge with first, then empty slots, each up to the max stack. It returns the count it took, which is less than asked when the bag is full, so a pickup knows what to leave on the ground.
+- `removeItem(entity, { item, count })` takes up to `count` copies, whatever their data, from the first slot on, and returns the count it took.
+- `moveStack(entity, { from, to })` moves a slot's stack into another slot. Onto a stack it can merge with, it tops that stack up to the max and leaves the rest where it was. Onto any other stack, the two swap.
+- `splitStack(entity, { from, to, count })` moves part of a stack into an empty slot.
+- `countItem(entity, item)` counts the copies across every stack.
+- `hasItem(entity, item)` says whether the bag holds at least one.
+- `declareInventory(entity, slots)` gives an entity a bag, for a system that spawns one without the component. A changed count keeps the stacks in the slots that remain.
+
+Each verb writes a new list of slots, so a reader of `InventoryTrait` sees each change. A count that is not a whole number above zero throws, and so does an item nobody registered.
+
+## The store
+
+`useInventory` mirrors the player's bag each frame for a HUD, as `useWallet` mirrors her coins. Its `slots` hold one entry a slot, `null` where the slot is empty. It reads the bag of the player's character, and it changes only when the bag does.
+
+`<Bag />` in a [Hud](/engine/ui/hud/) is the engine's panel over that store: a column of buttons up the right edge, one a stack, each reading its display name and count. The right edge keeps it clear of the stick a thumb steers by at the bottom left and of an [ActionBar](/engine/ui/action-bar/)'s arc at the bottom right. Its `slot` stands it in another of the HUD's regions, as a Panel's does, such as `<Bag slot={Slot.TopLeft} />`. A press wears an item that has an `equip` and uses any other, and an empty slot draws nothing. A game that wants another look writes its own from `useInventory`. Under a camera that captures the cursor, as in a shooter, no click reaches the bag's buttons, so a game shows it as a screen the player opens and frees the cursor while it shows, as every game with an inventory does: `useFreeCursor(open)` beside it, or a [Panel with `freeCursor`](/engine/ui/panel/#a-panel-that-frees-the-cursor) around the game's own bag. In development, the engine warns of a bag shown in play with nothing freeing the cursor. Roblox draws a default Backpack bar a game can turn off and replace, and Minecraft draws its own inventory screen; Unity, Unreal and Godot draw none.
+
+## Equipment
+
+`<Equipment />` gives an entity the engine's equipment slots, the values of `EquipmentSlot`: `head`, `body`, `hands`, `feet`, `ring1`, `ring2`, `neck`, `mainhand` and `offhand`. The list is fixed, as Minecraft's is, and a game leaves the slots it does not use empty.
+
+An item that can be worn names its slot and what it changes in `equip`:
+
+- `slot` is an `EquipmentSlot`, or `"ring"` for whichever ring slot is free.
+- `modifiers` holds a [`StatModifier`](https://wiki.spawnite.com/reference/stats/statmodifier/)'s `flat`, `percent` and `more` by stat name. A copy's own `data.modifiers` replaces its definition's, so a ring rolled stronger than its kind is one copy's data.
+
+Two verbs move an item between the bag and a slot:
+
+- `equipItem(entity, from)` wears the stack in bag slot `from`, and adds each modifier to the entity's [stats](/engine/behaviours/stats/) with the source `equip:<slot>`. What the slot wore goes into bag slot `from`, and its modifiers come off. It returns false, and changes nothing, for an empty slot, an item with no `equip`, or an entity without `<Equipment />`. It wears the whole stack, so three rings stacked in one bag slot go on as one ring, and their modifiers apply once.
+- `unequipItem(entity, slot)` puts what the slot wears into the bag's first empty slot and removes its modifiers by that source. It returns false, and the item stays on, when the bag has no empty slot.
+
+The source is the slot's, so two identical rings in `ring1` and `ring2` are two sources, and taking one off leaves the other's modifiers. `useInventory` carries what the player's character wears as `equipment`, by slot. Unmounting `<Equipment />` removes the slots, what they wear, and the modifiers that put on the stats.
+
+Minecraft keys a worn item's attribute modifiers by its slot and removes them when the item leaves it. Unreal's Lyra keeps a handle for each grant, and Unity's common Kryzarel pattern removes by the source object. Equipment keys by slot, as Minecraft does, because a slot is a string a save and a room carry as they are, where a handle or an object is not. Roblox's accessories and Godot carry no stats of their own.
+
+```tsx
+import {
+    Entity,
+    Equipment,
+    Inventory,
+    Stats,
+    registerItem,
+} from "@spawnite/engine";
+
+registerItem("ring-of-speed", {
+    displayName: "Ring of speed",
+    equip: { slot: "ring", modifiers: { speed: { percent: 0.1 } } },
+});
+
+export function Wearer() {
+    return (
+        <Entity>
+            <Stats speed={{ base: 6 }} />
+            <Inventory slots={20} />
+            <Equipment />
+        </Entity>
+    );
+}
+```
+
+## Using an item
+
+An item's `use` says what using it does. Its `effects` are a closed set that the step runs on the server, on the entity that uses the item:
+
+- `{ type: "heal", amount }` adds `amount` to its [health](/engine/behaviours/health/), never past the maximum, as `dealHealing` by its user, so a view of heals hears it. `registerItem` throws for an `amount` below 0 or not finite, naming the item.
+- `{ type: "modify", stat, flat, percent, more, seconds }` adds a [stat modifier](/engine/behaviours/stats/) under the source `use:<item>`. With `seconds`, it is a buff that ends when they run out. A second use of the item replaces what the first put on, so a buff restarts its seconds rather than stacking.
+- `{ type: "coins", amount }` pays `amount` coins into its wallet, as [`addCoins`](/engine/behaviours/pickup/#coins-a-game-pays) does. The step checks every coin effect of a use before it runs the first effect, so a use whose coins the wallet could not hold throws and changes nothing.
+
+`consume: true` spends one copy from the slot the use named. `cooldownSeconds` is how long before the same entity can use the item again. The cooldown runs in the entity's [`CooldownsTrait`](/engine/behaviours/cooldowns/) under `item:` and the item's name. Items that name the same `cooldownGroup` share one cooldown under that key: using one holds them all.
+
+`activateItem(entity, { slot, target })` asks the step to use the stack in bag slot `slot`, on `target` when one is named. The step runs each use before the behaviours: the effects, then the target, then the copy it spends and the cooldown. A use does nothing, and spends nothing, in any of these cases:
+
+- The slot is empty.
+- The item is still cooling down.
+- The item has no effects, and no target accepts it.
+
+The step runs a use only where the simulation has the say: a client's world fed from a room runs none.
+
+An effect the set lacks is the game's own: a trait and a server system keyed on the item's tags, as [the entity page](/engine/entities/entity/#consequences-are-data) says for every consequence.
+
+```tsx
+import {
+    Button,
+    Entity,
+    Hud,
+    Lock,
+    Panel,
+    Slot,
+    activateItem,
+    registerItem,
+    usePlayer,
+} from "@spawnite/engine";
+
+registerItem("potion", {
+    displayName: "Potion of healing",
+    maxStack: 10,
+    use: {
+        effects: [{ type: "heal", amount: 30 }],
+        consume: true,
+        cooldownSeconds: 1,
+    },
+});
+
+registerItem("gold-key", {
+    displayName: "Gold key",
+    tags: ["key", "gold"],
+    use: { consume: true },
+});
+
+export function VaultDoor() {
+    return (
+        <Entity position={[0, 0, -6]}>
+            <Lock accepts="key gold" />
+        </Entity>
+    );
+}
+
+/** Drinks what the first slot of the player's bag holds. */
+export function DrinkButton() {
+    const { entity: character } = usePlayer();
+    return (
+        <Hud>
+            <Panel slot={Slot.Bottom}>
+                <Button
+                    onPress={() => {
+                        if (character) activateItem(character, { slot: 0 });
+                    }}
+                >
+                    Drink
+                </Button>
+            </Panel>
+        </Hud>
+    );
+}
+```
+
+### Targets
+
+A target says which items it takes. Its `accepts` is a list of tags, separated by spaces, and an item used on it matches when the item's `tags` hold every one. An empty `accepts` takes every item, since there is no tag for the item to miss. `<Lock accepts="key gold" />` is the engine's target: an item with both tags opens it, and `LockTrait`'s `open` turns true in the step the item is used. An open lock refuses every item, so a second use of the key does nothing and spends no copy, as a key in Minecraft or Zelda is spent only on the lock it opens.
+
+A game's own target is a trait with an `accepts` field, made a target once with `registerItemTarget(trait)`, and a server system. When an item matches, the step emits the `ItemAcceptedEvent` [event](/engine/structure/systems/#events) on the target, naming the item, and the system reads it with `readEvents`. A lock opens as it accepts its key:
+
+```tsx
+import { trait, type World } from "koota";
+import {
+    ItemAcceptedEvent,
+    readEvents,
+    registerItemTarget,
+    type SystemStep,
+} from "@spawnite/engine";
+
+/** Soil that takes a seed, and the seed it grows. */
+export const SoilTrait = trait({ accepts: "seed", planted: "" });
+registerItemTarget(SoilTrait);
+
+/** Plants each seed a soil took. */
+export function plantSeeds(_world: World, step: SystemStep) {
+    for (const { entity: soil, record } of readEvents(step, ItemAcceptedEvent))
+        if (soil?.has(SoilTrait)) soil.set(SoilTrait, { planted: record.item });
+}
+```
+
+Minecraft's `consumable` and `use_cooldown` components are the model for `use`: a closed list of effects the server runs, a copy spent, and a cooldown by item. Stardew's machines and Minecraft's `cow_food` tag say on the target what it takes, as `accepts` does. Unreal's Lyra has the target grant an ability, Roblox runs a script on each tool, and Unity and Godot leave use to code. Use takes Minecraft's data and the target's list of tags, because both are data an agent writes and the server runs.
+
+## Saving and replication
+
+Where the game's save includes `inventory`, the save keeps the player's bag, one entry a slot and `null` where the slot is empty, and what she wears, by slot, under `engine.inventory`:
+
+- The engine reads the character's bag and her worn items there, each stack as it is: `{ item, count, data? }`. An emptied bag is saved as empty, so a reload never brings back what she used.
+- The engine lays the saved bag and worn items on her once her spawn has set her up, so a game's save code never names them. Her bag then has `<CharacterSpawn>`'s `bagSlots` slots, or more where the saved bag had more: a larger saved bag keeps its size and every stack in it, and a smaller one grows to `bagSlots`.
+- A stack whose item the game no longer registers is dropped as the save loads, with a warning in development, and the rest of the save loads.
+- A worn item's modifiers go back on her stats from the item as it is registered now, so a changed definition takes effect on the next load, and a dropped item's modifiers go with it. The save's `stats` hold the `equip:<slot>` modifiers too, and the load removes them before it adds the worn items' own, so each counts once.
+- A game whose player has no character keeps a stack inside its own save with the engine's codec, `itemStack.toSave(stack)` and `itemStack.fromSave(saved)`, and calls `restoreInventory(entity, inventory)` and `restoreEquipment(entity, equipment)` in its own `restore`.
+- A save with neither part loads as before.
+
+Unity's Opsive and Godot's gloot save each stack as its definition's id, its count and the values it overrides, as a save here keeps `item`, `count` and `data`. Unity's Chop Chop sample skips an id it no longer knows. The load here drops one too, and says so in development, so the agent sees what a save lost. Roblox and Unreal leave the save to the game.
+
+In a room, the room owns her bag and what she wears, and streams them to her alone:
+
+- After each delta that changed them, the room sends her client an `owned` message with what changed of her character's `inventory` and `equipment`, and her page writes it onto her character. `useInventory` mirrors it there as it does alone.
+- Every other player's stream carries neither, and neither counts toward the stream's hash. Another player sees a worn item through the stats it changes, which every client receives.
+- A client asks the room for a change to her bag with an `item` message naming the verb: `move`, `use`, `equip`, `unequip` or `drop`. The room runs that verb on its own copy of her, and its word to her alone carries what it made.
+- The room checks each intent's fields before it runs the verb, and the verb's own checks refuse a slot her bag does not have.
+- On her page, `moveStack`, `splitStack`, `activateItem`, `equipItem`, `unequipItem` and `dropItem` called on her character send that message instead of changing her bag, so a game calls the same verbs alone and in a room. The page predicts nothing: the change shows when the room's word to her arrives. There, `equipItem` and `unequipItem` check what her page holds and return `true` once they have asked the room, which makes the change on its own copy of her, and `dropItem` returns nothing. A verb called on another player's character asks nothing, since a room changes a bag only on its owner's word, and warns in development. A use's target goes by its streamed id.
+
+Unreal's Lyra keeps the inventory on the player's controller, which exists only on the server and its owner, and Roblox replicates a Backpack to every player. A bag here goes to its owner alone, as Lyra's does, because what a player carries is hers.
+
+## What an agent reads
+
+`dumpState`, the headless dump and the entity inspector show a bag under `inventory` and what an entity wears under `equipment`, and its hash covers them. The room's stream to every client leaves both out, as [Saving and replication](#saving-and-replication) says.
+
+In the AI tree, a bag is a fact for each stack it carries, `carrying Potion of healing ×3`, and an action for each item that does something: `use` for one with a `use` or tags, `wear` for one with a slot. A worn item is a fact, `wearing Ring of speed`. An item goes by its display name, or by the name it was registered under where the game no longer registers it.
+
+## Where it runs
+
+Server. A bag holds what a player owns, what she wears changes her stats, and what she uses changes her health, her stats, her wallet or a lock.
+
+## What other engines do
+
+| Engine or game | Held item                                       | Container                       | Stacking                                   | A full bag                                    |
+| -------------- | ----------------------------------------------- | ------------------------------- | ------------------------------------------ | --------------------------------------------- |
+| Roblox         | a whole `Tool`, no count                        | an unbounded Backpack           | none                                       | never full                                    |
+| Unreal, Lyra   | a definition class; an instance with tag stacks | an unbounded list               | never merged                               | never full                                    |
+| Unity, Opsive  | a definition asset plus an amount               | fixed slots, a list or a weight | up to 99, only when attributes are equal   | returns the amount added                      |
+| Godot, gloot   | a JSON prototype plus overrides                 | a list, a grid or a weight      | a max per prototype; equal overrides merge | returns false                                 |
+| PlayCanvas     | none                                            | none                            | none                                       | none                                          |
+| Minecraft      | an item type plus per-stack components          | fixed slots                     | a max per type; equal components merge     | takes what fits; the rest stays on the ground |
+
+Inventory takes Minecraft's shape: a definition per item, a stack that stores only what differs, fixed slots, and stacks that merge when their data is equal. Most players know that shape, and it maps onto a trait. Like Opsive's `AddItem`, `addItem` returns what it took, so a full bag is an answer rather than an error. It leaves out a grid, a weight cap and a category filter, which no engine builds in and every game does differently.
+
+An item takes two entries. Its definition goes in the game's items file, which each scene that names the item imports:
+
+```ts
+registerItem("potion", {
+    displayName: "Potion",
+    color: "crimson",
+    maxStack: 10,
+});
+```
+
+A Loot of it lies in a scene with a `<CharacterSpawn>`, whose character takes it into her bag as she walks over it; the engine draws it, and `<Bag />` shows it:
+
+```tsx
+<Entity position={[4, 0, -2]}>
+    <Loot item="potion" count={3} />
+</Entity>
+```

package/dist/wiki/engine/behaviours/loot.md

@@ -0,0 +1,90 @@
+---
+title: Loot
+description: A stack of an item lying in the world, which the player's character who reaches it takes into her bag.
+useCases:
+    - loot drop on the ground
+    - item lying in the world
+    - enemy drops loot
+    - treasure to collect
+    - drop an item from the bag
+    - loot stays after reload
+    - collect ground items
+    - glowing item pickup
+sidebar:
+    order: 12
+---
+
+Loot puts a stack of an item on an entity in the world. The character who walks within its radius takes it into her [bag](/engine/behaviours/inventory/), and whatever her bag cannot take stays on the ground. The character here is an entity that carries the `ControlledTrait` trait, whether or not a player controls it now: every character `<CharacterSpawn>` spawns, and any other entity `control` linked to a player, a kart she has left among them. A view reads her own character with `useCharacter()`.
+
+Its props are in [`LootProps`](https://wiki.spawnite.com/reference/inventory/lootprops/).
+
+## How it looks
+
+Loot draws the model its item's definition names in `model`. Where the definition names none, it draws a small glowing gem in the definition's `color`, white unless the definition says otherwise, so an item needs no model to be seen. Headless it draws nothing. Minecraft draws a lying item as its own icon, and Roblox draws a dropped Tool's handle; Unity, Unreal and Godot draw what the game gives them.
+
+## Taking it
+
+Each step, Loot adds its stack to the bag of the nearest character within `radius`, as `addItem` does: into the stacks it can merge with first, then empty slots. Its count drops by what the bag took, and the entity is destroyed when none is left. A character with a full bag, or with no bag, takes nothing, and the loot stays where it is.
+
+Loot and [Pickup](/engine/behaviours/pickup/) share the same reach check. Pickup stays for coins, which go into the wallet.
+
+## After a reload
+
+Loot comes back by default: each load lays the scene as it is written, so every loot lies again, whole. Give a loot an `id` and it stays taken instead: the save keeps what is left of it under `loot`, by id, and a reload lays only that, or nothing once it is all taken.
+
+```tsx
+import { Entity, Loot } from "@spawnite/engine";
+
+export function MeadowLoot() {
+    return (
+        <>
+            {/*  TakenEvent once, gone for good. */}
+            <Entity position={[3, 0, -2.5]}>
+                <Loot id="meadow-potions" item="potion" count={3} />
+            </Entity>
+            {/*  Back at every load. */}
+            <Entity position={[8, 0, 1]}>
+                <Loot item="herb" />
+            </Entity>
+        </>
+    );
+}
+```
+
+The id names this loot in the save, so it has to be unique in the game, and it has to stay the same between versions of the game, or a player's taken loot lies again. Two loot mounted at once with one id throw in development, naming the id. The save keeps what is left of each where the game's save includes `loot`, as [Saving progress](https://wiki.spawnite.com/learn/saving-progress/) says, so a game writes no code for it. The counts live on the world, so a save written from any scene keeps the loot taken in the others. A game with rooms keeps none: its loot is the room's. The `place_loot` tool takes an `id` too.
+
+No engine keeps this for you. Unity, Unreal, PlayCanvas and Roblox rebuild a level as authored, and the game saves the ids of taken objects itself; Godot saves only the nodes in its "Persist" group. Zelda: Breath of the Wild marks each object with its own revival policy, and Skyrim refills a whole area after days away. Loot takes the per-object choice, and makes the id the switch, since a stable name is what the save needs anyway.
+
+## Dropping it
+
+`dropItem(world, { holder, slot, count })` takes `count` copies out of bag slot `slot` and spawns an entity with Loot 1.5 metres in front of the holder, carrying the stack's data and the item's `model`. That is past a loot's default radius of 1 metre, so she does not take it back on the next step. It returns the new entity, or nothing when the slot is empty or holds fewer than `count`.
+
+An item's definition names the model it is drawn as in the world with `model`, a name registered with `registerModel`. A dropped copy is drawn as that model, or as the gem in the item's `color` where it names none, as a Loot in the scene is. In a room, `Replicas` draws it from the stream. Playing alone, the engine draws it itself, as it draws every entity that gameplay spawns with a model, such as a weapon's projectile: Roblox, Unity, Unreal and Godot draw a spawned object whether or not a network is up.
+
+## Where it runs
+
+Server. Loot has a consequence: it changes the character's bag.
+
+In the AI tree, a loot entity is its item's display name and count, `Potion ×3`, with the action "take it".
+
+## What other engines do
+
+Minecraft drops an item as its own entity carrying the stack, merges nearby stacks, and waits two seconds before anyone can pick it up. Unreal's Lyra spawns a collectable actor that holds item definitions or instances. Roblox moves the `Tool` itself into the workspace, and a touch collects it. Unity and Godot build in none. Loot takes Minecraft's item entity and leaves out its pickup delay, its despawn timer and the merging of stacks on the ground.
+
+```tsx
+import { Entity, Loot, registerItem } from "@spawnite/engine";
+
+registerItem("potion", {
+    displayName: "Potion",
+    color: "crimson",
+    maxStack: 10,
+});
+
+export function PotionPile() {
+    return (
+        <Entity position={[4, 0, -2]}>
+            <Loot item="potion" count={3} />
+        </Entity>
+    );
+}
+```

package/dist/wiki/engine/behaviours/pickup.md

@@ -0,0 +1,149 @@
+---
+title: Pickup
+description: Credits a reward to the player's character who reaches an entity.
+useCases:
+    - coin pickup
+    - collect coins
+    - reward for touching an item
+    - collectible gem
+    - pickup radius
+    - automatic pickup on walking over
+    - score from collectibles
+    - give the player coins
+    - spend coins
+    - charge a price
+sidebar:
+    order: 3
+---
+
+Pickup gives an entity a reward that goes to the character who walks within its radius. The character here is an entity that carries the `ControlledTrait` trait, whether or not a player controls it now: every character `<CharacterSpawn>` spawns, and any other entity `control` linked to a player, a kart she has left among them. A view reads her own character with `useCharacter()`.
+
+Its props are in [`PickupProps`](https://wiki.spawnite.com/reference/entity/pickupprops/).
+
+Pickup credits the character's `WalletTrait` through `addCoins`, so a coin picked up while a [Round](/engine/structure/round/) plays counts toward its score, and destroys the entity in the same step. Just before the destroy, the step emits the `TakenEvent` [event](/engine/structure/systems/#events) on the entity, which is what plays its [sound](/engine/audio/sound/): a pickup the scene removes untaken stays silent. In a room, the room sends `TakenEvent` to every page in the delta that removes the pickup, and each page lands it before it removes the pickup, so each page plays the sound whichever player took it.
+
+## Where it runs
+
+Server. Pickup has a consequence: it changes the character's wallet.
+
+```tsx
+import { Entity, Pickup, type EntityProps } from "@spawnite/engine";
+
+export function Coin({ position }: Pick<EntityProps, "position">) {
+    return (
+        <Entity model="coin" position={position}>
+            <Pickup reward={1} />
+        </Entity>
+    );
+}
+```
+
+## An effect where it is taken
+
+A "+1" or a burst of sparks where a coin is taken plays in a view that hears the coin's `TakenEvent`. The event's record is empty and the coin is gone by the time a view hears it, so the view sits under the coin's `<Entity>`, takes the place from the coin's own `position`, and passes `{ entity: useEntity() }`. Without `{ entity }`, every coin's view hears every coin's `TakenEvent`, and each coin plays its effect whenever any coin is taken. The scene mounts [`<FloatingText />`](/engine/ui/floating-text/) and [`<Particles effects>`](/engine/graphics/particles/) holding the sparks:
+
+```tsx title="packages/engine/test/outside/Coin.tsx"
+import {
+    Entity,
+    Pickup,
+    TakenEvent,
+    useEntity,
+    useEvent,
+    useFloatingText,
+    useParticles,
+    type ParticleEffect,
+    type Position,
+} from "@spawnite/engine";
+
+export interface CoinProps {
+    position: Position;
+    /** The burst where the coin is taken, one of the scene's
+     *  `<Particles effects>`. */
+    sparks: ParticleEffect;
+}
+
+export function Coin({ position, sparks }: CoinProps) {
+    return (
+        <Entity position={position}>
+            <Pickup reward={1} />
+            <CoinTaken position={position} sparks={sparks} />
+            <mesh>
+                <cylinderGeometry args={[0.4, 0.4, 0.1, 24]} />
+                <meshStandardMaterial color="gold" />
+            </mesh>
+        </Entity>
+    );
+}
+
+//  Under the coin's Entity, so `useEntity()` is this coin. Without
+//  `{ entity }` the view hears every coin's TakenEvent, and each coin
+//  would burst whenever any coin is taken.
+function CoinTaken({ position, sparks }: CoinProps) {
+    const floatingText = useFloatingText();
+    const particles = useParticles();
+    useEvent(
+        TakenEvent,
+        () => {
+            floatingText.show({ at: position, text: "+1", color: "gold" });
+            particles.spawn(sparks, { at: position, color: "#ffd166" });
+        },
+        { entity: useEntity() },
+    );
+    return null;
+}
+```
+
+## Coins a game pays
+
+A game pays and charges coins with the same two verbs Pickup uses, from a system on the room:
+
+- `addCoins(step, entity, amount)` adds `amount` to the entity's wallet, gives it a wallet where it has none, and adds `amount` to the coins the world has credited, whose rise a round in play scores.
+- `spendCoins(step, entity, amount)` takes `amount` off the wallet and returns `true` where the wallet holds all of it. Where it holds less, or the entity has no wallet, it takes nothing and returns `false`, so a shop sells whole or not at all. A spend never lowers a round's score.
+- `readCreditedCoins(world)` reads every coin `addCoins` has credited on the world, to any entity: a count that only rises, which a spend lowers no more than a wallet set by hand raises.
+
+The entity is whoever holds the wallet: a player's character, or the entity a player controls where she has no character, such as a rider on a track. Both verbs take the room's step first, as `dealDamage` does, because coins are an outcome; a call on a page in a room throws. An amount may be a fraction, and zero changes nothing. An amount below 0, or one that is no finite number, throws and names the call, and so does a credit that would leave the wallet, or the score of a round in play, at no finite number; each throws before anything changes.
+
+The following plugin pays every player's character a coin a second:
+
+```ts title="packages/room/test/outside/wage.ts"
+import type { World } from "koota";
+import {
+    addCoins,
+    ControlledTrait,
+    createQuery,
+    definePlugin,
+    readEach,
+    type AuthoritativeStep,
+} from "@spawnite/engine/core";
+
+//  A wage the room pays, built as a creator's plugin is, from the engine's
+//  public entry alone: a coin a second to every player's character, which
+//  her page reads from the stream and a round in play scores.
+
+const characters = createQuery(ControlledTrait);
+
+/** The room's steps between two wages: one second. */
+const wageTicks = 60;
+
+export const wage = definePlugin({
+    name: "outside-wage",
+    systems: {
+        rules: {
+            //  No `runsOn`, so it runs on the room alone, whose step is the
+            //  authority addCoins takes.
+            payWages: (world: World, step: AuthoritativeStep) => {
+                if (step.tick % wageTicks !== 0) return;
+                readEach(world, characters, (_, character) => {
+                    addCoins(step, character, 1);
+                });
+            },
+        },
+    },
+});
+```
+
+To charge for something the player gets, such as a potion from a merchant, spend only once the thing has a place to go: [the Dialog page's shop](/engine/behaviours/dialog/#a-shop) puts the potion in the bag first. Unity's Economy service names the same pair, an increment and a decrement of a player's balance; Roblox, Unreal and Godot leave the wallet to the game.
+
+In a view, `useWallet()` reads the player's coins. In a game played alone, its `spend(amount)` spends from a button: it answers at once from the coins the page last saw, and the next frame takes them off the wallet. Where a system spent those coins first, the wallet keeps what it holds, and in development the console says so. In a room, a page's `spend` changes no wallet, since the room's stream carries it. A purchase whose outcome matters, such as an item handed over, belongs in a system with `spendCoins`.
+
+The wallet reaches the next scene, such as a lobby shop after a run, and the next visit only where [the game's save](/engine/structure/saves/) lists `wallet` in `include`, as the example template's does: a scene change carries only the included saves onto the next scene's character.