@hatiolab/figure-model 0.1.17 → 0.1.19

package/docs/format.md

@@ -4,7 +4,7 @@
 
 ```
 FigureSource      저작 결과. 편집 가능한 정본. DB 에 저장된다.
-FigureBlueprint   보드가 세우는 형태. 정본에서 파생되는 캐시. 저장하지 않는다.
+FigureBlueprint   씬이 세우는 형태. 정본에서 파생되는 캐시. 저장하지 않는다.
 ```
 
 값의 기준이 되는 원본은 `src/types.ts` 다. 이 문서와 코드가 어긋나면 `src/docs.test.ts` 가 실패한다.
@@ -31,7 +31,7 @@ transform.rotation   { x, y, z }   축별 회전(도, deg), 선택. 오일러
 기준은 `base` 상자의 중심 (0, 0, 0)이다. **원점은 부품의 중심**이고 `position` 은
 그 원점의 자리다 — 여느 모델러와 같다.
 
-보드 컴포넌트의 state 는 `width` · `height` · `depth` 이고 축 배정도 다르다(그쪽은
+씬 컴포넌트의 state 는 `width` · `height` · `depth` 이고 축 배정도 다르다(그쪽은
 `depth` 가 높이다). 그 환산은 그리는 쪽 경계 한 곳에서 한다.
 
 ## 단위 규약
@@ -52,7 +52,7 @@ pitch: 150                          // 롤러 중심 간 거리 150mm
 | 필드          | 타입                       | 필수 | 뜻                                                                                                                          |
 | ------------- | -------------------------- | ---- | --------------------------------------------------------------------------------------------------------------------------- |
 | `version`     | `number`                   |      | 형식 판 번호. 기본값 1. 스키마 버전 명시 및 마이그레이션 기준선                                                             |
-| `type`        | `string`                   | ✓    | 컴포넌트 타입 이름. **저장되는 식별자다** — 보드가 이 이름으로 청사진을 찾는다. 바꾸면 이미 놓인 인스턴스가 세워지지 않는다 |
+| `type`        | `string`                   | ✓    | 컴포넌트 타입 이름. **저장되는 식별자다** — 씬이 이 이름으로 청사진을 찾는다. 바꾸면 이미 놓인 인스턴스가 세워지지 않는다 |
 | `base`        | `Vec3`                     | ✓    | 기준 크기(축별, mm). 배치 크기가 이 비율에서 나온다                                                                         |
 | `parts`       | `FigurePart[]`             | ✓    | 부품. 하나는 있어야 한다                                                                                                    |
 | `detailLevel` | `'S' \| 'M' \| 'L'`        |      | 부품 수 상한을 정한다 (3 · 8 · 20)                                                                                          |
@@ -504,5 +504,5 @@ animations    figure-real-object.ts (clip 을 실제로 돌린다)
 실제 병합 geometry 의 삼각형 수와 맞는지는 **아직 확인되지 않았다** — 특히
 `polygon` 의 `2(n−2) + 2n` 은 `ExtrudeGeometry` 의 실제 cap 삼각분할과 다를 수 있다.
 
-Figure 한 종의 값과 인스턴스별 추이는 `costOf` · `costCurve` 로 낸다. **보드 전체
+Figure 한 종의 값과 인스턴스별 추이는 `costOf` · `costCurve` 로 낸다. **도면 전체
 합계**(여러 타입이 섞인 판)는 내지 않는다 — 필요한 것이 Figure 단위라서 범위에서 뺐다.

package/docs/sizing.md

@@ -1,6 +1,6 @@
 # 크기 반응 — 인스턴스가 커질 때 부품이 어떻게 되나
 
-저작한 형상 하나가 보드에 여러 크기로 놓인다. 컨베이어를 2400 으로도, 7200 으로도
+저작한 형상 하나가 도면에 여러 크기로 놓인다. 컨베이어를 2400 으로도, 7200 으로도
 놓는다. 그때 부품마다 다르게 반응해야 한다 — 프레임은 길어지고, 모터는 그대로이고,
 롤러는 개수가 늘고, 다리는 늘어나 프레임을 떠받친다.
 

package/docs/validation.md

@@ -48,7 +48,7 @@ const { errors, violations } = validate(source)
 
 | 코드            | 언제                                      | 왜                                                        |
 | --------------- | ----------------------------------------- | --------------------------------------------------------- |
-| `missing-type`  | `type` 이 없거나 빈 문자다                | **저장되는 식별자다.** 보드가 이 이름으로 청사진을 찾는다 |
+| `missing-type`  | `type` 이 없거나 빈 문자다                | **저장되는 식별자다.** 씬이 이 이름으로 청사진을 찾는다 |
 | `missing-base`  | `base` 가 없다                            | 배치 크기가 이 비율에서 나온다                            |
 | `missing-parts` | `parts` 가 없거나 비었다                  | 부품이 하나는 있어야 한다. 여기서 검사를 멈춘다           |
 | `bad-style-kit` | `styleKit` 이 빈 문자이거나 문자가 아니다 |                                                           |
@@ -126,6 +126,30 @@ things-scene** 이므로(`registerCapabilityMeta`), 여기서는 **모양만**
 | `duplicate-capability`   | 같은 능력을 두 번 선언했다                             |
 | `bad-part-capability`    | 부품의 `capability` 모양이 틀렸다 — 역할·accepts·capacity |
 
+### 파라미터 (`parameters`)
+
+> ADR-0051 (`operato-twin/design/04-decisions.md`)
+
+값이 만드는 자세다 — 호이스트가 얼마나 내려왔나, 포크가 얼마나 올라갔나. **애니메이션이 아니다.**
+저것은 시각이 흐르는 것이고 이것은 지금 값이 그만큼인 것이다.
+
+두 층으로 되어 있다. `clip` 은 **glTF 애니메이션과 같은 모양**이라 내보내면 평범한 애니메이션이
+나가고, 그 위에 얹는 `range` 가 우리 것이다 — 「이 곡선은 값이 몬다」와 「그 값은 mm 로 몇부터
+몇까지다」. 못 받는 쪽은 선언만 잃고 형상은 잃지 않는다.
+
+곡선의 값 축은 0~1 이다(glTF morph target `weights` · Unity 파라미터와 같은 정규화). 저작자와
+인스턴스가 주고받는 것은 `range` 의 단위이고 런타임이 그 사이를 맵한다.
+
+| 코드            | 뜻                                                                 |
+| --------------- | ------------------------------------------------------------------ |
+| `missing-range` | `range` 나 `range.unit` 이 없다 — 인스턴스가 어느 값을 줄지 모른다     |
+| `bad-range`     | `max` 가 `min` 이하이거나, `default` 가 그 밖이다                  |
+
+이름은 `animations` 의 clip 이름과도 겹칠 수 없다. 인스턴스는 둘을 이름으로 부르므로 겹치면 어느 쪽에
+값을 준 것인지 알 수 없다.
+
+**옛 `drive: 'hold'` 는 `compile()` 이 여기로 옮긴다.** 저작자가 할 일이 아니라 기계적인 변환이다.
+
 부품의 `capability` 는 **그 능력을 어느 부품이 받쳐 주나**를 말한다. 역할은 셋이다.
 
 | 역할     | 씬에서                       |
@@ -181,6 +205,32 @@ things-scene** 이므로(`registerCapabilityMeta`), 여기서는 **모양만**
 | `too-many-surface-textures` | `LIMITS.surfaceTextures` (1)                 | 무늬·그라디언트는 **재질을 나눠 쓸 수 없다** — 인스턴스 수만큼 재질이 생긴다                  |
 | `capacity-with-repeat`      | —                                            | 반복하는 자리에 `capacity` 를 적었다 — 칸 수는 **인스턴스 크기**가 정하므로 쓰이지 않는다      |
 
+### 기준 상자
+
+> ADR-0044 (`operato-twin/design/04-decisions.md`)
+
+`base` 는 **저작자가 선언하는 점유 부피**다. 부품을 감싸는 최소 상자가 아니다 — 감싸는 상자면
+계산해서 나오는 값이라 저작자가 쓸 것이 아니고, 의도를 담을 자리가 없어진다. 컨베이어가 앞에
+두어야 하는 접근 공간, 랙의 칸 pitch 가 그 여백에 담긴다. **남는 여백은 선언이므로 보지 않는다.**
+
+넘치는 것과 기준면에 안 닿는 것은 **다른 결함이라 코드를 나눈다.** 하나로 뭉치면 저작자가 상자를
+키우는 쪽으로 고치는데, 뒤쪽이 필요로 하는 것은 부품을 제자리로 옮기는 것이다.
+
+| 코드                        | 언제                                                                     | 왜                                                                                              |
+| --------------------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
+| `part-outside-base`         | 부품이 `±base/2` 밖으로 나간다. 회전을 포함한 실제 부피로 잰다            | `base` 는 **나누는 수**다(`instanceScale = width/base.x`). 넘치면 그 수가 거짓말을 하고 도면에서 크기와 높이가 둘 다 틀린다 |
+| `parts-off-placement-face`  | 바닥 기반인데 상자 밑면에 안 닿는다 · 천정 기반인데 윗면에 안 닿는다      | 「선다」·「매달린다」고 선언해 놓고 떠 있다. **원점 규약이 어긋난 것**이지 상자가 큰 것이 아니다 |
+
+허용 오차는 `SKIN`(0.5) 하나다 — 발행 관문이 「덩어리가 갈라졌나」를 재는 값과 같다. 오차 상수가
+둘이면 한쪽이 닿았다고 한 면을 다른 쪽이 떨어졌다고 한다.
+
+**중심 기반(`center`)에는 기준면 요구가 없다.** 떠 있는 것이 그 배치의 뜻이다.
+
+밑면 아래로 지나가는 것은 **닿은 것으로 본다.** 지나간 사실은 `part-outside-base` 가 이미
+말하므로, 같은 일을 두 코드가 두 번 말하지 않는다.
+
+**이 둘은 발행을 막는다.** 이미 발행된 것은 그대로 서 있고, 고치기 전에는 다시 발행하지 못한다.
+
 ### draw call 을 세는 법
 
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hatiolab/figure-model",
-  "version": "0.1.17",
+  "version": "0.1.19",
   "description": "Figure 저작 결과의 정본 형식과 검증 — 재질별로 병합되고 이름이 붙은 부품 그래프. 3D 로 저작한 형상 하나가 씬 컴포넌트로 서는 데 필요한 것을 담는다.",
   "keywords": [
     "figure",