@hatiolab/figure-model 0.1.8 → 0.1.11

package/docs/validation.md

@@ -40,7 +40,7 @@ const { errors, violations } = validate(source)
 | `not-finite`   | 수여야 할 자리가 수가 아니거나 `NaN`·`Infinity` 다                                                                            |
 | `not-positive` | 0 보다 커야 하는데 아니다 (`base` 의 세 변)                                                                                   |
 | `not-integer`  | `segments` 가 정수가 아니다                                                                                                   |
-| `out-of-range` | 아래위가 정해진 값이 그 밖이다 (`material.emissive.intensity` 는 0~1)                                                                |
+| `out-of-range` | 아래위가 정해진 값이 그 밖이다 (`material.emissive.intensity` 는 0~1, `animation.turnsPerSecond` 는 0 이상)                          |
 | `not-boolean`  | `material.flatShading` · `material.transparent` · `material.emissive.on` 이 참·거짓이 아니다                                       |
 | `not-allowed`  | 열거 값이 목록 밖이다 (`primitive` · `preset` · `slot` · `sizing` · `axis` · `detailLevel` · `animation.kind` · `label.when`) |
 
@@ -69,6 +69,8 @@ const { errors, violations } = validate(source)
 | 코드                 | 언제                                                     |
 | -------------------- | -------------------------------------------------------- |
 | `missing-shape-path` | `polygon` 인데 `shape.path` 가 없거나 점이 3 개 미만이다 |
+| `hollow-too-thick`    | 벽이나 바닥이 치수를 다 먹는다 — 팔 안쪽이 남지 않는다                                |
+| `hollow-not-convex`   | 오목한 `polygon` 은 아직 못 판다 — 안쪽 테가 제 몸을 가로지른다                       |
 | `bad-shape-point`    | `shape.path` 의 점이 `{ x, y }` 가 아니다                |
 
 ### 재질
@@ -84,12 +86,18 @@ const { errors, violations } = validate(source)
 | ---------------- | -------------------------------------------- |
 | `missing-repeat` | `sizing` 이 `'repeat'` 인데 `repeat` 가 없다 |
 
-### 애니메이션
+### 움직임
 
-| 코드            | 언제                     | 왜                                                                                             |
-| --------------- | ------------------------ | ---------------------------------------------------------------------------------------------- |
-| `missing-axis`  | 회전인데 `axis` 가 없다  | 어느 축으로 회전하는지 모른다                                                                      |
-| `missing-pivot` | 회전인데 `pivot` 이 없다 | 없으면 회전축이 부품 **자기 중심**이 된다. 교반 축이 몸체 가운데를 돌아야 하면 결과가 완전히 달라진다 |
+| 코드                     | 언제                                          | 왜                                                              |
+| ------------------------ | --------------------------------------------- | ---------------------------------------------------------------- |
+| `missing-channels`       | clip 에 `channels` 가 없거나 비었다           | 무엇을 움직이는지 모른다                                        |
+| `unknown-channel-target` | `channels[].target` 이 없는 부품을 가리킨다   | 조용히 아무것도 안 움직인다                                     |
+| `too-few-keys`           | `keys` 가 둘 미만이다                         | 하나짜리는 움직임이 아니라 자세 하나다. `transform` 이 그 자리다 |
+| `keys-out-of-order`      | 키의 시각이 앞의 것보다 크지 않다             | 표본추출이 뜻을 잃는다. 화면에서는 「이상하게 움직인다」로만 보인다 |
+
+clip 의 이름은 부품과 같은 코드를 쓴다 — 없으면 `missing-name`, 겹치면 `duplicate-name`.
+경로 · `drive` · `interpolation` 이 목록 밖이면 `not-allowed`, 키의 시각이 음수면
+`not-positive` 다.
 
 ### 예외 표면
 
@@ -118,6 +126,9 @@ const { errors, violations } = validate(source)
 | `segments-off-preset` | `segments` 가 프리셋(8 · 12 · 16 · 24 · 32 · 48) 밖이다. 값은 쓰이지만 geometry 키가 그만큼 늘어난다 |
 | `segments-ignored`    | 곡면이 없는 프리미티브에 `segments` 를 주었다                                         |
 | `repeat-ignored`      | `sizing` 이 `'repeat'` 가 아닌데 `repeat` 를 주었다                                   |
+| `anchor-ignored`      | `sizing` 이 `'scale'` 인데 `anchor` 를 주었다 — 상자와 함께 커지는 부품은 붙잡을 면이 없다 |
+| `hollow-ignored`      | 밀어 만드는 것이 아닌 프리미티브에 `shape.hollow` 를 주었다                            |
+| `pivot-ignored`       | `rotation` 이 아닌 채널에 `pivot` 을 주었다 — 아무 일도 안 일어난다                   |
 
 ### 예산
 
@@ -125,20 +136,39 @@ const { errors, violations } = validate(source)
 | --------------------------- | -------------------------------------------- | --------------------------------------------------------------------------------------------- |
 | `detail-level-missing`      | —                                            | 등급이 없으면 부품 수 예산을 잡을 수 없다                                                     |
 | `too-many-parts`            | `PART_LIMIT[detailLevel]` (S 3 · M 8 · L 20) |                                                                                               |
-| `too-many-animation-points` | `LIMITS.animationPoints` (2)                 | 포인트마다 묶음이 하나 늘고, 프레임마다 갱신이 는다                                           |
+| `too-many-animated-parts`   | `LIMITS.animatedParts` (2)                   | 움직이는 부품마다 묶음이 하나 늘고, 프레임마다 갱신이 는다                                    |
 | `too-many-material-groups`  | `LIMITS.materialGroups` (3)                  | **자산당 draw call 이 는다.** 세는 단위는 `groupKeyOf` — 컴파일러가 합치는 단위와 같은 식이다 |
 | `too-many-transparent`      | `LIMITS.transparentMaterials` (1)            | 투명 재질은 별도 정렬 경로를 탄다                                                             |
 | `too-many-always-labels`    | 1                                            | `'always'` 라벨은 대량 배치에서 DOM·텍스처를 늘린다                                           |
 | `too-many-surface-textures` | `LIMITS.surfaceTextures` (1)                 | 무늬·그라디언트는 **재질을 나눠 쓸 수 없다** — 인스턴스 수만큼 재질이 생긴다                  |
 
-### 묶음 수를 세는 법
+### draw call 을 세는 법
+
+```
+draw call = 합쳐진 묶음 하나당 1
+          + 단독으로 서는 부품 하나당 1
+          + repeat 부품은 사본 하나당 1
+```
+
+**단독으로 서는 것이 셋이다.**
+
+| 무엇 | 왜 |
+| --- | --- |
+| clip 이 움직이는 부품 | 합치면 그 부품만 따로 움직일 수 없다 |
+| `sizing` 이 `scale` 이 아닌 부품 | 합친 geometry 는 변환을 하나만 받는다 |
+| `repeat` 부품 | 한 부품이 여러 mesh 다 |
+
+한동안 이 자리가 「재질·슬롯 조합 수」였다. 그 값은 컴파일이 실제로 만드는 묶음보다
+작아서, 저작자에게 자산이 싸다고 알려 주는 숫자만 비용을 안 재고 있었다.
 
 ```
-묶음 수 = 재질·슬롯 조합 수 + 애니메이션 포인트 수
+컨베이어    3 으로 셌고 32 를 그렸다
+셀 트레이   2 로 셌고  9 를 그렸다
 ```
 
-애니메이션이 걸린 부품은 **제 묶음을 따로 갖는다.** 합쳐 버리면 그 부품만 따로
-움직일 수 없기 때문이다.
+`repeat` 개수는 **저작한 크기(배율 1)** 기준이다. 줄은 인스턴스가 받은 상자를 채우므로
+크게 놓으면 더 그린다.
+
 
 `groupKeyOf` 에 드는 것 — `token` · `preset` · `flatShading` · `transparent` · `slot`.
 투명 여부와 flatShading 이 키에 드는 이유는 셰이더와 정렬 경로가 달라 실제로 합칠 수

package/package.json

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