---
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 and the skills). Its models, animations and textures, Anima included, are CC BY 4.0: free to use with attribution to Jimmy Lee (j@internet.dev). 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.15.35"
  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, 4 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.771,
  "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.771,
        "tierName": "Grade C",
        "material": { "name": "steel", "materialRank": 9, "tier": 4, "tierGrade": "C", "tierName": "Grade C" }
      }
    ]
  },
  "seed": null,
  "contentVersion": "8.1bmmTgz1B0Y9UKhiu84STg"
}
```

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 6 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, rare grades included. Orbs buy control instead, through the craft endpoint, which returns the same `Item`. Every grade in a craft is gated by its guarantee price, so a craft reaches the grades its spend pays for far more surely than a free roll. A grade far above its spend comes *less* often than from a free roll, while the next grade up becomes likelier than a free roll as the spend nears that grade's price ([Crafting an item](https://set.world/skills/crafting-an-item) has the exact odds).

| Call | Your player pays | What comes back |
| --- | --- | --- |
| `/api/roll/item?seed=` | Nothing | One ordinary roll: Grade C or better 42.3% of the time, Grade B or better 12.1%, Grade S 1.45% |
| `/api/craft?orbs=N&seed=` | N orbs, up to 15,625 | The best of several candidates: the best grade and quality among them, and the rarest prefix and suffix. At 125 orbs (the Grade C price), Grade C or better 57.3% and Grade B or better 1.1%; at 15,625, Grade B or better 98.8% and Grade S 39.1% |
| `/api/craft?tier=T&seed=` | The grade's fixed price | Exactly that grade, F to S, unless a small explicit `budget=` runs out first (`capped: true`) |

More orbs draw more candidates and open higher grades as the spend reaches their price. 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: your game tracks the balance, checks it before the call and subtracts the spend after. How your own resources become orbs is the bridge in [Crafting an item](https://set.world/skills/crafting-an-item).

```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).
