scene_add_item
Define a backpack item in a copied save with currency value, icon, stack limit, and optional use graph, enabling shops and graphs to manage quantities.
Instructions
Define an item (道具) in a copy of a save: a thing a character holds in its backpack in numbers (fruit, wood, a key), which a shop can sell or buy. Define a currency first (scene_add_currency gives every character the backpack). value is what one of it is worth in a currency (the currency by name or id); icon is the number of an item icon (90001 an apple, 90015 fowl meat). A graph gives and takes it with f.modifyInventoryItemQuantity(character, itemId, change) and reads f.getInventoryItemQuantity(character, itemId). The events about an item (whenItemIsAddedToInventory, whenItemIsLostFromInventory, whenTheQuantityOfInventoryItemChanges, whenItemsInTheInventoryAreUsed) arrive only in the item's own item graph (useGraphId), not in a graph on the character or the player; only the currency event goes to the holder. The record written is byte for byte the item of the official sample 货币与商店. Verified in play on 2026-10-11 (bought and sold in a shop, counted by a graph). category "consumable" with useGraphId makes it an item the player uses from the backpack: useGraphId is an item graph (scene_add_graph {kind: "item"}, source g.server({id, name, type:'item'}).on('whenItemsInTheInventoryAreUsed', ...)), the record being that of the fowl meat of the official sample 掉落物、道具、背包; evt.itemOwnerEntity is the character that used it and evt.amountToUse how many. The player presses B for the backpack, clicks the item, 使用 and 确认; useCooldownSeconds is how long the item then waits before it can be used again (10 when left out). Verified in play on 2026-10-11 (examples/potion). Equipment is not made; the drop that lies on the ground is scene_add_prefab {drop}. Writes a new .gil in the workspace; the official save is not touched.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| icon | No | ||
| name | Yes | ||
| value | No | ||
| mapPath | No | ||
| category | No | material | |
| outputName | No | ||
| stackLimit | No | ||
| useGraphId | No | ||
| description | No | ||
| useCooldownSeconds | No |