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.