Currency And Shops

From adm/etc/default.lpml:

CURRENCY: [
    ["copper",   1   ],
    ["silver",   10  ],
    ["gold",     100 ],
    ["platinum", 1000],
]

Each entry is [name, value_in_base_units]. Copper = 1 is the base denomination. All internal values are in base (copper) units.

Related config:

Currency Daemon — adm/daemons/currency.c

Singleton daemon. Macro: CURRENCY_D.

Wealth — std/living/wealth.c

Inherited by STD_BODY. Tracks coins as a mapping of { currency_name: count }.

Variable

private nomask mapping _wealth = ([]);   // e.g., ([ "copper": 50, "gold": 3 ])

Functions

Important: adjust_wealth returns mixed — it can return an error string if the currency is invalid, funds are insufficient, or the player can't carry the weight. Always check the return type.

Transaction Module — std/ext/currency.c

Macro: EXT_CURRENCY. Inherited by both shop modules.

handle_transaction(object tp, int cost) : mixed

Entry point for all purchases. cost is in base (copper) units.

Returns either:

• string — error message
• ({ paid_array, change_array }) — success

Where each array contains ({ currency_name, amount }) pairs.

Transaction Algorithm (complex_transaction)

1. Compute total_wealth in base units. Fail if insufficient.
2. Iterate denominations highest to lowest.
3. For each: take min(available, ceil(remaining / rate)) coins.
4. If still short after first pass, retry lower denominations.
5. Compute change from overpayment, broken into fewest coins (highest to lowest).
6. Check mass capacity (net coin change vs available capacity).
7. Apply: adjust_wealth(currency, -amount) for each payment, adjust_wealth(currency, amount) for each change coin.

reverse_transaction(object tp, mixed result) : mixed

Critical for error recovery. Reverses a completed transaction when a subsequent operation fails (e.g., item won't fit in inventory).

// In a buy command:
mixed result = handle_transaction(tp, cost);
if(stringp(result)) return result;  // payment failed

if(stringp(ob->move(tp))) {
    reverse_transaction(tp, result);  // MUST reverse or coins are lost
    return "You can't carry that.";
}

least_coins(int total_amount) : mapping

Breaks a base-unit amount into the minimum number of coins per denomination. Does not deduct anything — pure calculation.

least_coins(125)  // → ([ "gold": 1, "silver": 2, "copper": 5 ])

Used by EXT_SHOP's sell command to compute payout.

Other Functions

Inventory-Based Shop — std/ext/shop.c

Macro: EXT_SHOP. Inherits EXT_CURRENCY and CLASS_STORAGE.

Items are stored in a persistent STD_STORAGE_OBJECT. Players buy items out of it and sell items into it.

Setup Pattern

inherit STD_ROOM;
inherit EXT_SHOP;

void setup() {
    // ... room descriptions, exits, etc. ...
    init_shop();
    add_shop_inventory(
        "/obj/weapon/piercing/rusty_sword",
        "/obj/armour/torso/leather_jerkin",
    );
}

Variables

Commands

buy <item>: Finds item in storage via present(str, store). Calls handle_transaction(tp, cost). Moves item to player. On move failure, calls reverse_transaction. Sends action messages.

sell <item> / sell all / sell all <item>: Finds items on player. For each: checks query_cost(tp, ob, "sell") (returns null to refuse), skips equipped items, moves to store, pays player via least_coins(cost) → adjust_wealth() per denomination.

list: Shows all items in storage with prices.

Pricing — query_cost()

Storage Object

Created via create_storage() using class StorageOptions:

class StorageOptions {
    string storage_type;       // "public" or "private"
    mixed  storage_id;         // ID string or function
    string storage_org;        // namespace
    string storage_directory;  // filesystem path
    int    clean_on_empty;     // remove when empty
    int    restore_on_load;    // restore from saved data
}

The storage object has ignore_capacity(1) and ignore_mass(1) — no limits on stored items.

Known issue: create_storage() currently has a hardcoded storage_org. Each shop must override this or they share storage.

Menu-Based Shop — std/ext/shop_menu.c

Macro: EXT_SHOP_MENU. Inherits CLASS_MENU and EXT_CURRENCY.

Items are cloned fresh on each purchase. No storage object. No sell command. Ideal for food, drink, and consumable vendors.

Setup Pattern

inherit STD_ROOM;
inherit EXT_SHOP_MENU;

void setup() {
    // ... room descriptions, exits, etc. ...
    init_shop();
    add_menu_item("food", "/obj/food/bread", 5);
    add_menu_item("drink", "/obj/drink/ale", 8);
}

Menu Item Data — class Menu

class Menu {
    string type;          // category (e.g., "food", "drink")
    string file;          // blueprint file path
    string short;         // display name
    string *id;           // ID array for matching
    string *adj;          // adjective array
    string description;   // long description
    int cost;             // price in base units
}

Functions

Commands

buy <item>: Searches food_menu by ID. Calls handle_transaction. Clones new(item.file). Moves to player. Reverses on failure.

list / menu [type]: Shows all items or filtered by type with prices.

view <item>: Shows item short + long description.

When to Use Which Shop

Bank System

Bank Daemon — adm/daemons/bank.c

SQLite-backed via DB_D. Stores a single balance in base (copper) units.

Bank Module — std/ext/bank.c

Macro: EXT_BANK. Provides room commands.

inherit STD_ROOM;
inherit EXT_BANK;

void setup() {
    // ... room setup ...
    init_bank();
}

Commands: register, deposit <num> <type>, withdraw <num> <type>, balance.

Key design: Deposits convert denomination to copper for storage. Withdrawals convert copper back to the requested denomination. You can deposit 1 gold and withdraw 100 copper.

Coin Objects — lib/coin.c

Physical coin items that exist in rooms and containers.

Behavior

• Moving to a living: The coin object self-destructs and calls dest->adjust_wealth(coin_type, coin_num). Coins dissolve into the wealth mapping.
• Moving to a container: Merges with existing same-type coin stacks via adjust_coin_num(). Different types coexist as separate objects.
• Mass: Each coin has mass equal to its count (set_mass(num)).

Constructor

new(LIB_COIN, "gold", 5)   // creates a stack of 5 gold coins

Key Functions

Critical: query_value() on a coin returns ({ num, type }) — an array, not an integer. This intentionally differs from STD_VALUE::query_value() which returns int. Code handling mixed item types must account for this.

Item Value — std/object/value.c

All items inherit this via STD_ITEM.

set_value(50);       // 50 copper
query_value();       // 50
adjust_value(10);    // now 60 (but not auto-persisted!)

Note: set_value() calls save_var("_value") for persistence, but adjust_value() does not. Changes via adjust_value() are lost on reload unless save_var is called separately.

Loot Value Calculation

When NPCs drop loot, LOOT_D can auto-value items:

determine_value_by_level(level):
    value    = level * COIN_VALUE_PER_LEVEL (15)
    variance = COIN_VARIANCE (0.25) * value
    subtract = to_int(variance) / 2
    value   -= subtract
    value   += random(to_int(variance) + 1)

Level 10 NPC: base 150, range ~131-169 copper.

Triggered when a loot item has query_loot_property("autovalue") == true.

GMCP Integration

Wealth changes send GMCP from adjust_wealth() and wipe_wealth():

Package: "Char.Status"
Label:   "wealth"
Payload: ([ currency_name: sprintf("%d", amount) ])

No GMCP is sent directly by shop modules. Item movement triggers GMCP_PKG_CHAR_ITEMS_LIST via STD_ITEM::move().

Death and Wealth

On die() in body.c:

1. query_all_wealth() is iterated.
2. Each denomination becomes new(LIB_COIN, type, amount).
3. Coin objects are moved to the corpse.
4. Player's wealth is effectively wiped (coins are now objects in the corpse).

Gotchas

1. All values are in base (copper) units internally. set_value(100) means 100 copper = 1 gold. Shops, transactions, and bank all work in copper.
2. adjust_wealth() can silently fail. It returns a string on error (invalid currency, insufficient funds, over encumbrance). Always check the return type.
3. reverse_transaction() is mandatory on buy failure. If handle_transaction succeeds but the item can't be moved to the player, you must call reverse_transaction or coins are duplicated/lost.
4. Two shop architectures serve different purposes. EXT_SHOP for persistent inventory (gear shops). EXT_SHOP_MENU for clone-on-demand (food/drink vendors). Using EXT_SHOP for consumables causes persistent item accumulation.
5. query_value() on coins returns an array, not int. Code that handles mixed items must check for this.
6. adjust_value() does not persist. Only set_value() calls save_var().
7. Bank stores copper internally. Deposit 1 gold, withdraw 100 copper — this is by design.
8. The complex_transaction algorithm can over-draw from higher denominations, producing non-optimal change. This is a known limitation.