Getting started

Embed the viewer on any page with an iframe. Drag to rotate. Scroll to zoom. The example below loads the AK-47 | Case Hardened finish.

<iframe
  src='{{origin}}/view?item={"id":215}'
  width="800"
  height="600"
  loading="lazy"
></iframe>

Parameters

Set what the viewer shows and how it frames the item with URL parameters on /view.

Parameter Example Description
item {"id":215} Economy item JSON. The id may be a number or {"def":7}. Def shorthand resolves to the base item; paint-kit index is not used for resolution. Optional wear (0..1) and seed (0..1000) set the finish. Changing them on the same id updates the render in place. Set autoInspect to true for a slow back-and-forth inspect orbit. Set editable to true to click-drag stickers and the charm (placements emit change / getState). Weapons accept stickers (slot → {id, wear?, x?, y?, rotation?, schema?}) and keychains (usually "0" → {id, seed?, x?, y?, z?}). Placement fields round-trip through getState / change so a host can recreate the item.
model weapon_rif_ak47_a4fa808a.glb Load a GLB from /models directly. Takes precedence over item.
cdn https://assets.example.com Base URL for models, images, materials, textures, shaders and animations. Defaults to the viewer origin.
zoom 1.5 Initial framing multiplier. Defaults to 1.
icon ?icon Still mode. Plays the icon clip once and clamps the last frame.
capture ?capture Still mode with the same framing, intended for clean capture output.

Embed API

The viewer exchanges postMessage envelopes over version 1. Messages have this shape:

{
  "source": "cs3d.hexium.cc",
  "v": 1,
  "id": "optional-reply-id",
  "type": "setItem",
  "data": { "item": { "id": 215, "wear": 0.1, "seed": 42 } }
}

Keep source as cs3d.hexium.cc unless you build with a different VIEWER_SOURCE. The default is required by InventorySim. Target the iframe's contentWindow and check event.source on replies.

const frame = document.querySelector("iframe");

frame.contentWindow.postMessage({
  source: "cs3d.hexium.cc",
  v: 1,
  type: "setItem",
  data: { item: { id: 215, wear: 0.1, seed: 42 } }
}, "*");

Commands

Send these message types to the viewer.

Type Data Reply
ping None ready
getState None state, echoing id
setItem {item: {...}} None. Emits change, loading and rendered.
capture {item?: {...}} captured, echoing id, with a WebP blob in data.image. The captured item includes current sticker/charm placements.
setSelection {selection: {kind:"sticker"|"keychain", index} | null} change
setActiveSticker {index: number | null} change
highlightSticker {index: number} change
setStickerWear {index, wear} change (live scrape)
setStickerSchema {index, schema} change
setKeychain {index, id} change
removeKeychain {index} change
setKeychainSeed {index, seed} change
setKeychainPosition {index, x, y, z} change
clearKeychainPosition {index} change — drops x/y/z so the host default applies
rerollKeychainPosition {index} change (API parity; mesh anchors land later)

Stickers render on the weapon from item.stickers. Click-drag on the model updates x/y and emits change with the new offsets. Charms hang on the weapon from item.keychains (id / seed / x/y/z) using the model's charm attachment point.

// Stickers + charm placement (InventorySim / 3d.cstrike.app shape)
frame.contentWindow.postMessage({
  source: "cs3d.hexium.cc",
  v: 1,
  type: "setItem",
  data: {
    item: {
      id: 215,
      wear: 0.1,
      seed: 42,
      stickers: {
        0: { id: 76, wear: 0, x: 0.02, y: -0.01 },
        1: { id: 76, wear: 0.2, rotation: 15 }
      },
      keychains: {
        0: { id: 12, seed: 1, x: 0.5, y: 0.1, z: 0.2 }
      }
    }
  }
}, "*");

// Read back after drag / edits
frame.contentWindow.postMessage({
  source: "cs3d.hexium.cc",
  v: 1,
  id: "s1",
  type: "getState"
}, "*");
// → state.data.item.stickers / .keychains, .selection, .keychainDefault

Events

These message types are sent by the viewer.

Type Data When
ready {v:1} On boot and in reply to ping.
change {item, selection, activeSticker, schemaCount, keychainDefault} — item includes live stickers / keychains placements After setItem, sticker drag, wear/position edits, or selection changes.
loading {busy:boolean} When a load starts and finishes.
rendered {item} When an item is visible.
unsupported {reason} An item cannot render. Reasons: weapon, sticker, keychain, patch, clip, network, webgl, asset.
state Current viewer state Reply to getState.
captured {item, image, apiCalls} Reply to capture.

HTTP API

The server also exposes item lookup and asset endpoints.

Route Description
GET /api/item?id=<economyId> Resolve an economy id to model, material and kind. ?def=<defindex> also works.
GET /api/browse?kind=<kind> List items with files on disk. Kinds: weapon, melee, gloves, agent, pet, petTool, graffiti, sticker, charm (keychain kind; no model required).
GET /api/catalog Supported-id manifest: {maxId, holes}.
GET /api/composite-inputs?material=<name> Resolve a material name to its composite inputs file.
POST /api/rate-limit Reports no quota. Self-hosted installs are not rate limited.
POST /api/inspect-link Body { item } (id / wear / seed / stickers / charms). Returns a CS2 steam:// inspect link via @ianlucas/cs2-lib-inspect. Long payloads may return a console command instead (steam: false).
/models, /images, /materials, /textures, /shaders, /animations Static files from ASSETS_DIR.

Use /viewer to try items and inspect protocol messages without writing a host page.