@things-factory/figure-ui 10.1.17 → 10.1.19

package/client/modeller/figure-preview.ts

@@ -57,46 +57,17 @@ export const PREVIEW_WAYS: readonly { name: string; axes: readonly ('x' | 'y' |
   { name: 'x·y·z', axes: ['x', 'y', 'z'] }
 ]
 
-/**
- * 이 도형의 상자 **밑면**이 씬의 어느 높이에 오나.
- *
- * 배치 기준이 하는 일이 이것 하나다 — 좌표를 뒤집는 것이 아니라 **높이를 정하는 것.**
- * 바닥 기반은 땅에 서고, 천정 기반은 천장에서 제 키만큼 내려온 자리에 매달리고,
- * 중심 기반은 그 사이에 뜬다. `operato-scene` 의 archetype 이 같은 말을 한다
- * (`archetypes.ts`: ceiling — *zPos derived from ceiling minus depth*).
- */
-function bottomOf(placement: FigureSource['placement'], height: number, ceiling: number): number {
-  switch (placement) {
-    case 'ceiling':
-      return ceiling - height
-    case 'center':
-      return (ceiling - height) / 2
-    case 'floor':
-    default:
-      return 0
-  }
-}
-
-/**
- * 밑면 높이를 씬이 받는 `zPos` 로 옮긴다.
+/*
+ * 높이는 여기서 안 정한다.
  *
- * 씬은 부품 중심을 `zPos + geometricOffsetY` 에 놓고, 그 오프셋이 좌표 기준마다 다르다
- * (`real-object.ts`). 그래서 같은 밑면을 말하는 `zPos` 가 기준마다 다른 수다 — 바닥
- * 기준이면 밑면 그대로, 중심 기준이면 중심, 천장 기준이면 윗면.
+ * 한동안 배치 기준을 높이로 옮기는 계산을 이 파일이 들고 있었다. 이제 씬이 한다 —
+ * `FigureRealObject.effectiveZPos` 가 청사진의 `placement` 와 레이어의 `heights` 로 정한다
+ * (ADR-0045, `operato-twin/design/04-decisions.md`). 보드가 그렇게 세우므로 「보드에 놓았을
+ * 때의 모습」을 말하는 이 화면도 그렇게 세워야 한다 — 여기서 `zPos` 를 적으면 **적은 값이
+ * 이겨서**, 씬이 무엇을 할지가 이 화면에서만 안 보인다.
  *
- * **여기가 유일하게 좌표 기준을 아는 자리다.** 저작한 값에는 이것이 안 들어간다.
+ * 규칙이 두 벌이면 갈린다. 오늘 하루가 그 이야기였다.
  */
-function zPosOf(bottom: number, height: number, reference: ViewSettings['placement']): number {
-  switch (reference) {
-    case 'space':
-      return bottom + height / 2
-    case 'inverted':
-      return bottom + height
-    case 'floor':
-    default:
-      return bottom
-  }
-}
 
 interface SceneHandle {
   dispose?: () => void
@@ -146,11 +117,11 @@ export class FigurePreview extends localize(i18next)(LitElement) {
     }
 
     /*
-      Clip 조작. **저작자가 제 애니메이션을 만져 볼 유일한 자리다.**
+      움직임 조작. **저작자가 제 애니메이션과 파라미터를 만져 볼 유일한 자리다.**
 
-      보드에서는 트윈이 clip 을 몬다 — 「닙이 40% 열렸다」는 사실이 어디선가 온다. 저작
-      중에는 그 사실을 주는 것이 없어서, 손대지 않으면 hold 인 clip 은 0 에 머문 채
-      영영 안 움직인다. 포크가 안 올라가는 것을 저작자가 「안 되는구나」로 읽게 된다.
+      도면에서는 트윈이 이 값을 준다 — 「닙이 40% 닫혔다」는 사실이 어디선가 온다. 저작
+      중에는 그 사실을 주는 것이 없어서, 손대지 않으면 파라미터는 기본값에 머문 채 영영
+      안 움직인다. 포크가 안 올라가는 것을 저작자가 「안 되는구나」로 읽게 된다.
 
       **미리보기 것이지 자산의 것이 아니다.** 여기서 민 값은 저장되지 않는다.
     */
@@ -223,11 +194,14 @@ export class FigurePreview extends localize(i18next)(LitElement) {
   private standing?: string
   private watcher?: ResizeObserver
 
-  /** 지금 민 clip 값. clip 이름 → 수. **저장되지 않는다.** */
+  /** 지금 민 clip 배속. clip 이름 → 수. **저장되지 않는다.** */
   @state() private driving: Record<string, number> = {}
+  /** 지금 민 파라미터 값. 이름 → `range` 의 단위로 잰 수. **저장되지 않는다.** */
+  @state() private giving: Record<string, number> = {}
 
   render() {
     const clips = this.source?.animations ?? []
+    const parameters = this.source?.parameters ?? []
 
     return html`
       <div stage></div>
@@ -236,31 +210,54 @@ export class FigurePreview extends localize(i18next)(LitElement) {
         : html`<div legend>
               ${PREVIEW_WAYS.map(way => html`<span>${way.name}</span>`)}
             </div>
-            ${clips.length > 0 ? this.renderClips(clips) : ''}`}
+            ${clips.length + parameters.length > 0 ? this.renderDrivers(clips, parameters) : ''}`}
     `
   }
 
   /**
-   * Clip 하나에 손잡이 하나.
+   * 움직임 하나에 손잡이 하나.
    *
-   * 수의 뜻이 `drive` 에 따라 다르므로 그것을 이름 옆에 적는다. `loop` 는 배속이라 0 이
-   * 멈춤이고, `hold` 는 0~1 위치라 0 이 처음이다. 둘을 같은 눈금으로 두면 「1」이 무슨
-   * 뜻인지 매번 헷갈린다.
+   * 두 갈래를 **눈금이 다른 채로** 낸다. clip 은 배속이라 0 이 멈춤이고 0~3 이 뜻이
+   * 있으며, 파라미터는 물리량이라 그 `range` 가 곧 눈금이고 단위가 따라 붙는다. 하나의
+   * 0~1 로 뭉뚱그리면 「1」이 무슨 뜻인지 매번 헷갈리고, 1200mm 를 넣어 보려던 저작자가
+   * 넣을 자리를 못 찾는다.
    */
-  private renderClips(clips: NonNullable<FigureSource['animations']>) {
+  private renderDrivers(
+    clips: NonNullable<FigureSource['animations']>,
+    parameters: NonNullable<FigureSource['parameters']>
+  ) {
     return html`
       <div clips>
+        ${parameters.map(parameter => {
+          const range = parameter.range
+          const value = this.giving[parameter.name] ?? parameter.default ?? range?.min ?? 0
+          const step = range ? Math.max((range.max - range.min) / 100, 0.01) : 1
+
+          return html`
+            <label>
+              <span>${parameter.label ?? parameter.name} <span drive>${range?.unit ?? ''}</span></span>
+              <input
+                type="range"
+                min=${range?.min ?? 0}
+                max=${range?.max ?? 1}
+                step=${step}
+                .value=${String(value)}
+                @input=${(e: Event) => this.give(parameter.name, Number((e.target as HTMLInputElement).value))}
+              />
+              <output>${Math.round(value)}</output>
+            </label>
+          `
+        })}
         ${clips.map(clip => {
-          const loop = (clip.drive ?? 'loop') === 'loop'
-          const value = this.driving[clip.name] ?? (loop ? 1 : 0)
+          const value = this.driving[clip.name] ?? 1
 
           return html`
             <label>
-              <span>${clip.name} <span drive>${loop ? '배속' : '위치'}</span></span>
+              <span>${clip.name} <span drive>배속</span></span>
               <input
                 type="range"
                 min="0"
-                max=${loop ? 3 : 1}
+                max="3"
                 step="0.05"
                 .value=${String(value)}
                 @input=${(e: Event) => this.drive(clip.name, Number((e.target as HTMLInputElement).value))}
@@ -281,9 +278,23 @@ export class FigurePreview extends localize(i18next)(LitElement) {
    */
   private drive(name: string, value: number): void {
     this.driving = { ...this.driving, [name]: value }
+    this.tellInstances('clips', this.driving)
+  }
+
+  /**
+   * 파라미터 값을 준다 — **`range` 의 단위 그대로다.**
+   *
+   * 0~1 로 바꿔서 주지 않는다. 그 환산은 런타임의 일이고, 여기서 한 번 더 하면 두 곳이
+   * 갈릴 수 있다. 저작자가 화면에서 보는 1200 이 씬에 그대로 간다.
+   */
+  private give(name: string, value: number): void {
+    this.giving = { ...this.giving, [name]: value }
+    this.tellInstances('parameters', this.giving)
+  }
 
+  private tellInstances(key: 'clips' | 'parameters', values: Record<string, number>): void {
     for (const component of this.scene?.root?.components ?? []) {
-      component.set?.('clips', { ...this.driving })
+      component.set?.(key, { ...values })
     }
   }
 
@@ -293,8 +304,8 @@ export class FigurePreview extends localize(i18next)(LitElement) {
    * 조명·환경·바탕은 씬이 스스로 반응한다(`three-capability` 의 `onchange`). 슬라이더를
    * 끄는 동안 다시 세우면 카메라가 매 프레임 처음으로 돌아간다.
    *
-   * 좌표 기준과 천장 높이는 다르다. 그 둘은 컴포넌트의 `zPos` 를 만들 때 쓰였으므로,
-   * 이미 세워 둔 것에 넣어 봐야 자리가 안 바뀐다. 그것만 다시 세운다.
+   * 좌표 기준과 천장 높이는 다르다. 씬이 그 둘로 인스턴스 높이를 정하는데, 그 계산은 세울
+   * 때 한 번 돈다 — 이미 세워 둔 것에 넣어 봐야 자리가 안 바뀐다. 그것만 다시 세운다.
    */
   willUpdate(changed: Map<string, unknown>) {
     if (!this.hasUpdated) return
@@ -344,7 +355,7 @@ export class FigurePreview extends localize(i18next)(LitElement) {
     }
 
     const view = this.view ?? DEFAULT_VIEW
-    /* 좌표 기준과 천장 높이가 컴포넌트의 `zPos` 를 만든다 — 서명에 안 넣으면 다시 세워도 그대로 선다. */
+    /* 씬이 이 둘로 인스턴스 높이를 정한다 — 서명에 안 넣으면 다시 세워도 그대로 선다. */
     const signature = JSON.stringify([source, view.placement, view.ceilingHeight])
     if (this.scene && this.standing === signature) return
 
@@ -399,7 +410,6 @@ export class FigurePreview extends localize(i18next)(LitElement) {
         const width = Math.round(base.x * grow.x)
         const height = Math.round(base.z * grow.z)
         const tall = Math.round(base.y * grow.y)
-        const bottom = bottomOf(source.placement, tall, view.ceilingHeight)
 
         return {
           type: source.type,
@@ -409,8 +419,7 @@ export class FigurePreview extends localize(i18next)(LitElement) {
           top: Math.round(row * cell.z + (cell.z - height) / 2),
           width,
           height,
-          depth: tall,
-          zPos: Math.round(zPosOf(bottom, tall, view.placement))
+          depth: tall
         }
       })
 
@@ -418,17 +427,15 @@ export class FigurePreview extends localize(i18next)(LitElement) {
         width: Math.round(cell.x * COLUMNS),
         height: Math.round(cell.z * rows),
         /*
-          판의 높이도 가장 큰 인스턴스를 담아야 한다.
+          판의 높이도 가장 큰 인스턴스를 담아야 한다. 안 주면 카메라가 평면만 보고 자리를
+          잡아서, 키가 큰 모델은 밑동만 보인다 — 시그널타워를 2 배로 놓으면 2200 인데 판이
+          그것을 모르면 받침만 화면에 든다.
 
-          안 주면 카메라가 평면만 보고 자리를 잡아서, 키가 큰 모델은 밑동만 보인다.
-          시그널타워를 2 배로 놓으면 2200 인데 판이 그것을 모르면 받침만 화면에 든다.
-
-          가장 높은 **윗면**으로 잡는다. 천정 기반은 천장 높이에 매달리므로 제 키보다
-          훨씬 위에 있다 — 키만 보고 잡으면 천장에 걸린 것이 화면 밖으로 나간다.
+          어디에 올려 놓을지는 **씬이 정하므로**(`FigureRealObject.effectiveZPos`), 여기서는
+          어느 경우에도 담기는 경계만 잡는다. 바닥 기반은 가장 큰 것의 키까지, 천정 기반은
+          천장까지다. 배치를 높이로 옮기는 계산을 여기서 다시 쓰면 그것이 두 벌째가 된다.
         */
-        depth: Math.round(
-          Math.max(...components.map(c => bottomOf(source.placement, c.depth, view.ceilingHeight) + c.depth)) * 1.1
-        )
+        depth: Math.round(Math.max(view.ceilingHeight, base.y * biggest) * 1.1)
       }
 
       this.scene = create({
@@ -447,11 +454,17 @@ export class FigurePreview extends localize(i18next)(LitElement) {
             올려도 편집 캔버스만 밝아지고 이 화면은 그대로여서, 같은 것을 두 화면이
             다르게 보여 주었다.
 
-            `sceneLook` 이 좌표 기준과 천장 높이를 빼고 준다 — 그 둘은 씬에 그대로 넣을
-            값이 아니라 위에서 `zPos` 를 정하는 데 쓴다. 좌표 기준만 여기 따로 싣는다.
+            `sceneLook` 이 좌표 기준과 천장 높이를 빼고 준다 — 씬이 아는 이름이 아니거나
+            (`ceilingHeight`) 편집 캔버스에 새면 안 되는 것(`placement`)이라서다. 둘 다 아래에
+            씬의 낱말로 따로 싣는다.
           */
           ...sceneLook(view),
           placement: view.placement,
+          /*
+            부착면의 높이. 씬이 이 자리를 갖고(`real-object.ts` 의 `sceneHeights`), 천정 기반
+            도형이 여기서 제 높이를 얻는다. 보드에서는 현장이 이 값을 준다.
+          */
+          heights: { floor: 0, ceiling: view.ceilingHeight },
           pixelRatio: Math.min(3, (window.devicePixelRatio || 1) * 2),
           components
         },

package/client/modeller/figure-side.ts

@@ -175,7 +175,7 @@ export class FigureSide extends localize(i18next)(LitElement) {
    * 0 이면 아무것도 안 붙인다 — 「0」을 붙이면 없는 것이 있는 것처럼 자리를 차지한다.
    */
   private get clipCount(): number | undefined {
-    const n = this.draft?.animations?.length ?? 0
+    const n = (this.draft?.animations?.length ?? 0) + (this.draft?.parameters?.length ?? 0)
     return n === 0 ? undefined : n
   }
 

package/client/modeller/figure-source.ts

@@ -102,6 +102,14 @@ export interface FigureDraft {
    * 저장하는 것만으로 **조용히 지워지기** 때문이다.
    */
   animations?: FigureSource['animations']
+  /**
+   * 값이 만드는 자세 — **애니메이션과 다른 칸이다.**
+   *
+   * 저것은 시각이 흘러 움직이는 것(도는 롤러)이고 이것은 인스턴스가 준 값이 그대로 자세가
+   * 되는 것(1200mm 내려온 호이스트)이다. 한동안 애니메이션 안에 `drive: 'hold'` 로 숨어
+   * 있었고, 그래서 「길이값을 변수로 노출하라」는 요청에 아무도 이것을 못 찾았다(ADR-0051).
+   */
+  parameters?: FigureSource['parameters']
   /**
    * 이 도형이 지는 능력. 씬의 capability mixin 이름이다.
    *
@@ -274,6 +282,7 @@ export function toFigureSource(draft: FigureDraft, parts: PartModel[]): FigureSo
     styleKit: draft.styleKit,
     parts: parts.map(part => partTo(part, half)),
     animations: draft.animations,
+    parameters: draft.parameters,
     capabilities: draft.capabilities
   }) as FigureSource
 }
@@ -341,6 +350,7 @@ export function fromFigureSource(source: FigureSource): { draft: FigureDraft; pa
     detailLevel: source.detailLevel,
     styleKit: source.styleKit,
     animations: source.animations,
+    parameters: source.parameters,
     capabilities: source.capabilities
   }) as FigureDraft
 

package/client/modeller/proposal.ts

@@ -30,6 +30,7 @@ export type ChangeKind =
   | 'detail'
   | 'styleKit'
   | 'animations'
+  | 'parameters'
   | 'capabilities'
 
 /**
@@ -48,13 +49,14 @@ export type ChangeKind =
  * 식별자라 후보가 바꿔 와도 받지 않고(`applyProposal` 참고), `version` 은 저작자가 고를 것이
  * 아니라 저장할 때 서버가 찍는다.
  */
-const FIGURE_FIELDS = ['base', 'placement', 'detailLevel', 'styleKit', 'animations', 'capabilities'] as const
+const FIGURE_FIELDS = ['base', 'placement', 'detailLevel', 'styleKit', 'animations', 'parameters', 'capabilities'] as const
 const FIELD_KIND: Record<(typeof FIGURE_FIELDS)[number], ChangeKind> = {
   base: 'base',
   placement: 'placement',
   detailLevel: 'detail',
   styleKit: 'styleKit',
   animations: 'animations',
+  parameters: 'parameters',
   capabilities: 'capabilities'
 }
 

package/client/pages/figure-modeller-page.ts

@@ -1184,6 +1184,7 @@ export class FigureModellerPage extends FigureModellerPageBase {
       detail: 'tune',
       styleKit: 'palette',
       animations: 'animation',
+      parameters: 'tune',
       capabilities: 'hub'
     } satisfies Record<proposals.ChangeKind, string>)[change.kind]
 

package/dist-client/modeller/figure-animations.d.ts

@@ -5,10 +5,18 @@ export declare class FigureAnimations extends FigureAnimations_base {
     static styles: import("lit").CSSResult[];
     draft?: FigureDraft;
     parts: PartModel[];
-    /** 펼쳐 둔 clip. 이름이 아니라 자리로 잡는다 — 이름은 편집 중에 바뀐다. */
+    /**
+     * 펼쳐 둔 것. 이름이 아니라 **목록과 자리**로 잡는다 — 이름은 편집 중에 바뀐다.
+     *
+     * 목록이 둘이므로 자리 하나로는 모자란다. `clip:0` 과 `parameter:0` 은 다른 것이다.
+     */
     private open;
     private recipeTarget;
     private get clips();
+    private get parameters();
+    /** 두 목록의 이름을 한자리에서 본다 — 인스턴스가 이름 하나로 값을 준다. */
+    private get allNames();
+    private channelsOf;
     /** 부품 이름 — 채널이 이것을 가리킨다. */
     private get partNames();
     /**
@@ -26,8 +34,17 @@ export declare class FigureAnimations extends FigureAnimations_base {
      * 그래서 무엇을 만들 수 있는지 예를 들고, 그것이 어떻게 움직이는지(사실이 들어온다)를 적는다.
      */
     private renderRecipes;
-    private renderClips;
+    /** 이름이 다른 것과 겹치나. 두 목록을 함께 본다 — 인스턴스는 이름 하나로 값을 준다. */
+    private taken;
     private renderClip;
+    /**
+     * 파라미터 하나 — **이름·범위·자세.**
+     *
+     * 범위가 화면에 있어야 하는 이유는 그것이 **인스턴스와 주고받는 말**이기 때문이다.
+     * 곡선은 0~1 이고 인스턴스는 mm 로 준다. 그 사이를 런타임이 맵하는데, 무엇부터 무엇
+     * 까지인지 저작자가 정하지 않으면 값을 줄 수가 없다.
+     */
+    private renderParameter;
     private renderChannels;
     /**
      * 채널 하나 — 어느 부품의 어느 속성을 움직이나.
@@ -69,13 +86,25 @@ export declare class FigureAnimations extends FigureAnimations_base {
      */
     private tell;
     private patchClip;
+    private patchParameter;
+    /** 채널 묶음을 통째로 얹는다. **어느 목록이든 같은 자리에 닿는다.** */
+    private setChannels;
     private patchChannel;
     private addClip;
-    /** Recipe creates a valid, editable two-pose clip; it never saves or publishes the Figure. */
+    private addParameter;
+    /**
+     * Recipe creates a valid, editable two-pose motion; it never saves or publishes the Figure.
+     *
+     * 어느 목록으로 가는지는 레시피가 안다 — 도는 롤러는 애니메이션이고 열리는 문은
+     * 파라미터다. 저작자에게 그 갈래를 먼저 고르게 하지 않는 이유가 이것이다.
+     */
     private addRecipe;
     private renameClip;
-    private setDrive;
+    private renameParameter;
+    private setRange;
+    private setDefault;
     private removeClip;
+    private removeParameter;
     private addChannel;
     private setChannel;
     /**