---
name: set-rolling-an-item
description: How to roll items with the Set World API. Use when generating loot, a single item or a full 15-item equipment set, reading an item's schema (name, slot, roll vector, grade, material, rarity score, orb value), spending orbs to get a better item than an ordinary roll, turning an item into a shareable page or a 3D model link, or storing items in a game's inventory.
license: Free to use when obtained from set.world, commercially too (the API, what it returns, the skills and downloaded models). The source code of Set is © Jimmy Lee under CC BY-NC 4.0 and its commercial use needs a paid waiver.
metadata:
  version: "0.8.9"
  title: Rolling an item
---

# Rolling an item

An item is one draw from 19 weighted tables. Its name is `{quality} {prefix} {material} {gear} of the {suffix}`, with empty parts dropped: `fine burning steel sword of the dawn`, or just `iron dagger`. Items are stateless: the 19-number roll vector is the whole item, and everything else is derived from it.

## Roll one item

```sh
curl https://set.world/api/roll/item              # random
curl 'https://set.world/api/roll/item?seed=42'    # reproducible
```

## The item schema

`Slot` is the union of the 13 slot names, defined in [Slots](https://set.world/skills/equipment-slots). `Grade` and `Material` are defined in [Materials](https://set.world/skills/item-materials).

```ts
type Prop = { name: string; weight: number | string };   // a raw table row; "-" means no word

type Item = {
  name: string;                    // the composed name
  slot: Slot;                      // one of the 13 slots; "tool" is the mainhand
  slotIndex: number;               // the index of the slot's gear table, 5..17
  props: [Prop, Prop, Prop, Prop, Prop];   // [quality, prefix, material, gear, suffix]
  roll: number[];                  // 19 raw rolls, one per table: the item's identity
  indexes: number[];               // 19 table positions those rolls select
  score: number;                   // rarity score, -log10 of the item's probability, four decimals
  materialRank: number;            // scarcity rank of the material in its table, 1 most common
  tier: number;                    // 1..7
  tierGrade: Grade;                // the grade, set by the material alone
  tierName: string;                // "Grade F" … "Grade S"
  orbValue: number;                // the guarantee price of the grade: 1, 5, 25, 125, 625, 3125, 15625
  material: Material;
  affects: string[];               // the slot's advisory attribute domain
};

type SlotBreakdown = {
  slot: Slot;
  affects: string[];
  items: Array<{ name: string; orbValue: number; materialRank: number; tier: number; tierGrade: Grade; score: number; tierName: string; material: Material }>;
};

type RollItemResponse = Item & { breakdown: SlotBreakdown; seed: number | null; contentVersion: string };
```

A full response, computed from the current tables. This item is built from named table entries rather than a seed, so `seed` is null:

```json
{
  "name": "fine burning steel sword of the dawn",
  "slot": "tool",
  "slotIndex": 8,
  "props": [
    { "name": "fine", "weight": 42699 },
    { "name": "burning", "weight": 1 },
    { "name": "steel", "weight": "35600" },
    { "name": "sword", "weight": "1" },
    { "name": "dawn", "weight": "1" }
  ],
  "roll": [119899, 493, 0, 430998, 9100, 0, 0, 0, 52, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1108],
  "indexes": [5, 5, 0, 10, 3, 0, 0, 0, 52, 0, 0, 0, 0, 0, 0, 0, 0, 0, 10],
  "score": 10.7359,
  "materialRank": 9,
  "tier": 4,
  "tierGrade": "C",
  "tierName": "Grade C",
  "orbValue": 125,
  "material": { "name": "steel", "materialRank": 9, "tier": 4, "tierGrade": "C", "tierName": "Grade C" },
  "affects": ["physicalDamage", "magicalDamage", "attackSpeed"],
  "breakdown": {
    "slot": "tool",
    "affects": ["physicalDamage", "magicalDamage", "attackSpeed"],
    "items": [
      {
        "name": "fine burning steel sword of the dawn",
        "orbValue": 125,
        "materialRank": 9,
        "tier": 4,
        "tierGrade": "C",
        "score": 10.7359,
        "tierName": "Grade C",
        "material": { "name": "steel", "materialRank": 9, "tier": 4, "tierGrade": "C", "tierName": "Grade C" }
      }
    ]
  },
  "seed": null,
  "contentVersion": "4.swpi78HUCtcrZ1Eoi9dipw"
}
```

Reading it:

- Take the gear from `props[3].name` and the material from `props[2].name`. Never parse the composed name.
- A table `weight` is a number in some tables and a numeric string in others; treat it with `Number()`.
- `roll` and `indexes` always have 19 entries. Only six positions matter for a given item; [Item properties](https://set.world/skills/item-properties) explains which and serves the tables.
- The grade and what it is worth are owned by [Materials](https://set.world/skills/item-materials); `affects` by [Slots](https://set.world/skills/equipment-slots); `score` by [Calculations](https://set.world/skills/calculations).

## Roll a full equipment set

```sh
curl 'https://set.world/api/roll/set?seed=7'
```

```ts
type Equipment = Record<Exclude<Slot, 'hand' | 'finger'>, Item> & { hand: [Item, Item]; finger: [Item, Item] };

type RollSetResponse = {
  equipment: Equipment;            // 15 items
  orbValue: number;                // the sum of the 15 orb values
  orbBreakdown: SlotBreakdown[];   // one row per slot, in canonical slot order
  seed: number | null;
  contentVersion: string;
};
```

The slot order is owned by [Slots](https://set.world/skills/equipment-slots); a filled `Equipment` object is shown in [Rolling a character](https://set.world/skills/rolling-a-character).

## Spend orbs for a better item

`/api/roll/item` is free and ordinary: one draw, whatever comes. To get a better item, your game spends orbs through the craft endpoint. It returns the same `Item`.

| Call | Your player pays | What comes back |
| --- | --- | --- |
| `/api/roll/item?seed=` | Nothing | One ordinary roll: Grade B or better 11.1% of the time, Grade S 1.47% |
| `/api/craft?orbs=N&seed=` | N orbs, up to 15,625 | The best of several candidates, with the rarest quality, prefix and suffix among them. At 125 orbs, Grade B or better 0.95%; at 15,625, 98.2%, and Grade S 39.5% |
| `/api/craft?tier=T&seed=` | The grade's fixed price | Exactly that grade, F to S |

More orbs draw more candidates and open higher grades. The odds at every spend, the price of each grade and both response schemas are in [Crafting an item](https://set.world/skills/crafting-an-item).

**Orbs are your game's currency, not Set's.** Set has no wallet and no rule for earning orbs: your game tracks the balance, checks it before the call and subtracts the spend after. That lets a game keep its own economy and use orbs as the bridge. A game with wood, stone and ore can price each in orbs, convert what the player pays and craft with the total: at the example rates in [Crafting an item](https://set.world/skills/crafting-an-item), 20 wood, 15 stone and 8 iron ore become 130 orbs.

```js
async function buyItem(wallet, orbs, seed) {
  if (wallet.orbs < orbs) throw new Error('Not enough orbs.');          // your ledger, your rule
  const response = await fetch(`https://set.world/api/craft?orbs=${orbs}&seed=${seed}`);
  const craft = await response.json();
  if (!response.ok) throw new Error(craft.error.message);
  wallet.orbs -= craft.orbs;                                            // the effective spend the response reports
  return craft.item;
}
```

## Share or inspect an item

Any item opens at its weighted-table page, which shows each table it used and every option's odds:

```text
https://set.world/roll/item/<roll joined by dashes>
https://set.world/roll/item/119899-493-0-430998-9100-0-0-0-52-0-0-0-0-0-0-0-0-0-1108
```

`https://set.world/roll/item?seed=42` rolls the same item as the API and redirects there. For the item's 3D model, see [Item models](https://set.world/skills/anima-item-models).

## Appraise an item you stored

Appraisal endpoints take either `rolls=` or `indexes=`: 19 dash-joined integers, never both.

| To get | Call | Owner |
| --- | --- | --- |
| Grade, score and per-factor rarity | `/api/rarity?rolls=…` | [Calculations](https://set.world/skills/calculations) |
| Advisory power budget and themes | `/api/modifiers?rolls=…` | [Calculations](https://set.world/skills/calculations) |
| Orbs returned if destroyed | `/api/salvage?rolls=…` | [Crafting an item](https://set.world/skills/crafting-an-item) |

## A schema for your inventory

Set stores no inventory. A game needs only the roll vector and the snapshot to rebuild an item, plus whatever it adds:

```ts
type InventoryItem = {
  id: string;                      // your own ID
  ownerId: string;
  roll: number[];                  // rebuilds the item at /roll/item/<roll>; re-appraise with /api/rarity?rolls=
  contentVersion: string;          // the snapshot the roll was read against
  item: RollItemResponse;          // keep the full object: old snapshots are not hosted
  acquired: { source: 'drop' | 'craft' | 'birth'; seed: number | null; at: string };
  equippedSlot: Slot | null;
  state: Record<string, unknown>;  // durability, sockets, enchantments: yours
};
```

## Rules

- One item per request. For many items, derive one seed each ([Rolling a group](https://set.world/skills/rolling-a-group)).
- To buy a grade instead of rolling for one, craft ([Crafting an item](https://set.world/skills/crafting-an-item)).
- Items carry no resolved stat modifiers. Damage, weight and effects are your game's rules; Set's own reading is [Derived stats](https://set.world/skills/anima-derived-stats).