# Decal (데칼)

*바닥 표시 / 사이니지 / 위험 줄무늬 / AGV 경로 오버레이* 등 "표면에 덧칠하는"
장식용 평면 3D 표면. 부피 없음, 월드 공간에 고정 (카메라를 향하지 않는다 —
카메라를 향하는 빌보드 마커는 `Sprite` 사용).

## 언제 쓰나

- 바닥 구역 페인트 (작업 구역, 충전 구역, 위험 줄무늬)
- AGV 경로 오버레이
- 구역 / 부서 색상 강조
- 벽 포스터 / 위험 표지판 (회전시켜 벽면에 부착)
- 깊이 없이 3D 장면에 디테일을 더하는 표면

라벨이 필요한 표시는 데칼 위에 `Text` 컴포넌트를 얹는다.

## 가시성

데칼은 **3D 전용**이다. *의도적으로* 2D 캔버스에서는 보이지도 선택되지도
않는다 — 2D 모식도에서 평면 색 사각형은 시야만 어지럽힌다. 데칼을 작업하려면
모델러를 3D 모드로 전환한다.

- 2D 캔버스 — 비어 있음 (그리기 없음, 클릭 대상 없음)
- 3D 모드 — XZ 평면에 누운 plane 으로 표시. 한쪽 모서리 근처의 작은 *편집용
  선택 핸들*이 클릭 대상이다. mesh 본체 자체는 raycast 대상이 아니라 위에
  놓인 다른 컴포넌트들이 가려지지 않는다.

## 속성

| 속성             | 의미                                                                                                                  |
| ---------------- | --------------------------------------------------------------------------------------------------------------------- |
| `width / height` | 평면의 가로/세로 (XZ).                                                                                                |
| `fillStyle`      | 표면 색. `#RGB` / `#RRGGBB` / `#RRGGBBAA` / `rgb(...)` / `rgba(...)` 지원. 알파 채널은 material opacity 에 반영.       |
| `strokeStyle`    | 가장자리 선 색. plane 의 모서리에 `LineSegments` 로 표시.                                                             |
| `alpha`          | 인스턴스별 투명도 곱셈자 (0–1). `fillStyle.alpha` 와 곱해진다.                                                        |
| `rotation`       | 월드 공간에서 회전 (예: 90° 회전하면 벽면에 부착).                                                                    |

## Z-stack

데칼은 바닥 표면보다 *살짝 위*에 놓여 z-fighting 없이 floor-plate *위에* 덧칠
된다. 여러 데칼이 겹칠 경우 z-priority 로 순서가 정해진다.

## 비슷한 컴포넌트와 비교

| 컴포넌트       | 역할                                                                  |
| -------------- | --------------------------------------------------------------------- |
| **Decal**      | 월드 공간에 고정된 평면 표면 (이것).                                  |
| **Sprite**     | 항상 카메라를 향하는 평면 (빌보드).                                   |
| **FloorPlate** | 바닥 그 자체 — 데칼이 얹히는 *구조물*, 장식이 아님.                   |
| **Rect**       | 2D 위주의 사각형. 진짜로 2D 표현이 필요하면 이걸 쓴다.                |

## 팁

- 생성 직후 안 보이면 *3D 모드인지* 먼저 확인. 데칼은 설계상 2D 모양이
  없다.
- 정확한 크기 조정은 3D 모드에서 모서리 핸들로 선택 후 property panel 의
  `width` / `height` 입력으로 한다.
- 반투명 오버레이 (예: 구역 tint) 가 필요하면 `fillStyle` 에 rgba 를
  쓴다 — 예: `rgba(255, 200, 0, 0.4)`. 색과 투명도를 한 곳에서 제어할 수
  있다.