castle-web-cli 0.4.10 → 0.4.12

package/kits/basic-3d/engine/threeUtil.js

@@ -0,0 +1,260 @@
+import * as THREE from 'three';
+
+// Shared three.js helpers: scene lighting, geometry/material/model builders
+// (used by the Mesh + Model behaviors and the model editor preview), camera
+// spec application, and disposal.
+
+export const defaultLighting = {
+  sky: '#cfd9ff',
+  ground: '#3d3a33',
+  hemiIntensity: 0.9,
+  sun: '#fff4e0',
+  sunIntensity: 2.4,
+  sunAzimuth: 35,
+  sunElevation: 55,
+  shadows: true,
+};
+
+export function createSceneLights() {
+  const group = new THREE.Group();
+  const hemi = new THREE.HemisphereLight(0xffffff, 0x444444, 1);
+  const sun = new THREE.DirectionalLight(0xffffff, 1);
+  sun.castShadow = true;
+  sun.shadow.mapSize.set(2048, 2048);
+  sun.shadow.camera.left = -40;
+  sun.shadow.camera.right = 40;
+  sun.shadow.camera.top = 40;
+  sun.shadow.camera.bottom = -40;
+  sun.shadow.camera.near = 0.5;
+  sun.shadow.camera.far = 200;
+  sun.shadow.bias = -0.0005;
+  group.add(hemi, sun, sun.target);
+  return { group, hemi, sun };
+}
+
+export function applyLightingSettings(lights, settings) {
+  const s = { ...defaultLighting, ...(settings ?? {}) };
+  lights.hemi.color.set(s.sky);
+  lights.hemi.groundColor.set(s.ground);
+  lights.hemi.intensity = s.hemiIntensity;
+  lights.sun.color.set(s.sun);
+  lights.sun.intensity = s.sunIntensity;
+  lights.sun.castShadow = !!s.shadows;
+  const azimuth = (s.sunAzimuth * Math.PI) / 180;
+  const elevation = (s.sunElevation * Math.PI) / 180;
+  const radius = 60;
+  lights.sun.position.set(
+    radius * Math.cos(elevation) * Math.sin(azimuth),
+    radius * Math.sin(elevation),
+    radius * Math.cos(elevation) * Math.cos(azimuth)
+  );
+  lights.sun.target.position.set(0, 0, 0);
+}
+
+export const geometryKinds = ['box', 'sphere', 'cylinder', 'cone', 'capsule', 'torus', 'plane'];
+
+// Build a sized primitive geometry. `width`/`height`/`depth` are the bounding
+// dimensions for every kind, so swapping `geometry` keeps the actor's size.
+export function buildGeometry(kind, width, height, depth) {
+  const w = Math.max(0.01, width ?? 1);
+  const h = Math.max(0.01, height ?? 1);
+  const d = Math.max(0.01, depth ?? 1);
+  switch (kind) {
+    case 'sphere':
+      return scaledToBox(new THREE.SphereGeometry(0.5, 32, 16), w, h, d);
+    case 'cylinder':
+      return scaledToBox(new THREE.CylinderGeometry(0.5, 0.5, 1, 32), w, h, d);
+    case 'cone':
+      return scaledToBox(new THREE.ConeGeometry(0.5, 1, 32), w, h, d);
+    case 'capsule':
+      return scaledToBox(new THREE.CapsuleGeometry(0.25, 0.5, 8, 16), w, h, d);
+    case 'torus':
+      return scaledToBox(new THREE.TorusGeometry(0.35, 0.15, 16, 48), w, h, d);
+    case 'plane': {
+      const plane = new THREE.PlaneGeometry(w, d);
+      plane.rotateX(-Math.PI / 2);
+      return plane;
+    }
+    case 'box':
+    default:
+      return new THREE.BoxGeometry(w, h, d);
+  }
+}
+
+// Normalize a unit-ish primitive into a w x h x d bounding box.
+function scaledToBox(geometry, w, h, d) {
+  geometry.computeBoundingBox();
+  const size = new THREE.Vector3();
+  geometry.boundingBox.getSize(size);
+  geometry.scale(w / (size.x || 1), h / (size.y || 1), d / (size.z || 1));
+  return geometry;
+}
+
+export function buildStandardMaterial(props) {
+  const material = new THREE.MeshStandardMaterial();
+  applyStandardMaterial(material, props);
+  return material;
+}
+
+export function applyStandardMaterial(material, props) {
+  material.color.set(colorOf(props.color ?? '#ffffffff'));
+  material.roughness = props.roughness ?? 0.8;
+  material.metalness = props.metalness ?? 0;
+  material.emissive.set(colorOf(props.emissive ?? '#00000000'));
+  const opacity = alphaOf(props.color ?? '#ffffffff') * (props.opacity ?? 1);
+  material.transparent = opacity < 1;
+  material.opacity = opacity;
+}
+
+// `#rgb`, `#rrggbb`, or `#rrggbbaa` -- THREE.Color does not parse the alpha
+// byte, so strip it and surface it via `alphaOf`.
+export function colorOf(value) {
+  const raw = typeof value === 'string' ? value.trim() : '';
+  if (/^#[0-9a-fA-F]{8}$/.test(raw)) return raw.slice(0, 7);
+  return raw || '#ffffff';
+}
+
+export function alphaOf(value) {
+  const raw = typeof value === 'string' ? value.trim() : '';
+  if (/^#[0-9a-fA-F]{8}$/.test(raw)) return parseInt(raw.slice(7, 9), 16) / 255;
+  return 1;
+}
+
+// Multiply two hex colors (tint application for Model parts).
+export function multiplyColors(base, tint) {
+  const a = new THREE.Color(colorOf(base));
+  const b = new THREE.Color(colorOf(tint));
+  a.multiply(b);
+  return `#${a.getHexString()}`;
+}
+
+export const defaultModelPart = {
+  geometry: 'box',
+  x: 0,
+  y: 0,
+  z: 0,
+  rotationX: 0,
+  rotationY: 0,
+  rotationZ: 0,
+  width: 1,
+  height: 1,
+  depth: 1,
+  color: '#ffffffff',
+  roughness: 0.8,
+  metalness: 0,
+};
+
+// Build a THREE.Group from `.model` file data: `{ parts: [partProps...] }`.
+// Each mesh carries `userData.partIndex` so editors can raycast to a part.
+export function buildModelGroup(modelData, tint) {
+  const group = new THREE.Group();
+  for (const [index, rawPart] of (modelData?.parts ?? []).entries()) {
+    const part = { ...defaultModelPart, ...rawPart };
+    const geometry = buildGeometry(part.geometry, part.width, part.height, part.depth);
+    const color = tint ? multiplyColors(part.color, tint) : part.color;
+    const material = buildStandardMaterial({ ...part, color });
+    const mesh = new THREE.Mesh(geometry, material);
+    mesh.position.set(part.x, part.y, part.z);
+    mesh.rotation.set(
+      degreesToRadians(part.rotationX),
+      degreesToRadians(part.rotationY),
+      degreesToRadians(part.rotationZ)
+    );
+    mesh.castShadow = true;
+    mesh.receiveShadow = true;
+    mesh.userData.partIndex = index;
+    group.add(mesh);
+  }
+  return group;
+}
+
+export function degreesToRadians(degrees) {
+  return ((degrees ?? 0) * Math.PI) / 180;
+}
+
+export function radiansToDegrees(radians) {
+  return ((radians ?? 0) * 180) / Math.PI;
+}
+
+// Recursively dispose geometries + materials under an object.
+export function disposeObject3D(object) {
+  object.traverse((child) => {
+    child.geometry?.dispose?.();
+    const materials = Array.isArray(child.material) ? child.material : [child.material];
+    for (const material of materials) material?.dispose?.();
+  });
+}
+
+// Common prologue for render behaviors' `sync`: resolve the actor's group and
+// its `runtime` cache, or null when hidden (`actor.runtime.hidden`) / absent.
+export function renderTarget(actor, scene) {
+  if (actor.runtime?.hidden) return null;
+  const group = scene.actorGroup(actor);
+  if (!group) return null;
+  return { group, cache: actor.runtime };
+}
+
+// Remove a behavior's cached object from the actor group and dispose it.
+// Behaviors call this when their props key changes (and the kit calls it on
+// actor teardown via group disposal).
+export function replaceGroupChild(group, previous, next) {
+  if (previous) {
+    group.remove(previous);
+    disposeObject3D(previous);
+  }
+  if (next) group.add(next);
+  return next;
+}
+
+// Create the WebGL renderer for a viewport canvas. `preserveDrawingBuffer`
+// keeps the frame readable for screenshots/preview capture.
+export function createRenderer(canvas) {
+  const renderer = new THREE.WebGLRenderer({
+    canvas,
+    antialias: true,
+    preserveDrawingBuffer: true,
+  });
+  renderer.shadowMap.enabled = true;
+  renderer.shadowMap.type = THREE.PCFSoftShadowMap;
+  renderer.outputColorSpace = THREE.SRGBColorSpace;
+  return renderer;
+}
+
+// Match the renderer + camera to the canvas's CSS size each frame (cheap when
+// nothing changed). Returns false when the canvas has no size yet.
+export function fitRendererToCanvas(renderer, camera, canvas) {
+  const width = canvas.clientWidth;
+  const height = canvas.clientHeight;
+  if (!width || !height) return false;
+  const pixelRatio = Math.min(window.devicePixelRatio || 1, 2);
+  if (renderer.getPixelRatio() !== pixelRatio) renderer.setPixelRatio(pixelRatio);
+  const size = renderer.getSize(new THREE.Vector2());
+  if (size.x !== width || size.y !== height) renderer.setSize(width, height, false);
+  const aspect = width / height;
+  if (camera.aspect !== aspect) {
+    camera.aspect = aspect;
+    camera.updateProjectionMatrix();
+  }
+  return true;
+}
+
+// Apply a runtime camera spec (`scene.camera`, e.g. from the Camera behavior)
+// to a PerspectiveCamera. Spec: target point + azimuth/elevation/distance
+// orbit position + fov.
+export function applyCameraSpec(camera, spec) {
+  const azimuth = degreesToRadians(spec.azimuth ?? 45);
+  const elevation = degreesToRadians(spec.elevation ?? 35);
+  const distance = spec.distance ?? 24;
+  const target = new THREE.Vector3(spec.targetX ?? 0, spec.targetY ?? 0, spec.targetZ ?? 0);
+  camera.position.set(
+    target.x + distance * Math.cos(elevation) * Math.sin(azimuth),
+    target.y + distance * Math.sin(elevation),
+    target.z + distance * Math.cos(elevation) * Math.cos(azimuth)
+  );
+  camera.lookAt(target);
+  const fov = spec.fov ?? 50;
+  if (camera.fov !== fov) {
+    camera.fov = fov;
+    camera.updateProjectionMatrix();
+  }
+}

package/kits/basic-3d/engine/ui.jsx

@@ -0,0 +1,352 @@
+import React, { useRef, useState } from 'react';
+import {
+  faArrowsAlt,
+  faBars,
+  faChevronDown,
+  faChevronRight,
+  faChevronUp,
+  faClone,
+  faCube,
+  faExpandArrowsAlt,
+  faObjectGroup,
+  faPalette,
+  faPlay,
+  faPlus,
+  faRedo,
+  faStop,
+  faSyncAlt,
+  faTimes,
+  faTrash,
+  faUndo,
+  faVideo,
+} from '@fortawesome/free-solid-svg-icons';
+import styles from './ui.module.css';
+export { styles };
+export const theme = {
+  transparentChecker:
+    'repeating-linear-gradient(45deg, #050505, #050505 4px, #252525 4px, #252525 8px)',
+};
+export function cx(...parts) {
+  return parts.filter(Boolean).join(' ');
+}
+export function AppShell({ children }) {
+  return <div className={styles.appShell}>{children}</div>;
+}
+export function MainEditor({ children }) {
+  return <main className={styles.mainEditor}>{children}</main>;
+}
+export function EditorHeader({ title, subtitle, right, onToggleFiles, filesOpen }) {
+  const hasRight = !!right || !!onToggleFiles;
+  return (
+    <header className={styles.editorHeader}>
+      <div className={styles.editorHeaderLeft}>
+        <div>
+          <div className={styles.editorTitle}>{title}</div>
+          {subtitle ? <div className={styles.muted}>{subtitle}</div> : null}
+        </div>
+      </div>
+      {hasRight ? (
+        <div className={styles.editorHeaderRight}>
+          {right}
+          {onToggleFiles ? (
+            <button
+              type="button"
+              className={cx(styles.headerFilesButton, styles.mobileOnly)}
+              onClick={onToggleFiles}
+              aria-label="Files"
+              aria-pressed={filesOpen ? 'true' : 'false'}>
+              <Icon name="bars" />
+            </button>
+          ) : null}
+        </div>
+      ) : null}
+    </header>
+  );
+}
+export function EditorBody({ children }) {
+  return <div className={styles.editorBody}>{children}</div>;
+}
+export function Button({ children, active = false, variant = '', className = '', ...props }) {
+  return (
+    <button
+      className={cx(
+        styles.button,
+        active && styles.buttonActive,
+        variant === 'primary' && styles.buttonPrimary,
+        variant === 'danger' && styles.buttonDanger,
+        className
+      )}
+      {...props}>
+      {children}
+    </button>
+  );
+}
+export function IconButton({ icon, label, active = false, variant = '', ...props }) {
+  return (
+    <Button
+      active={active}
+      variant={variant}
+      className={styles.iconButton}
+      aria-label={label}
+      title={label}
+      {...props}>
+      <Icon name={icon} />
+    </Button>
+  );
+}
+const icons = {
+  bars: faBars,
+  camera: faVideo,
+  cube: faCube,
+  move: faArrowsAlt,
+  rotate: faSyncAlt,
+  scale: faExpandArrowsAlt,
+  'chevron-down': faChevronDown,
+  'chevron-right': faChevronRight,
+  'chevron-up': faChevronUp,
+  clone: faClone,
+  'object-group': faObjectGroup,
+  palette: faPalette,
+  play: faPlay,
+  plus: faPlus,
+  redo: faRedo,
+  stop: faStop,
+  times: faTimes,
+  trash: faTrash,
+  undo: faUndo,
+};
+export function Icon({ name }) {
+  const def = icons[name];
+  if (!def) return null;
+  const [width, height, , , path] = def.icon;
+  const d = Array.isArray(path) ? path.join(' ') : path;
+  return (
+    <svg
+      viewBox={`0 0 ${width} ${height}`}
+      aria-hidden="true"
+      style={{ width: '1em', height: '1em', display: 'inline-block', fill: 'currentColor' }}>
+      <path d={d} />
+    </svg>
+  );
+}
+export function Panel({ title, children }) {
+  return (
+    <section className={styles.panel}>
+      {title ? <div className={styles.panelHeader}>{title}</div> : null}
+      <div className={styles.panelBody}>{children}</div>
+    </section>
+  );
+}
+export function FieldRow({ label, children }) {
+  return (
+    <label className={styles.fieldRow}>
+      <span className={styles.fieldLabel}>{label}</span>
+      {children}
+    </label>
+  );
+}
+export function TextField({ label, value, onChange }) {
+  return (
+    <FieldRow label={label}>
+      <input
+        className={styles.input}
+        value={value ?? ''}
+        onChange={(event) => onChange(event.target.value)}
+      />
+    </FieldRow>
+  );
+}
+export function NumberField({ label, value, onChange, min, max, step = 1 }) {
+  const current = Number.isFinite(value) ? (value ?? 0) : 0;
+  const [draft, setDraft] = useState(String(current));
+  const editingRef = useRef(false);
+  const cancelRef = useRef(false);
+  // keep the draft in sync with the committed value while not editing
+  if (!editingRef.current && draft !== String(current)) {
+    setDraft(String(current));
+  }
+  function commit(raw) {
+    let next = Number(raw);
+    if (!Number.isFinite(next)) next = current;
+    if (min != null && next < min) next = min;
+    if (max != null && next > max) next = max;
+    setDraft(String(next));
+    onChange(next);
+  }
+  function stepBy(delta) {
+    let next = current + delta;
+    if (min != null && next < min) next = min;
+    if (max != null && next > max) next = max;
+    setDraft(String(next));
+    onChange(next);
+  }
+  return (
+    <FieldRow label={label}>
+      <div className={styles.numberField}>
+        <input
+          className={cx(styles.input, styles.numberInput)}
+          type="number"
+          min={min}
+          max={max}
+          step={step}
+          value={draft}
+          onFocus={() => {
+            editingRef.current = true;
+          }}
+          onChange={(event) => setDraft(event.target.value)}
+          onBlur={(event) => {
+            editingRef.current = false;
+            if (cancelRef.current) {
+              cancelRef.current = false;
+              setDraft(String(current));
+              return;
+            }
+            commit(event.target.value);
+          }}
+          onKeyDown={(event) => {
+            if (event.key === 'Enter') {
+              event.preventDefault();
+              commit(event.currentTarget.value);
+              event.currentTarget.blur();
+            } else if (event.key === 'Escape') {
+              event.preventDefault();
+              cancelRef.current = true;
+              setDraft(String(current));
+              event.currentTarget.blur();
+            }
+          }}
+        />
+        <div className={styles.numberSteppers}>
+          <button
+            type="button"
+            className={styles.numberStepper}
+            tabIndex={-1}
+            aria-label="Increment"
+            disabled={max != null && current >= max}
+            onClick={() => stepBy(step)}>
+            <Icon name="chevron-up" />
+          </button>
+          <button
+            type="button"
+            className={styles.numberStepper}
+            tabIndex={-1}
+            aria-label="Decrement"
+            disabled={min != null && current <= min}
+            onClick={() => stepBy(-step)}>
+            <Icon name="chevron-down" />
+          </button>
+        </div>
+      </div>
+    </FieldRow>
+  );
+}
+export function CheckboxField({ label, checked, onChange }) {
+  return (
+    <FieldRow label={label}>
+      <button
+        type="button"
+        className={cx(styles.toggle, checked && styles.toggleOn)}
+        role="switch"
+        aria-checked={!!checked}
+        onClick={() => onChange(!checked)}>
+        <span className={styles.toggleKnob} />
+      </button>
+    </FieldRow>
+  );
+}
+export function ColorField({ label, value, onChange }) {
+  const hex = normalizeHex(value);
+  const alpha = hex.length === 9 ? hex.slice(7) : '';
+  const rgb = hex.slice(0, 7);
+  return (
+    <FieldRow label={label}>
+      <input
+        className={styles.colorInput}
+        type="color"
+        value={rgb}
+        onChange={(event) => onChange(event.target.value + alpha)}
+      />
+    </FieldRow>
+  );
+}
+function normalizeHex(value) {
+  const raw = (value ?? '').trim();
+  if (/^#[0-9a-fA-F]{3}$/.test(raw)) {
+    return '#' + raw.slice(1).replace(/./g, (c) => c + c);
+  }
+  if (/^#[0-9a-fA-F]{6}([0-9a-fA-F]{2})?$/.test(raw)) return raw;
+  return '#000000';
+}
+export function isHexColor(value) {
+  return (
+    typeof value === 'string' && /^#[0-9a-fA-F]{3}([0-9a-fA-F]{3}([0-9a-fA-F]{2})?)?$/.test(value)
+  );
+}
+export function useMobileSheet({ snap, baseClassName, onTransition }) {
+  const startY = useRef(0);
+  const lastDy = useRef(0);
+  const dragging = useRef(false);
+  function onPointerDown(event) {
+    startY.current = event.clientY;
+    lastDy.current = 0;
+    dragging.current = true;
+    event.currentTarget.setPointerCapture(event.pointerId);
+  }
+  function onPointerMove(event) {
+    if (!dragging.current) return;
+    lastDy.current = event.clientY - startY.current;
+  }
+  function endDrag() {
+    if (!dragging.current) return;
+    dragging.current = false;
+    const dy = lastDy.current;
+    lastDy.current = 0;
+    if (Math.abs(dy) < 6) onTransition('tap');
+    else if (dy > 30) onTransition('down');
+    else if (dy < -30) onTransition('up');
+  }
+  return {
+    rootProps: {
+      className: baseClassName,
+      'data-sheet-snap': snap,
+    },
+    grabProps: {
+      className: cx(styles.sheetGrab, styles.mobileOnly),
+      onPointerDown,
+      onPointerMove,
+      onPointerUp: endDrag,
+      onPointerCancel: endDrag,
+    },
+  };
+}
+export function SheetGrabHandle({ label, hint }) {
+  return (
+    <>
+      <div className={styles.sheetGrabBar} />
+      <div className={styles.sheetGrabLabelRow}>
+        <span className={styles.sheetGrabLabel}>{label}</span>
+        {hint ? <span className={styles.sheetGrabHint}>{hint}</span> : null}
+      </div>
+    </>
+  );
+}
+export function SelectField({ label, value, onChange, options }) {
+  return (
+    <FieldRow label={label}>
+      <select
+        className={styles.select}
+        value={value ?? ''}
+        onChange={(event) => onChange(event.target.value)}>
+        {options.map((option) => {
+          const value = typeof option === 'string' ? option : option.value;
+          const label = typeof option === 'string' ? option : option.label;
+          return (
+            <option key={value} value={value}>
+              {label}
+            </option>
+          );
+        })}
+      </select>
+    </FieldRow>
+  );
+}