Skip to content

Show a player's items and craft with them

In this guide you'll read what a player owns, show it, and let them turn items into a new item by paying a pool, all without a game server. Economy is the truth: the game asks for the player's items and sends a payment; Economy decides what comes out. (What used to be a separate "craft" call is now a roll by payment: a pool whose cost equals the payment exactly.)

It takes 20 to 30 minutes. You'll need the SDK installed and the player signed in (Install the SDK).

Step 1: Read the inventory

var inventory = Otomo.Instance.Client.Inventory;
var snapshot = await inventory.RefreshAsync();

long water = snapshot.Count("resource.water_essence");   // 0 when the player has none
bool hasJet = snapshot.Owns("spell.water_jet");
long coins = snapshot.Balance("coin");

RefreshAsync reads items and money together. Call it when a screen opens, not on a timer: callers that arrive while a read is running share it, so several screens opening at once cost one pair of requests. inventory.Current is the last snapshot, and is null before the first refresh and after sign-out.

inventory.Changed is raised when a refresh finds something different. It can arrive on a background thread, so in Godot defer to the main thread (CallDeferred) before touching a node.

Step 2: Roll a pool by paying its cost

using OtomoSdk.Economy;

var payment = new List<Payment>
{
    Payment.OfItem("resource.water_essence", 2),
    Payment.OfItem("resource.nature_essence", 1),
};
RollAttempt attempt = await Otomo.Instance.Client.Pools.RollByPaymentAsync(payment);

switch (attempt.Outcome)
{
    case RollOutcome.Rolled:  /* attempt.Result.Draws[0].Item is what came out */ break;
    case RollOutcome.NoMatch: /* no open pool costs exactly this; nothing was spent */ break;
    case RollOutcome.Refused: /* attempt.Code: insufficient_items, insufficient_funds, pool_closed ... */ break;
}

To roll a pool you already know by id, RollAsync(poolId, count) pays the pool's cost (times count).

  • A refusal is a result, not an exception, and nothing changes. Other errors (signed out, service down) throw OtomoError.
  • The inventory is refreshed for you after a roll that changed anything, so inventory.Current is right when the call returns.
  • A retry is safe: the client makes one idempotency key per call and the transport reuses it if it has to retry. If your code retries after an error, pass the same key: RollByPaymentAsync(payment, key).

Step 3: The pool list

IReadOnlyList<PoolInfo> pools = await Otomo.Instance.Client.Pools.ListPoolsAsync();

You get the listed pools, plus unlisted ones the player has already found (rolled once). A pool carries its cost, its entries with their weights, and PaymentMatch (a roll by payment can reach it). Pools that are not listed stay hidden until found.

The shop, tasks and waiting rewards are Client.Shop, Client.Tasks and Client.Entitlements; see the SDK reference.

Play offline, or test without a server

FakeEconomyBook, FakeInventoryClient and FakePoolClient follow the same rules as the service (exact match, a refused roll changes nothing, a repeated key returns the first result). Put in whatever the game needs:

var book = new FakeEconomyBook()
    .Grant("resource.water_essence", 10)
    .AddPool("jet",
        cost: new[] { Payment.OfItem("resource.water_essence", 2), Payment.OfItem("resource.nature_essence", 1) },
        entries: new[] { ("spell.water_jet", 1L) },
        listed: false,
        paymentMatch: true)
    .Discover("jet");
var inventory = new FakeInventoryClient(book);
var pools = new FakePoolClient(book, inventory);

Copies of an item, and upgrading one

A game can declare an item as instanced: a player then holds several copies of it, each with its own numbers that Economy rolled. A copy is a row of the inventory with a UniqueRef, and a roll that makes one carries it on the draw:

RollAttempt brew = await Otomo.Instance.Client.Pools.RollByPaymentAsync(payment);
InstanceRef copy = brew.Result!.Draws[0].Instance!;          // null for an ordinary item

InventorySnapshot items = await Otomo.Instance.Client.Inventory.RefreshAsync();
IReadOnlyList<OwnedItem> copies = items.Copies("spell.fireball");   // each has UniqueRef and Attrs

Upgrading spends materials on one copy. Ask for the rules once, and preview before sending: the preview says whether the pot is the exact cost of a whole number of levels, what the main stat is certain to reach, and the chance and size of each outcome of the first level. The server makes every roll; its answer lists the chances each level really used.

var instances = Otomo.Instance.Client.Instances;
InstanceRules rules = await instances.RulesAsync();
var pot = new[] { Payment.OfItem("resource.fire_essence", 9), Payment.OfItem("resource.water_essence", 2) };

UpgradeOddsPreview preview = rules.Preview(copy.Attrs, "spell.fireball", pot);
if (!preview.Valid) { /* preview.Reason, and preview.ValidTotals to guide the player */ }

UpgradeAttempt upgrade = await instances.UpgradeAsync("spell.fireball", copy.UniqueRef, pot);
if (upgrade.Ok) { /* upgrade.Result.Steps: per level, the odds used and what rose */ }
else { /* upgrade.Code: pot_not_exact, insufficient_items, instance_max_level, ... */ }

DismantleAttempt gone = await instances.DismantleAsync("spell.fireball", copy.UniqueRef);

A roll is refused with instance_limit when the player already holds as many copies as the rules allow; nothing is spent. Offline, FakeEconomyBook.LoadInstanceRules(json) with the same instances block makes the book grant, upgrade and dismantle copies by the same rules, and FakeInstanceClient stands in for Instances.

Errors you will see

OtomoError.Code Meaning
rate_limit_exceeded Too many requests. The SDK already waited (honouring Retry-After) and retried; show a "try again"
insufficient_items, insufficient_funds, pool_closed, unknown_pool, no_match Not thrown: they come back as a RollAttempt
anything else Throws OtomoError; see Troubleshooting