API reference
Commonly used public APIs. For details, see each function's JSDoc and the guides.
@isora/core
Scenes and assets
| API | Meaning |
|---|---|
createScene(options) | An empty scene (id, name, width, depth, snap, unit). Without name, meta.name is 'Untitled scene' |
parseScene(json) / validateScene(scene) | Validation. parseScene throws SceneValidationError if invalid |
defineAsset(def) / box(part) | Define and validate an asset / a part box |
createRegistry(packs) | Asset id → asset |
createSceneBuilder(scene, registry, { packs? }) | Build scenes in code. With packs, the packs used are written to scene.assetPacks |
↳ add(asset, x, y, rotation?, extra?) · on(baseId, asset, dx, dy, …) | Place · place next to or on top of something already placed (a monitor on a desk) |
↳ sit(asset, furnitureId, index?, extra?) · row(asset, count, { at, step, rotation?, extra? }) | Seat someone · place in a row (returns the placed ids) |
↳ floor(asset, x0, y0, x1, y1, color?, rotation?) | Lay floor tiles. Where color is null the tile is left empty (for a different floor tile) |
↳ room(x0, y0, x1, y1, { wall?, corner?, window?, windowEvery?, doors?, thickness?, color?, skip? }) | Wall in the outside of a rectangle and place doors, windows and corner posts → { walls, doors, corners } |
lintScene(scene, registry, { skip?, tolerance?, locale? }) · formatIssues(issues) | Layout checks: overlaps, floating, outside the grid, unusable seats, trapped people, activities without spots · as human-readable lines |
lintMotion(scene, registry, { samples?, tolerance?, people?, seconds?, seed?, locale? }) · formatMotionIssues(issues) | Checks while things move: cargo floating along, buried cargo, cargo passing through equipment, loads coming off, parts going through the floor, parts detaching from where they hang, people passing through or overlapping furniture |
collectAssetPacks(objects, packs) · nextObjectId(scene, assetId) | Packs used by objects → assetPacks value · a new object id (desk-3) |
Coordinates and placement
| API | Meaning |
|---|---|
iso(x, y, z, unit) | Projection |
projectPoint(point, scene, rotation) | Scene coordinates → SVG coordinates |
unprojectPoint(screen, scene, rotation, z) | SVG coordinates → scene coordinates on the plane at height z |
floorPointAt(scene, registry, screen, rotation) | SVG coordinates → the floor below (top of floor tiles and rugs) |
rotatePoint · unrotatePoint · rotateBox · rotatedSize · rotateVector | Rotation in 90° steps |
placeAt(scene, registry, assetId, center, rotation) | The position to place at a center (with snapping and stacking) |
placeCorner(…, corner, …) | Placement by corner |
surfaceHeightAt(scene, registry, area) | The highest top surface holding up that area |
objectFootprint(obj, asset) · objectPartBoxes(obj, asset) | Footprint box · world boxes of the parts |
findCollisions(scene, registry) · collidesWithScene(…) | Overlaps |
Spots and sitting
| API | Meaning |
|---|---|
SITTING · SIT_POSE | Sitting template (0.5×0.75, back 0.1, knees 0.46, hips 0.49) · 'sit' |
LYING · LIE_POSE | Lying template (0.5×1.4, head end y 0, back z 0) · 'lie' |
seatedPatch(furniture, asset, index) | position, rotation, pose and seat of a person seated (or lying) at that spot |
seatPose(seat) · canTakePose(person, pose) | The pose a seat uses · whether that person asset can take the pose |
findActivitySpots(scene, registry, grid?, { sitters? }) | The scene's activity spots, standing places (approach) and seated shapes |
standUpCorners(sitter) | The four standing places beside a seat (front, left, right, back) |
sitPathClear(seated, standing, sitters, obstacles) · seatObstacles(scene, registry) | Whether the sitting path stays clear of furniture · obstacle boxes |
findSeatOnScreen(scene, registry, point, { sitter }) | A free seat near a screen point (skips seats whose pose sitter cannot take) |
describeRig(asset, { locale? }) | Whether a person asset follows the motion conventions |
AssetDef.hollow | A hollow asset (booth, tent, guard post, L-shaped desk). Pathfinding blocks only where parts stand, so spots inside can be used |
Behavior
| API | Meaning |
|---|---|
createBehaviorWorld(scene, registry, { seed, speed, control }) | Behavior planning. frameAt(t), command(id, commands, at), people, spots, time, version |
ActorCommand | go · do · idle · leave · routine, fallback command orElse, standing activity activity (Moving people) |
BehaviorFrame | overrides, states, people, hidden, transitions, strides |
behaviorActors(objects, frame, people) | Frame → the moving people to pass to composeRender |
DEFAULT_ROUTINES · MANUAL_ROUTINE · ACTIVITIES · sceneRoutines(scene) | Built-in routines · command-only routine id · activity definitions · scene routines + built-in routines |
clockMinutes(clock, t) · formatClock(min) · parseClock('09:00') | Time of day |
buildNavGrid · canStand · findPath | Pathfinding grid · whether a place is standable · A* |
WALK_SPEED · POSE_SECONDS · PERSON_SIZE · NAV_STEP | 1.6 tiles/s · 0.45 s · 0.5 · 0.25 |
Motion and drawing
| API | Meaning |
|---|---|
actorPartBoxes(obj, asset, { transition?, gait? }) | World boxes of the parts, with pose transition and gait applied |
transitionClear(seated, asset, from, obstacles) | Sitting-path check for one person |
GAIT · gaitLimb(partId) · poseCorrespondence(asset, pose) | Gait values · which limb swings · part pairs when sitting |
prepareRender(scene, registry, options) | Static picture + front/back edges. dynamic lists ids to leave out |
composeRender(prepared, actors) | This frame's picture with moving things slotted in (parts, hulls, bounds) |
buildRenderList(scene, registry, options) | Draw in one go (= prepareRender(…).result) |
sceneBounds · groundGeometry | Screen bounds · floor plate and grid lines |
depthSort(items) · isBehind(a, b) | Depth sorting |
Timelines
| API | Meaning |
|---|---|
evaluateTimelines(scene, registry, t) | Cargo and loads (temporary objects) and part changes at that time (objects, changes) |
SpawnTrack.face | 'axis' (default: lay the long side along the axis of travel) · 'direction' (front points where it goes — vehicles drawn with +y as front) |
samplePath · pathLength · interpolateKeys | Paths and keyframes |
isTransientId(id) · TRANSIENT_PREFIX | Whether an object is a temporary one made by a timeline (excluded from selection and moves) |
Languages (i18n)
Text from the library is English by default. Korean is built in, and you can add any other language to your own data.
- Data keeps the English text in its original field and translations next to it, keyed by locale:
AssetDef.names,AssetState.labels,AssetPack.names,Routine.names,ActivityDef.labels. - Official assets, packs, routines and activities are English (
Desk,Office worker) with Korean innames.ko/labels.ko. - Helpers return the translation for the locale, or fall back to the English text. Unknown locales fall back to English; a regional locale such as
'ko-KR'also finds'ko'.
ts
{ id: 'isora/office/desk', name: 'Desk', names: { ko: '책상' } } // an asset with a Korean name| API | Meaning |
|---|---|
Locale · DEFAULT_LOCALE | A locale string ('en' default, 'ko' built in) · 'en' |
Translations | Readonly<Record<string, string>> — locale → text |
localize(text, translations, locale?) | Pick the text for a locale, or text |
assetName(asset, locale?) · packName(pack, locale?) | Asset name · pack name |
stateLabel(asset, stateName, locale?) | Display name of an asset state (the state name if the asset has no such state) |
activityLabel(activity, locale?) · routineName(routine, locale?) | Activity name ('work' → 'Work' / '일하기') · routine name |
{ locale } option | lintScene, lintMotion and describeRig return messages in that language |
ts
import { assetName, formatIssues, lintScene } from '@isora/core'
const desk = registry.get('isora/office/desk')!
assetName(desk) // 'Desk'
assetName(desk, 'ko') // '책상'
assetName(desk, 'ja') // 'Desk' (no Japanese name → English)
console.log(formatIssues(lintScene(scene, registry, { locale: 'ko' }))) // Korean messages@isora/react
| API | Meaning |
|---|---|
<IsoScene> | The viewer. Props are in Rendering |
useBehaviorPlayback(scene, registry, { enabled, playing, speed, clock, seed, control, walkSpeed }) | time, people, overrides, states, hidden, ids, live, world, clock, command() |
useActorCommands(behavior, { [id]: command }) | Declare what each person should do; commands go only to people whose value changed |
useTimelinePlayback(scene, registry, { enabled, timelines, playing, speed, clock }) | time, playing, live (cargo and keyframes drawn every frame), reducedMotion |
useObjectMotion(scene, registry, { enabled, speed, ignore }) | A live source that bridges scene data changes with walking and sitting |
createTimelineClock({ tickMs, time, speed }) | play, pause, seek, setSpeed, getState, subscribe, timeAt |
useTimelineClock(clock) | { time, playing, speed } every tick |
LiveSceneLayer · LiveSource | Per-frame drawing layer · motion source |
SceneLayer · GroundGrid · HullOutline · IsoStyles · ISORA_CSS | Low-level drawing |
ActivityBubbles · ACTIVITY_ICONS · hullTop(hull) | Activity bubbles · icons · top of a silhouette |
AssetThumbnail · ScreenContent | Asset preview (locale picks the language of its accessible name) · device screens |
usePrefersReducedMotion() · canWalk(asset) | Reduced motion · whether a person asset can walk |
@isora/assets
| export | Meaning |
|---|---|
officialPacks | All 10 official packs · 190 assets (common · office · factory · city · medical · military · school · retail · transit · people) |
@isora/assets/common | Floors, walls, doors, partitions, outdoor props (sidewalks, crosswalks, barriers, CCTV, planters, notice boards, lockers …) |
@isora/assets/office | Desks, L-shaped desks, chairs, stools, sofas, meeting tables, focus booths, reception, printers, server racks … |
@isora/assets/factory | Conveyors, rollers, inspection gates, robot arms, machining centers, presses, pallet racks, loading dock doors, AGVs, forklifts … |
@isora/assets/city | Buildings, shops, street furniture (traffic lights, smart poles, bus stops, EV chargers, solar panels), vehicles |
@isora/assets/medical | Hospital beds, exam beds, CT, nurse stations, IV stands, patient monitors, waiting chairs … |
@isora/assets/military | Guard posts, watchtowers, barbed wire, tents, cots, barracks, helipads, radar, military vehicles … |
@isora/assets/school | Student desks and chairs, blackboards, lecterns, serving counters, tracks, soccer and basketball goals, slides, swings |
@isora/assets/retail | Shelves, checkout counters, shopping carts, refrigerated cases, freezers, produce stands, bakery cases, anti-theft gates |
@isora/assets/transit | Check-in counters, security screening, baggage conveyors, gate seating, information boards, airliners, jet bridges, tugs |
@isora/assets/people | 23 people (office worker, developer, nurse, doctor, patient, soldier, officer, student, teacher, traveler, flight attendant …) |