@operato/scene-storage 10.0.0-beta.40 → 10.0.0-beta.42

package/dist/crane.d.ts

@@ -16,13 +16,6 @@ export type CraneStatus = 'idle' | 'moving' | 'loading' | 'unloading' | 'error';
 /** Crane 컴포넌트 state */
 export interface CraneState extends State {
     status?: CraneStatus;
-    /**
-     * Crane 이 서비스 할 타깃 컴포넌트의 refid (또는 id).
-     * 명시되면 그 컴포넌트 (또는 그 children) 의 위치를 stop point 로 사용 — heuristic
-     * 으로 sibling 추정 안 함. 미명시면 sibling 안에서 추측.
-     * 예: RackGrid 의 refid 를 지정하면 그 안의 cell 들 사이에서만 이동.
-     */
-    target?: string;
     /** 마스트 따라 carriage 의 수직 위치 (mm). */
     carriageHeight?: number;
     /**
@@ -41,10 +34,37 @@ export interface CraneState extends State {
      */
     forkExtension?: number;
     /**
-     * Fork 의 *carrier 들어올림 높이* (mm). 0 = neutral (cell shelf 와 같은 면),
-     * +값 = carrier 를 *위로* 들어올림 (fork pocket 안으로 진입 후 위로 lifting).
+     * Fork 가 carrier 를 *cell shelf 에서 분리하기 위해 들어올리는 높이* (mm).
+     * 사용자가 board 에서 설정하는 *configured 진폭*. engage 의 lift 단계 target.
+     * 미명시 시 default 30mm.
+     *
+     * Note: 시뮬 *진행 중 current 들림 값* 은 별도 internal transient — `forkLiftRT`
+     * state. 3D / 2D render 가 carriage Y 결정 시 그 값을 사용.
      */
     forkLift?: number;
+    /**
+     * Fork lift *runtime current value* (mm). engage 가 시뮬 진행 중 매 frame
+     * setState 로 lerp. *사용자가 설정하는 값 아님* — internal transient.
+     */
+    forkLiftRT?: number;
+    /**
+     * 자동 random simulate (visual smoke test) 시작 여부.
+     * - `undefined` 또는 `false` (default): 자동 시작 안 함. application 이 crane.
+     *   pickAndPlace 등 직접 제어 시 사용.
+     * - `true`: added() 시 자동 시작.
+     */
+    simulate?: boolean;
+    /**
+     * Carriage 의 rail-local X 위치 (0 ~ crane.width). Crane.moveTo / simulate 가
+     * lerp. crane 본체 (rail) 는 안 움직임 — carriage assembly (masts + carriage +
+     * forks) 만 rail 안 X 만 슬라이드.
+     */
+    carriagePosition?: number;
+    /**
+     * Carriage 의 폭 (rail-local X 방향). 미명시 시 rail (crane.width) 의 ~10%.
+     * Target rack 의 cell 폭과 매칭 권유.
+     */
+    carriageWidth?: number;
     material3d?: Material3D;
 }
 declare const Crane_base: any;
@@ -88,8 +108,46 @@ export default class Crane extends Crane_base {
     get toolType(): string;
     get nature(): ComponentNature;
     get anchors(): never[];
-    /** Stacker crane carries at most one load at a time on its forks. */
+    /**
+     * Stacker crane carries at most one load at a time on its forks.
+     *
+     * localPosition.z = 0 명시 — ContainerCapacity.receive 의 atomic setState 가
+     * `carrier.state.zPos = slot.localPosition.z + parentGeoOffset = 0` 강제.
+     * 미명시 시 zPos update skip → carrier 의 *이전 holder 또는 board model 의
+     * 임의 zPos (음수 가능)* 그대로 → _realObject 미빌드 시점 (transient placement
+     * 미설정 = state-driven) 에 carrier 가 *지하* 로 가는 결함.
+     */
     get slots(): SlotDef[];
+    /**
+     * Acceptance rotation — carrier 가 crane.fork 에 attach 시 *crane 의 local
+     * axis (전방)* 으로 정렬. identity quaternion 반환 → atomic setState 가
+     * carrier.state.rotation/X/Y = 0 강제. _realObject 미빌드 시점 (transient
+     * placement 미설정 = state-driven) fallback 에서도 자세 정렬.
+     *
+     * follow-holder carryPolicy 와 짝 — 두 path 모두 동일 결과 (local identity).
+     */
+    acceptanceRotation(_carrier: Component, _slot?: SlotDef): {
+        x: number;
+        y: number;
+        z: number;
+        w: number;
+    };
+    /**
+     * Arrangement — carrier.state.left/top 의 *기준* 이 *crane 전체 footprint* 가
+     * 아닌 *carriage X (carriagePosition) + fork Z (bladeMidZ)*. carriage / fork
+     * 의 위치가 carrier 의 위치.
+     *
+     *   left = carriagePosition − carrier.w/2     (carriage X 중심)
+     *   top  = crane.h/2 + bladeMidZ − carrier.h/2   (fork Z 중심)
+     */
+    get arrangementStrategy(): {
+        positionAt(_idx: number, _slot: any, _occ: number, component?: any): {
+            x: number;
+            y: number;
+            z: number;
+        };
+        capacity(slot: any): any;
+    };
     /**
      * Return the 3D attach frame on the crane's carriage (fork tip).
      * Carriers are attached here while the crane is in transit (pick phase).
@@ -118,6 +176,17 @@ export default class Crane extends Crane_base {
      * binding sets 'moving' in monitoring mode; override pick()/place() to
      * set it in full simulation environments.
      */
+    /**
+     * Crane.moveTo — **Crane 본체 (rail) 은 안 움직임**. *내부 carriage 의 rail-
+     * local X 위치 (carriagePosition) 만 lerp*. 실제 gantry / AS/RS crane 의
+     * 자연스러운 운동 패턴.
+     *
+     * target.center 의 world 좌표를 *crane 의 local frame (rail-aligned)* 로
+     * 변환 → rail-local X 추출 → carriagePosition setState.
+     *
+     * Crane.state.rotation = rail 방향. carriage 가 rail 위 X 만 이동.
+     */
+    moveTo(target: Component, options?: MoveOptions): Promise<void>;
     engage(target: Component, kind: 'pick' | 'place', _options?: MoveOptions): Promise<void>;
     /** Fetch a carrier from a rack cell (semantically = pick). */
     fetch(carrier: Component, options?: MoveOptions): Promise<void>;
@@ -141,6 +210,20 @@ export default class Crane extends Crane_base {
      */
     render(ctx: CanvasRenderingContext2D): void;
     added(parent: any): void;
+    /**
+     * Actuator state 의 *canonical default*. state 미설정 시 모든 read 경로
+     * (build / _tween / 외부) 가 *동일 값* 보도록.
+     *
+     * single source 패턴 — visual fallback 과 state fallback 이 *분리* 되어
+     * 첫 _tween 시 start 가 visual current 와 어긋나는 jump 결함을 근본 차단.
+     */
+    _canonicalDefault(key: string): number;
+    private _startAutoSimulate;
+    /**
+     * state.simulate 변경 시 자동 simulate 시작/중단. application 이 런타임 toggle
+     * 가능 (예: editor 에서 simulate off, view 에서 on).
+     */
+    onchange(after: Record<string, unknown>, before: Record<string, unknown>): void;
     buildRealObject(): RealObject | undefined;
     private _simStarted;
     private _simRunning;
@@ -168,8 +251,9 @@ export default class Crane extends Crane_base {
     dispose(): void;
     private _oneCycle;
     /**
-     * things-scene 의 `component.animate()` 로 한 구간 tween. step 콜백에서 setState 호출.
-     * frameClock.simTime 기반이라 scene pause / speed change / suppressAnimations 모두 자동 대응.
+     * frameClock 기반 tween — things-scene 의 표준 `Component.animate()` 사용.
+     * frameClock.simTime 진행 (view mode + scene 활성) 시에만 step 호출 → modeler
+     * 또는 paused 시 자동 정지. scene.simulationSpeed 도 자동 대응.
      */
     private _tween;
 }