The item framework stays renderer-neutral while exposing a complete 3D preview state for inventory, vendor, loot, and equipment inspection UI.
Preview State#
createItemPreviewViewer(database, item) accepts either an item definition or
an item instance. It resolves the item definition, applies localization when
requested, and returns:
- preview asset references for icon, mesh, and material
- a scene node with transform data for the item mesh
- orbit camera settings with distance and pitch limits
- studio lighting settings
- orbit, zoom, turntable, and hotspot inspection controls
- hotspots derived from stats, enchantments, and durability
- an accessibility label for screen-reader narration
- a snapshot containing camera, selected hotspot, and asset refs
Items without meshes return status: "icon_only" so UI can fall back to a flat
icon preview without losing the inspection panel.
Controls#
Use immutable helpers to update state:
rotateItemPreviewadjusts orbit yaw and pitch.zoomItemPreviewclamps camera distance to configured bounds.setItemPreviewTurntableenables or disables automatic rotation.selectItemPreviewHotspotselects a stat, enchantment, or durability marker.createItemPreviewSnapshotcaptures the current view for thumbnails or tests.
Renderer implementations should treat the returned state as the source of truth and can map the scene node and camera data to Three.js, WebGPU, native engine, or editor viewport primitives.