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.Currentis 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¶
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 |