패키지

Mirage Engine은 pnpm 모노레포입니다. 보통 설치하는 건 mirage-engine 하나이고, 나머지는 필요한 조각만 골라 쓸 수 있도록 개별 배포됩니다.

패키지	npm	의존
`mirage-engine`	↗ (opens in a new tab)	core, painter, sandwich
`@mirage-engine/core`	↗ (opens in a new tab)	painter, dom-tracker, wasm-compute
`@mirage-engine/painter`	↗ (opens in a new tab)	three (peer)
`@mirage-engine/dom-tracker`	↗ (opens in a new tab)	—
`@mirage-engine/sandwich`	↗ (opens in a new tab)	dom-tracker
`@mirage-engine/wasm-compute`	내부용	Rust / wasm-bindgen

`@mirage-engine/core`

파사드를 뺀 전부입니다. 자체 래퍼를 만들 때 사용하세요.

import { Engine, WasmSynchronizer } from "@mirage-engine/core";
import type { CoreConfig, SceneNode, Quality } from "@mirage-engine/core";

`Engine`

메서드	시그니처	비고
`constructor`	`(target, config: CoreConfig)`	스타일 주입, 컨테이너 결정, Renderer + Syncer 생성
`start`	`(): Promise<void>`	wasm 부팅, 트래커 시작
`stop`	`(): void`	트래커 정지
`dispose`	`(): void`	정지 + 렌더러 해제
`getTracker`	`(): Tracker`	내부 DOM 트래커
`getCanvas`	`(): HTMLCanvasElement`	마운트된 캔버스
`updateUniforms`	`(el, uniforms): void`	유니폼 직접 쓰기

타입도 전부 함께 export됩니다 (SceneNode, NodeRect, Visibility, THREE_LAYERS, ATTR_* 상수, DIRTY_* 플래그, WASM_STRIDE와 OFFSET_* 인덱스).

`@mirage-engine/painter`

DOM 스타일을 그대로 반영하는 Three.js 머티리얼을 단독으로 제공합니다. DOM 관찰은 하지 않으며, 스타일은 직접 넘겨야 합니다.

import { Painter, TextGenerator, createBoxMaterial } from "@mirage-engine/painter";

`Painter`

Painter.create(
  type: "BOX" | "TEXT",
  styles: BoxStyles | TextStyles,
  content: string,
  width: number,
  height: number,
  quality?: number,
  texture?: THREE.Texture | null,
  shaderHooks?: ShaderHooks,
): THREE.Material
 
Painter.update(material, type, styles, content, width, height, quality?, texture?): void
 
Painter.forceUpdateUniforms(material: THREE.ShaderMaterial, values: BoxUniformValues): void

import * as THREE from "three";
import { Painter } from "@mirage-engine/painter";
 
const material = Painter.create("BOX", {
  backgroundColor: "rgb(20, 20, 30)",
  backgroundImage: "linear-gradient(45deg, #f00, #00f)",
  opacity: 1,
  zIndex: 0,
  borderRadius: "16px",
  borderColor: "rgba(255,255,255,0.2)",
  borderWidth: "2px",
  boxShadow: "0 8px 24px rgba(0,0,0,0.4)",
}, "", 320, 180);
 
const mesh = new THREE.Mesh(new THREE.PlaneGeometry(1, 1), material);
mesh.scale.set(320, 180, 1);

`TextGenerator`

텍스트를 CanvasTexture에 그리는 THREE.MeshBasicMaterial 서브클래스입니다.

const mat = new TextGenerator("Hello", textStyles, 200, 40, 2);
mat.updateText("Goodbye", textStyles, 200, 40);
mat.dispose();

CSS 파서

parsePixelValue, parseColor, splitByComma, parseLinearGradient, parseBoxShadow가 재사용 가능하도록 export됩니다. getComputedStyle이 반환하는 문자열 형태를 그대로 받습니다.

import { parseLinearGradient } from "@mirage-engine/painter";
 
parseLinearGradient("linear-gradient(45deg, red 0%, blue 100%)");
// { angle: 0.785…, stops: [ { color, alpha, stop }, … ] }

`@mirage-engine/dom-tracker`

렌더링에 관여하지 않는, 배치 처리 DOM 옵저버입니다. 의존성이 없습니다.

import { Tracker, extractFromStyle } from "@mirage-engine/dom-tracker";
 
const tracker = new Tracker(document.body, { resizeDebounce: { delay: 200 } });
 
tracker.onLayoutChange.add((mask, deletions) => { /* … */ });
tracker.onStyleChange.add((styles) => { /* Map<HTMLElement, StyleData> */ });
tracker.onRender.add(() => { /* 매 프레임 */ });
 
tracker.start();

훅	페이로드	발생 시점
`onBeforeRender`	—	매 프레임, 가장 먼저
`onLayoutChange`	`(mask: number, deletions: Set<HTMLElement>)`	트리가 더티일 때만
`onScrollChange`	`(scrollX, scrollY)`	윈도우 스크롤이 바뀌었을 때
`onStyleChange`	`Map<HTMLElement, StyleData>`	인라인 스타일이 변경됐을 때
`onRender`	—	매 프레임, 가장 마지막

각 훅은 Set이므로 add / delete로 구독을 관리합니다.

Mirage 자신은 onLayoutChange, onStyleChange, onRender를 구독합니다. onScrollChange는 발생하지만 내장 구독자가 없습니다 — 여러분을 위한 자리입니다.

`@mirage-engine/sandwich`

DOM 텔레포테이션. 페이지 레이아웃을 유지한 채 요소를 캔버스 위로 올립니다.

import { SandwichRenderer } from "@mirage-engine/sandwich";
 
const sandwich = new SandwichRenderer({ frontSelector: "[data-hud]" });
sandwich.init();

메서드	용도
`init()`	레이어 생성, front 요소 이관, 훅 연결, 트래커 시작
`useTracker(tracker)`	새로 만들지 않고 기존 트래커를 재사용

Mirage는 useTracker(engine.getTracker())를 자동으로 호출해서 둘이 하나의 requestAnimationFrame 루프를 공유하게 합니다.

`@mirage-engine/wasm-compute`

wasm-pack으로 컴파일하는 Rust 크레이트입니다. 직접 쓰라고 만든 건 아닙니다.

pub struct MemoryManager { /* Vec<f32> */ }
 
impl MemoryManager {
    pub fn new(capacity: usize) -> MemoryManager;
    pub fn get_pointer(&self) -> *const f32;
    pub fn get_length(&self) -> usize;
    pub fn update_physics(&mut self, node_count: usize);
}

노드당 5개의 float으로 구성됩니다.

[ parentIndex, localX, localY, worldX, worldY ]

update_physics는 노드를 순서대로 훑으면서 부모의 월드 좌표를 자식의 로컬 오프셋에 더합니다. 추출 단계에서 부모가 자식보다 먼저 기록되므로, 한 번의 정방향 패스로 트리 전체가 해결됩니다.

데이터 속성 개발 환경 설정