Things-Scene

Things-Scene은 웹 애플리케이션을 위한 2D/3D 씬 렌더링 및 편집 라이브러리입니다.

주요 특징

• 캔버스 기반 고성능 2D 렌더링
• Three.js 기반 3D 렌더링 (WebGL)
• 컴포넌트 기반 아키텍처
• 기즈모 편집 시스템 (Move/Rotate/Scale)
• Material3D 프리셋 시스템 (metal, glass, plastic, wood, ceramic, rubber)
• 2D↔3D 속성 자연스러운 연동
• GLTF/GLB 모델 로딩 및 노드별 제어
• ESM 및 UMD 형식 지원
• TypeScript strict mode

설치

npm install @hatiolab/things-scene

사용 방법

ESM 방식 (권장)

import { Scene, Component } from '@hatiolab/things-scene'

// 씬 생성 및 렌더링

UMD 방식

<script src="node_modules/@hatiolab/things-scene/things-scene-min.js"></script>
<script>
  const { Scene, Component } = window['things-scene']
</script>

3D 기능 (v10)

3D 모드 활성화

model-layer의 threed: true 속성으로 3D 모드를 활성화합니다.

Material3D API

컴포넌트의 material3d 속성으로 3D 재질을 제어합니다:

component.set('material3d', {
  preset: 'glass',     // 프리셋: default, metal, glass, plastic, wood, ceramic, rubber
  metalness: 0.5,      // 0~1
  roughness: 0.3,      // 0~1
  opacity: 0.3,        // 0~1 (프리셋 기본값 또는 명시적)
  envMapIntensity: 1.5, // 0~3
  side: 'double',      // double, front, back
  castShadow: true,
  receiveShadow: false,
})

3D 컴포넌트 타입

Sphere, Cube, Cylinder, Banner, Camera, Wall, GLTFObject, Light, Sprite

GLTF 모델

component.set('src', '/models/building.glb')
component.set('nodes', {
  'Wall': { color: '#ff0000', opacity: 0.5 },
  'Door': { visible: false }
})

빌드

| 포맷 | 파일명 | 용도 | | ---- | ------------------- | ------------- | | ESM | things-scene.mjs | 최신 브라우저 | | UMD | things-scene-min.js | 모든 환경 |

npm run build
npm test        # 1170+ tests
npm run type-check

개발 환경

자세한 내용은 DEVELOPMENT.md를 참조하세요.

v9 → v10 마이그레이션

Breaking Changes

• strict: true — strictPropertyInitialization 등 준수 필요
• Evaluator 샌드박스 강화 — window/document 접근 차단
• innerHTML → textContent + DOMPurify
• state getter가 Proxy로 변경 (동작 호환)
• bounds 반환값 Object.freeze (수정 시 spread 복사 필요)

상세: CHANGELOG.md

라이선스

이 프로젝트는 독점 라이선스로 배포됩니다. 라이선스 정보: http://things-scene.hatiolab.com/EULA/