Items

The Items resource is the catalog — one row per distinct item the game knows about. Player ownership lives in a separate table (item_instances) under /v1/users/@me/inventory.

Catalog is global and read-mostly: admins author rows, everyone reads. Reads need only an authenticated user; every write (POST, PATCH, DELETE, uploads) requires the items.write permission.

The Item object

List

curl "https://api.localuniverse.io/v1/items?type=4&limit=20" \
  -H "authorization: <token>"

[
  { "id": "3091...", "name": "Cosmic Bass", "type": 4, "rarity": 3, ... },
  { "id": "3092...", "name": "Sapphire Hat", "type": 2, "rarity": 4, ... }
]

Get, create, update, delete

CreateItem body

Asset uploads

Three multipart endpoints. Each returns the content hash; the admin client stamps it onto the create-item payload.

Icon

curl -X POST https://api.localuniverse.io/v1/items/uploads/icon \
  -H "authorization: <token>" \
  -F "file=@./icon.png"

{ "hash": "a1b2c3d4e5f60123" }

Spritesheet

curl -X POST https://api.localuniverse.io/v1/items/uploads/spritesheet \
  -H "authorization: <token>" \
  -F "file=@./spritesheet.png"

Manifest

curl -X POST https://api.localuniverse.io/v1/items/uploads/manifest \
  -H "authorization: <token>" \
  -F "spritesheet_hash=a1b2c3d4e5f60123" \
  -F "file=@./spritesheet.json"

Randomization

When layers is set on a catalog row, and the grant call opts in with randomize: true, the grant flow composites a unique spritesheet + icon per instance and stamps the resulting hashes onto the item_instance row.

{
  layers: number,            // dye-zone count
  hue_centers: number[],     // original hues for roll bias
  textures: string[],        // texture names in the prefab that get tinted
  icon: string               // master icon name
}

The sprite renderer reads master _layer1.png…_layerN.png (plus optional _outlines.png) under textures/<master>/ in CDN_BUCKET, multiplies each by a rolled tint, composites, hashes the result, and writes it to textures/<hash>.png. Every sibling under the master directory matching <master>.<ext> (manifest, atlas, etc.) gets copied next to the hashed output. See packages/sprite-tools for the splitter that authors layer assets.

Properties

The catalog row's properties column is a Record<string, PropertyDescriptor> map. At grant time each descriptor rolls into a concrete value and the result is stamped onto item_instances.properties so it stays stable for the lifetime of the instance.

{
  "equipment_type": { "value": 1, "resolve": "fixed" },
  "durability":     { "min": 50, "max": 100, "resolve": "range" },
  "rarity_bonus":   {
    "min": 0, "max": 1, "mean": 0.3, "stddev": 0.15,
    "precision": 2, "resolve": "curve"
  },
  "skin_variant":   {
    "values": ["red", "blue", "green"],
    "weights": [3, 1, 1],
    "resolve": "pool"
  },
  "blessed":        { "value": true, "resolve": "fixed", "required": false, "probability": 0.05 }
}

{
  "equipment_type": 1,
  "durability": 87,
  "rarity_bonus": 0.42,
  "skin_variant": "red"
}

blessed was skipped in this roll — required: false plus probability: 0.05 means it lands on roughly 5% of grants and otherwise doesn't appear in the result at all.

Resolvers

Every descriptor optionally carries required: false + probability to make the key itself probabilistic — useful for chance-of-drop modifiers like blessed, cursed, lucky, etc.

The whole roll lives in @localuniverse/common/property-resolver and is called once at grant time. Unknown resolve values throw — catalogs author against known strategies and a typo should fail loudly rather than silently dropping a property.

Inventory

Owned instances of catalog items live on the user resource:

Gameplay drops (fish caught, NPC reward) call itemInstanceService.grant() directly — they don't round-trip through HTTP.