API 한눈에
자주 쓰는 공개 API. 자세한 뜻은 각 함수의 JSDoc 과 가이드 문서에 있다.
@isora/core
씬·에셋
| API | 뜻 |
|---|---|
createScene(options) | 빈 씬 (id·name·width·depth·snap·unit). name 이 없으면 meta.name 은 'Untitled scene' |
parseScene(json) / validateScene(scene) | 검증. parseScene 은 틀리면 SceneValidationError 를 던진다 |
defineAsset(def) / box(part) | 에셋 정의와 검증 / 파츠 상자 |
createRegistry(packs) | 에셋 id → 에셋 |
createSceneBuilder(scene, registry, { packs? }) | 코드로 씬 쌓기. packs 를 주면 쓴 팩이 scene.assetPacks 에 적힌다 |
↳ add(asset, x, y, rotation?, extra?) · on(baseId, asset, dx, dy, …) | 놓기 · 이미 놓은 것 옆·위에 놓기 (책상 위 모니터) |
↳ sit(asset, furnitureId, index?, extra?) · row(asset, count, { at, step, rotation?, extra? }) | 자리에 앉히기 · 줄 세우기 (놓은 id 배열) |
↳ floor(asset, x0, y0, x1, y1, color?, rotation?) | 바닥 깔기. color 가 null 이면 그 칸은 비운다 (다른 바닥재 자리) |
↳ room(x0, y0, x1, y1, { wall?, corner?, window?, windowEvery?, doors?, thickness?, color?, skip? }) | 사각형 바깥을 벽으로 두르고 문·창문·모서리 기둥을 놓는다 → { walls, doors, corners } |
lintScene(scene, registry, { skip?, tolerance?, locale? }) · formatIssues(issues) | 배치 검사: 겹침·떠 있음·그리드 밖·못 앉는 자리·갇힌 사람·자리 없는 활동 · 사람이 읽을 줄로 |
lintMotion(scene, registry, { samples?, tolerance?, people?, seconds?, seed?, locale? }) · formatMotionIssues(issues) | 움직이는 동안 검사: 떠서 가는 화물·파묻힌 화물·설비를 뚫는 화물·실린 짐 이탈·바닥을 뚫는 파츠·매단 곳에서 떨어진 파츠·가구를 뚫거나 겹치는 사람 |
collectAssetPacks(objects, packs) · nextObjectId(scene, assetId) | 오브젝트가 쓰는 팩 → assetPacks 값 · 새 오브젝트 id (desk-3) |
좌표·배치
| API | 뜻 |
|---|---|
iso(x, y, z, unit) | 투영 |
projectPoint(point, scene, rotation) | 씬 좌표 → SVG 좌표 |
unprojectPoint(screen, scene, rotation, z) | SVG 좌표 → 높이 z 평면의 씬 좌표 |
floorPointAt(scene, registry, screen, rotation) | SVG 좌표 → 그 아래 바닥(바닥재·러그 윗면) |
rotatePoint·unrotatePoint·rotateBox·rotatedSize·rotateVector | 90° 단위 회전 |
placeAt(scene, registry, assetId, center, rotation) | 가운데 기준으로 놓을 position (스냅·쌓기) |
placeCorner(…, corner, …) | 모서리 기준 |
surfaceHeightAt(scene, registry, area) | 그 자리를 받치는 가장 높은 윗면 |
objectFootprint(obj, asset) · objectPartBoxes(obj, asset) | 발자국 상자 · 파츠 월드 상자 |
findCollisions(scene, registry) · collidesWithScene(…) | 겹침 |
자리·앉기
| API | 뜻 |
|---|---|
SITTING · SIT_POSE | 앉은 자세 틀 (0.5×0.75, 등 0.1, 무릎 0.46, 엉덩이 0.49) · 'sit' |
LYING · LIE_POSE | 누운 자세 틀 (0.5×1.4, 머리맡 y 0, 등 z 0) · 'lie' |
seatedPatch(furniture, asset, index) | 그 자리에 앉히거나 눕힌 사람의 position·rotation·pose·seat |
seatPose(seat) · canTakePose(person, pose) | 자리가 쓰는 자세 · 그 사람 에셋이 그 자세를 할 수 있는지 |
findActivitySpots(scene, registry, grid?, { sitters? }) | 씬의 활동 자리와 설 곳(approach)·앉은 모습 |
standUpCorners(sitter) | 앉은 자리 옆의 설 곳 넷 (앞·왼·오·뒤) |
sitPathClear(seated, standing, sitters, obstacles) · seatObstacles(scene, registry) | 앉는 길이 가구를 뚫지 않는지 · 장애물 상자 |
findSeatOnScreen(scene, registry, point, { sitter }) | 화면 좌표 근처의 빈자리 (sitter 가 못 하는 자세의 자리는 건너뜀) |
describeRig(asset, { locale? }) | 사람 에셋이 움직임 약속을 따르는지 |
AssetDef.hollow | 속이 빈 에셋(부스·천막·초소·L 자 책상). 길 찾기가 파츠 자리만 막아 안쪽 자리를 쓸 수 있다 |
행동
| API | 뜻 |
|---|---|
createBehaviorWorld(scene, registry, { seed, speed, control }) | 행동 계획. frameAt(t)·command(id, commands, at)·people·spots·time·version |
ActorCommand | go · do · idle · leave · routine, 대신 할 명령 orElse, 서서 하는 일 activity (사람 움직이기) |
BehaviorFrame | overrides·states·people·hidden·transitions·strides |
behaviorActors(objects, frame, people) | 프레임 → composeRender 에 넘길 움직이는 사람 |
DEFAULT_ROUTINES · MANUAL_ROUTINE · ACTIVITIES · sceneRoutines(scene) | 기본 루틴 · 명령 전용 루틴 id · 활동 정의 · 씬 루틴 + 기본 루틴 |
clockMinutes(clock, t) · formatClock(min) · parseClock('09:00') | 하루 시각 |
buildNavGrid · canStand · findPath | 길 찾기 격자·설 수 있는지·A* |
WALK_SPEED · POSE_SECONDS · PERSON_SIZE · NAV_STEP | 1.6칸/초 · 0.45초 · 0.5 · 0.25 |
움직임·그리기
| API | 뜻 |
|---|---|
actorPartBoxes(obj, asset, { transition?, gait? }) | 자세 전환·걸음이 들어간 파츠 월드 상자 |
transitionClear(seated, asset, from, obstacles) | 한 사람의 앉는 길 검사 |
GAIT · gaitLimb(partId) · poseCorrespondence(asset, pose) | 걸음새 값 · 흔드는 팔다리 · 앉을 때 파츠 짝 |
prepareRender(scene, registry, options) | 정지 그림 + 앞뒤 간선. dynamic 으로 뺄 id |
composeRender(prepared, actors) | 움직이는 것을 끼워 넣은 이번 프레임 그림 (parts·hulls·bounds) |
buildRenderList(scene, registry, options) | 한 번에 그리기 (= prepareRender(…).result) |
sceneBounds · groundGeometry | 화면 범위 · 바닥판·격자선 |
depthSort(items) · isBehind(a, b) | 깊이 정렬 |
타임라인
| API | 뜻 |
|---|---|
evaluateTimelines(scene, registry, t) | 그 시각의 화물·실린 짐(임시 오브젝트)과 파츠 변화 (objects·changes) |
SpawnTrack.face | 'axis'(기본, 긴 쪽을 가는 축에 눕힘) · 'direction'(가는 쪽을 앞으로 — +y 를 앞으로 그린 차량) |
samplePath · pathLength · interpolateKeys | 경로·키프레임 |
isTransientId(id) · TRANSIENT_PREFIX | 타임라인이 만든 임시 오브젝트인지 (선택·이동에서 뺀다) |
언어 (i18n)
라이브러리가 내는 글은 기본이 영어다. 한국어는 내장되어 있고, 내 데이터에는 어떤 언어든 더할 수 있다.
- 데이터는 원래 필드에 영어 글을 두고, 그 옆에 언어별 번역을 둔다:
AssetDef.names·AssetState.labels·AssetPack.names·Routine.names·ActivityDef.labels. - 공식 에셋·팩·루틴·활동은 영어 이름(
Desk·Office worker)이고 한국어는names.ko·labels.ko에 있다. - 도우미 함수는 그 언어의 번역을 돌려주고, 없으면 영어 글이다. 모르는 언어도 영어로 돌아간다.
'ko-KR'처럼 지역이 붙은 언어는'ko'로도 찾는다.
ts
{ id: 'isora/office/desk', name: 'Desk', names: { ko: '책상' } } // 한국어 이름이 있는 에셋| API | 뜻 |
|---|---|
Locale · DEFAULT_LOCALE | 언어 문자열 ('en' 기본, 'ko' 내장) · 'en' |
Translations | Readonly<Record<string, string>> — 언어 → 글 |
localize(text, translations, locale?) | 그 언어의 글, 없으면 text |
assetName(asset, locale?) · packName(pack, locale?) | 에셋 이름 · 팩 이름 |
stateLabel(asset, stateName, locale?) | 에셋 상태의 이름 (없는 상태면 상태 이름 그대로) |
activityLabel(activity, locale?) · routineName(routine, locale?) | 활동 이름 ('work' → 'Work' / '일하기') · 루틴 이름 |
{ locale } 옵션 | lintScene·lintMotion·describeRig 가 그 언어로 메시지를 낸다 |
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' (일본어 이름이 없으면 영어)
console.log(formatIssues(lintScene(scene, registry, { locale: 'ko' }))) // 한국어 메시지@isora/react
| API | 뜻 |
|---|---|
<IsoScene> | 뷰어. props 는 그리기 |
useBehaviorPlayback(scene, registry, { enabled, playing, speed, clock, seed, control, walkSpeed }) | time·people·overrides·states·hidden·ids·live·world·clock·command() |
useActorCommands(behavior, { [id]: command }) | 사람마다 할 일을 선언하면 바뀐 사람에게만 명령을 보낸다 |
useTimelinePlayback(scene, registry, { enabled, timelines, playing, speed, clock }) | time·playing·live(매 프레임 그릴 화물·키프레임)·reducedMotion |
useObjectMotion(scene, registry, { enabled, speed, ignore }) | 씬 데이터 변화를 걷기·앉기로 잇는 live |
createTimelineClock({ tickMs, time, speed }) | play·pause·seek·setSpeed·getState·subscribe·timeAt |
useTimelineClock(clock) | 틱마다 { time, playing, speed } |
LiveSceneLayer · LiveSource | 매 프레임 그리기 레이어 · 움직임 source |
SceneLayer · GroundGrid · HullOutline · IsoStyles · ISORA_CSS | 저수준 그리기 |
ActivityBubbles · ACTIVITY_ICONS · hullTop(hull) | 활동 말풍선 · 아이콘 · 실루엣 맨 위 |
AssetThumbnail · ScreenContent | 에셋 미리보기 (locale 로 접근성 이름의 언어를 고른다) · 전자제품 화면 |
usePrefersReducedMotion() · canWalk(asset) | 동작 줄이기 · 걷는 사람 에셋인지 |
@isora/assets
| export | 뜻 |
|---|---|
officialPacks | 공식 팩 전부 10개 · 에셋 190개 (common · office · factory · city · medical · military · school · retail · transit · people) |
@isora/assets/common | 바닥·벽·문·파티션·야외 소품 (보도·횡단보도·차단기·CCTV·화단·게시판·사물함 …) |
@isora/assets/office | 책상·L 자 책상·의자·스툴·소파·회의 테이블·집중 부스·리셉션·복합기·서버 랙 … |
@isora/assets/factory | 컨베이어·롤러·검사 게이트·로봇 팔·가공기·프레스·파렛트 랙·하역 도어·AGV·지게차 … |
@isora/assets/city | 건물·상가·도로 시설(신호등·스마트 폴·버스 정류장·충전기·태양광)·차량 |
@isora/assets/medical | 병상·진료 베드·CT·간호 스테이션·수액 거치대·환자 모니터·대기 의자 … |
@isora/assets/military | 초소·감시탑·철조망·천막·야전 침대·생활관·헬기장·레이더·군용 차량 … |
@isora/assets/school | 학생 책상·의자·칠판·교탁·배식대·트랙·축구/농구 골대·미끄럼틀·그네 |
@isora/assets/retail | 진열대·계산대·쇼핑 카트·냉장 진열장·냉동고·청과 매대·베이커리 쇼케이스·도난 방지 게이트 |
@isora/assets/transit | 체크인 카운터·보안 검색대·수하물 컨베이어·게이트 좌석·안내판·여객기·탑승교·견인차 |
@isora/assets/people | 사람 23종 (회사원·개발자·간호사·의사·환자·병사·장교·학생·교사·여행객·승무원 …) |