@operato/scene-transport 10.0.0-beta.22

package/src/forklift.ts

@@ -0,0 +1,200 @@
+/*
+ * Copyright © HatioLab Inc. All rights reserved.
+ */
+import { Component, ComponentNature, Container, RealObject, sceneComponent } from '@hatiolab/things-scene'
+import {
+  Legendable,
+  Placeable,
+  type Alignment,
+  type Heights,
+  type LegendBinding,
+  type PlacementArchetype
+} from '@operato/scene-base'
+
+import { Forklift3D } from './forklift-3d.js'
+
+/**
+ * Forklift status — the operating state of a forklift truck.
+ *
+ * - `idle`     — parked, engine off
+ * - `running`  — driving (no load)
+ * - `lifting`  — actively lifting / lowering forks
+ * - `loaded`   — driving with cargo on forks
+ * - `error`    — fault / emergency stop
+ *
+ * The 5-state set differs from Conveyor's because forklifts have a distinct
+ * loaded-vs-empty distinction relevant for fleet visualization.
+ */
+export type ForkliftStatus = 'idle' | 'running' | 'lifting' | 'loaded' | 'error'
+
+/** Body color — yellow base hue, modulated slightly by status for at-a-glance state. */
+const BODY_LEGEND = {
+  idle: '#d4a017',     // muted yellow (parked)
+  running: '#FFD700',  // bright yellow (active)
+  lifting: '#FFD700',
+  loaded: '#FFA500',   // orange tint (carrying)
+  error: '#e9746b',    // red
+  default: '#d4a017'
+}
+
+/** Status lamp emissive — saturated for at-a-glance status from a distance. */
+const LAMP_EMISSIVE_LEGEND = {
+  idle: '#333333',
+  running: '#44ff44',  // green (operating)
+  lifting: '#44aaff',  // blue (lifting)
+  loaded: '#ffaa00',   // amber (loaded)
+  error: '#ff3333',    // red
+  default: '#333333'
+}
+
+const NATURE: ComponentNature = {
+  mutable: false,
+  resizable: true,
+  rotatable: true,
+  properties: [
+    {
+      type: 'select',
+      label: 'status',
+      name: 'status',
+      property: {
+        options: [
+          { display: 'Idle', value: 'idle' },
+          { display: 'Running', value: 'running' },
+          { display: 'Lifting', value: 'lifting' },
+          { display: 'Loaded', value: 'loaded' },
+          { display: 'Error', value: 'error' }
+        ]
+      }
+    },
+    {
+      type: 'number',
+      label: 'fork-height',
+      name: 'forkHeight',
+      placeholder: '0..2000mm'
+    }
+  ],
+  help: 'scene/component/forklift'
+}
+
+const Base = Legendable(Placeable(Container)) as unknown as typeof Component
+
+/**
+ * Forklift — a powered industrial truck used to lift and transport material
+ * over short distances.
+ *
+ * **Container-based for cargo containment.** A Forklift extends `Container` so
+ * that loaded items (boxes, parcels, pallets) can be added as children. The
+ * intended visual semantics: the children's 3D representations should appear
+ * sitting on the forks, at a height determined by `state.forkHeight`. The
+ * actual *positioning* of cargo on the forks is a v2 concern — for now,
+ * children render with their declared archetype's zPos (operation level by
+ * default), which approximates the fork-down position but won't track
+ * `forkHeight` dynamically. See `forklift-3d.ts` for the fork attach point.
+ */
+@sceneComponent('forklift')
+export default class Forklift extends Base {
+  static legends: Record<string, LegendBinding> = {
+    bodyColor: { from: 'status', legend: BODY_LEGEND },
+    lampEmissive: { from: 'status', legend: LAMP_EMISSIVE_LEGEND }
+  }
+
+  /**
+   * Forklift sits on its wheels — `floor` archetype. Default depth is the
+   * forklift's overall envelope with mast collapsed (~= operation level).
+   */
+  static placement: PlacementArchetype = 'floor'
+  static align: Alignment = 'bottom'
+  static defaultDepth = (h: Heights) => h.operation - h.floor
+
+  get nature() {
+    return NATURE
+  }
+
+  get anchors() {
+    return []
+  }
+
+  /**
+   * Allow items that flow at operation level (boxes, cartons, parcels, loaded
+   * pallets) to be added as cargo. Restricting by archetype rather than type
+   * means new package components are auto-permitted as they're added to the
+   * scene-base ecosystem.
+   */
+  containable(component: Component) {
+    const archetype = (component.constructor as any).placement
+    if (archetype === 'operation') return true
+    // Container's default — accept anything descendible (default things-scene policy).
+    return component.isDescendible(this as any)
+  }
+
+  /**
+   * 2D — render() sets the body silhouette path (auto-filled with bodyColor
+   * via the Legendable→fillStyle chain). postrender() draws structural
+   * details (forks, mast bar, counterweight tail-light hint, status lamp).
+   */
+  render(ctx: CanvasRenderingContext2D) {
+    const { width, height, left, top } = this.state
+    const forkLen = height * 0.30
+    const cwBulge = height * 0.10
+    const radius = Math.min(width, height) * 0.10
+
+    ctx.beginPath()
+    // Body with rounded corners + rear counterweight bulge (slight extension at top
+    // edge in top-view convention: top = back of forklift)
+    ctx.roundRect(left, top - cwBulge, width, height - forkLen + cwBulge, radius)
+  }
+
+  postrender(ctx: CanvasRenderingContext2D) {
+    super.postrender?.(ctx)
+
+    const { width, height, left, top } = this.state
+    const forkLen = height * 0.30
+    const accentColor = (this.state.lampEmissive as string) || '#44ff44'
+
+    ctx.save()
+
+    // Mast (thin horizontal bar at the front of the body, before the forks)
+    const mastY = top + height - forkLen
+    ctx.fillStyle = '#444455'
+    ctx.fillRect(left + width * 0.10, mastY - height * 0.025, width * 0.80, height * 0.025)
+
+    // Forks (two prongs extending forward — bottom of the top-down silhouette)
+    const forkW = width * 0.10
+    ctx.fillStyle = '#222233'
+    ctx.strokeStyle = '#111'
+    ctx.lineWidth = 1
+    for (const xFrac of [0.20, 0.70]) {
+      ctx.beginPath()
+      ctx.rect(left + width * xFrac, mastY, forkW, forkLen)
+      ctx.fill()
+      ctx.stroke()
+    }
+
+    // Tail lights on counterweight rear (top edge in top-down view)
+    ctx.fillStyle = '#ff2222'
+    const tailLightW = width * 0.08
+    const tailLightH = height * 0.025
+    const cwBulge = height * 0.10
+    ctx.fillRect(left + width * 0.15, top - cwBulge + tailLightH * 0.5, tailLightW, tailLightH)
+    ctx.fillRect(left + width - width * 0.15 - tailLightW, top - cwBulge + tailLightH * 0.5, tailLightW, tailLightH)
+
+    // Status lamp on top of overhead guard (center)
+    const lampR = Math.min(width, height) * 0.06
+    ctx.fillStyle = accentColor
+    ctx.strokeStyle = '#111'
+    ctx.beginPath()
+    ctx.ellipse(left + width / 2, top + height * 0.30, lampR, lampR, 0, 0, Math.PI * 2)
+    ctx.fill()
+    ctx.stroke()
+
+    ctx.restore()
+  }
+
+  get fillStyle() {
+    return (this.state.bodyColor as string) || '#d4a017'
+  }
+
+  buildRealObject(): RealObject | undefined {
+    return new Forklift3D(this as any)
+  }
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+/*
+ * Copyright © HatioLab Inc. All rights reserved.
+ */
+export { default as Forklift } from './forklift.js'
+export type { ForkliftStatus } from './forklift.js'
+
+export { default as Worker } from './worker.js'
+export type { WorkerStatus } from './worker.js'
+
+export { default as Agv } from './agv.js'
+export type { AgvStatus } from './agv.js'
+
+export { default as Tugger } from './tugger.js'
+export type { TuggerStatus } from './tugger.js'

package/src/templates/index.ts

@@ -0,0 +1,73 @@
+/*
+ * things-scene catalog templates for the transport domain.
+ *
+ * Icons reference PNG assets in `packages/transport/icons/`. They are not yet
+ * shipped — the catalog will fall back to the default rendering if icons are
+ * missing. Add icon files before publishing the catalog publicly.
+ */
+const forklift = new URL('../../icons/forklift.png', import.meta.url).href
+const worker = new URL('../../icons/worker.png', import.meta.url).href
+const agv = new URL('../../icons/agv.png', import.meta.url).href
+const tugger = new URL('../../icons/tugger.png', import.meta.url).href
+
+export default [
+  {
+    type: 'forklift',
+    description: 'forklift truck',
+    group: 'transport',
+    icon: forklift,
+    model: {
+      type: 'forklift',
+      top: 100,
+      left: 100,
+      width: 120,
+      height: 200,
+      status: 'idle',
+      forkHeight: 0
+    }
+  },
+  {
+    type: 'worker',
+    description: 'human worker',
+    group: 'transport',
+    icon: worker,
+    model: {
+      type: 'worker',
+      top: 100,
+      left: 300,
+      width: 50,
+      height: 50,
+      status: 'idle'
+    }
+  },
+  {
+    type: 'agv',
+    description: 'payload AGV (unit-load, Kiva-style)',
+    group: 'transport',
+    icon: agv,
+    model: {
+      type: 'agv',
+      top: 100,
+      left: 500,
+      width: 200,
+      height: 200,
+      status: 'idle',
+      battery: 1
+    }
+  },
+  {
+    type: 'tugger',
+    description: 'tugger AGV (towing tractor)',
+    group: 'transport',
+    icon: tugger,
+    model: {
+      type: 'tugger',
+      top: 100,
+      left: 800,
+      width: 150,
+      height: 250,
+      status: 'idle',
+      battery: 1
+    }
+  }
+]

package/src/tugger-3d.ts

@@ -0,0 +1,169 @@
+/*
+ * Copyright © HatioLab Inc. All rights reserved.
+ *
+ * Tugger 3D — towing AGV.
+ *
+ * LO-POLY but structurally complete:
+ *
+ *   - chassis (compact body, ~600mm tall — no cargo deck)
+ *   - control panel hump on top (operator-less but houses electronics)
+ *   - 4 wheels (front pair = drive/steer, larger; rear pair = caster, smaller)
+ *   - LiDAR sensor at front (forward-facing — detects obstacles)
+ *   - hitch at rear (the defining feature — what distinguishes a tugger from
+ *     a payload AGV)
+ *   - status lamp on top of control panel
+ *
+ * Design rule: the hitch is the visual signature. Without it, this looks like
+ * a tall payload AGV. Make sure the hitch is unambiguously visible.
+ */
+
+import * as THREE from 'three'
+import * as BufferGeometryUtils from 'three/examples/jsm/utils/BufferGeometryUtils.js'
+import { RoundedBoxGeometry } from 'three/examples/jsm/geometries/RoundedBoxGeometry.js'
+import { RealObjectGroup } from '@hatiolab/things-scene'
+
+const TIRE_COLOR = 0x202020
+const HITCH_COLOR = 0x222233
+const PANEL_COLOR = 0x444455
+const LIDAR_COLOR = 0x222233
+
+export class Tugger3D extends RealObjectGroup {
+  build() {
+    super.build()
+
+    const { width, height, depth = 600 } = this.component.state
+    const bodyColor = (this.component.state.bodyColor as string) || '#666'
+    const emissiveColor = (this.component.state.lampEmissive as string) || '#222222'
+    const status = this.component.state.status
+    const lampIntensity = status && status !== 'idle' ? 1.5 : 0.2
+
+    // Proportions
+    const chassisH = depth * 0.55
+    const panelH = depth * 0.30
+    const wheelR = chassisH * 0.45
+    const baseY = -depth / 2
+
+    const bodyMaterial = new THREE.MeshStandardMaterial({
+      color: bodyColor,
+      metalness: 0.4,
+      roughness: 0.5
+    })
+
+    // ── Chassis (rounded body) ────────────────────────────────────
+    const chassisRadius = Math.min(width, height) * 0.10
+    const chassisGeo = new RoundedBoxGeometry(width * 0.9, chassisH, height * 0.85, 4, chassisRadius)
+    const chassisMesh = new THREE.Mesh(chassisGeo, bodyMaterial)
+    chassisMesh.position.set(0, baseY + chassisH / 2 + wheelR * 0.3, 0)
+    chassisMesh.castShadow = true
+    chassisMesh.receiveShadow = true
+    this.object3d.add(chassisMesh)
+
+    // ── Control panel (rounded hump on top) ───────────────────────
+    const panelGeo = new RoundedBoxGeometry(width * 0.55, panelH, height * 0.5, 3, chassisRadius * 0.6)
+    const panelMesh = new THREE.Mesh(
+      panelGeo,
+      new THREE.MeshStandardMaterial({ color: PANEL_COLOR, metalness: 0.5, roughness: 0.4 })
+    )
+    panelMesh.position.set(0, baseY + chassisH + panelH / 2 + wheelR * 0.3, 0)
+    panelMesh.castShadow = true
+    this.object3d.add(panelMesh)
+
+    // ── LiDAR sensor at front ─────────────────────────────────────
+    const lidarR = Math.min(width, height) * 0.07
+    const lidarH = lidarR * 0.7
+    const lidarGeo = new THREE.CylinderGeometry(lidarR, lidarR * 1.1, lidarH, 24)
+    const lidarMesh = new THREE.Mesh(
+      lidarGeo,
+      new THREE.MeshStandardMaterial({ color: LIDAR_COLOR, metalness: 0.6, roughness: 0.4 })
+    )
+    lidarMesh.position.set(0, baseY + chassisH + lidarH / 2 + wheelR * 0.3, height * 0.40)
+    lidarMesh.castShadow = true
+    this.object3d.add(lidarMesh)
+
+    // ── Hitch at rear (the tugger's signature) ────────────────────
+    const hitchW = width * 0.15
+    const hitchH = chassisH * 0.30
+    const hitchD = height * 0.18
+    const hitchMaterial = new THREE.MeshStandardMaterial({
+      color: HITCH_COLOR,
+      metalness: 0.85,
+      roughness: 0.4
+    })
+
+    // Hitch arm (horizontal bar extending rearward)
+    const hitchArmGeo = new THREE.BoxGeometry(hitchW * 0.4, hitchH * 0.4, hitchD)
+    const hitchArmMesh = new THREE.Mesh(hitchArmGeo, hitchMaterial)
+    hitchArmMesh.position.set(0, baseY + wheelR * 0.6, -height * 0.5 - hitchD / 2)
+    hitchArmMesh.castShadow = true
+    this.object3d.add(hitchArmMesh)
+
+    // Hitch coupler (the ball/pin where a trailer attaches)
+    const couplerR = hitchH * 0.5
+    const couplerGeo = new THREE.SphereGeometry(couplerR, 20, 8)
+    const couplerMesh = new THREE.Mesh(couplerGeo, hitchMaterial)
+    couplerMesh.position.set(0, baseY + wheelR * 0.6 + couplerR * 0.5, -height * 0.5 - hitchD - couplerR * 0.2)
+    couplerMesh.castShadow = true
+    this.object3d.add(couplerMesh)
+
+    // ── Wheels — front (larger, drive/steer) and rear (smaller, caster) ─
+    const frontWheelR = wheelR
+    const rearWheelR = wheelR * 0.7
+    const wheelGeometries: THREE.BufferGeometry[] = []
+
+    // Front pair
+    for (const xSign of [-1, 1]) {
+      const wheel = new THREE.CylinderGeometry(frontWheelR, frontWheelR, width * 0.08, 20)
+      wheel.rotateZ(Math.PI / 2)
+      wheel.translate(xSign * width * 0.4, baseY + frontWheelR, height * 0.30)
+      wheelGeometries.push(wheel)
+    }
+    // Rear pair (smaller)
+    for (const xSign of [-1, 1]) {
+      const wheel = new THREE.CylinderGeometry(rearWheelR, rearWheelR, width * 0.07, 20)
+      wheel.rotateZ(Math.PI / 2)
+      wheel.translate(xSign * width * 0.35, baseY + rearWheelR, -height * 0.32)
+      wheelGeometries.push(wheel)
+    }
+
+    const wheelMesh = new THREE.Mesh(
+      BufferGeometryUtils.mergeGeometries(wheelGeometries),
+      new THREE.MeshStandardMaterial({ color: TIRE_COLOR, roughness: 0.95 })
+    )
+    wheelMesh.castShadow = true
+    this.object3d.add(wheelMesh)
+
+    // ── Status lamp on control panel top ──────────────────────────
+    const lampR = Math.min(width, height) * 0.05
+    const lampH = lampR * 1.3
+    const lampMaterial = new THREE.MeshStandardMaterial({
+      color: emissiveColor,
+      emissive: emissiveColor,
+      emissiveIntensity: lampIntensity,
+      metalness: 0,
+      roughness: 0.3
+    })
+    const lampGeo = new THREE.CylinderGeometry(lampR, lampR * 0.85, lampH, 20)
+    const lampMesh = new THREE.Mesh(lampGeo, lampMaterial)
+    lampMesh.position.set(0, baseY + chassisH + panelH + lampH / 2 + wheelR * 0.3, 0)
+    this.object3d.add(lampMesh)
+  }
+
+  updateDimension() {}
+
+  onchange(after: Record<string, unknown>, before: Record<string, unknown>) {
+    if (
+      'status' in after ||
+      'bodyColor' in after ||
+      'lampEmissive' in after ||
+      'width' in after ||
+      'height' in after ||
+      'depth' in after
+    ) {
+      this.update()
+      return
+    }
+    super.onchange(after, before)
+  }
+
+  updateAlpha() {}
+}

package/src/tugger.ts

@@ -0,0 +1,169 @@
+/*
+ * Copyright © HatioLab Inc. All rights reserved.
+ */
+import { Component, ComponentNature, RealObject, RectPath, Shape, sceneComponent } from '@hatiolab/things-scene'
+import {
+  Legendable,
+  Placeable,
+  type Alignment,
+  type Heights,
+  type LegendBinding,
+  type PlacementArchetype
+} from '@operato/scene-base'
+
+import { Tugger3D } from './tugger-3d.js'
+
+import type { AgvStatus } from './agv.js'
+
+/**
+ * Tugger — a towing AGV. Pulls trailers / carts behind it; has no cargo deck
+ * of its own. Common in mail sorting, automotive line-side delivery, hospital
+ * supply transport.
+ *
+ * Status enum is reused from {@link AgvStatus} — the tugger and the unit-load
+ * AGV share the same operating-state semantics. The structural difference
+ * (cargo deck vs hitch) is in geometry, not state.
+ */
+export type TuggerStatus = AgvStatus
+
+const BODY_LEGEND = {
+  idle: '#666',
+  moving: '#777',
+  charging: '#777',
+  error: '#c66',
+  default: '#666'
+}
+
+const LAMP_EMISSIVE_LEGEND = {
+  idle: '#222222',
+  moving: '#44ff44',
+  charging: '#ffaa00',
+  error: '#ff3333',
+  default: '#222222'
+}
+
+const NATURE: ComponentNature = {
+  mutable: false,
+  resizable: true,
+  rotatable: true,
+  properties: [
+    {
+      type: 'select',
+      label: 'status',
+      name: 'status',
+      property: {
+        options: [
+          { display: 'Idle', value: 'idle' },
+          { display: 'Moving', value: 'moving' },
+          { display: 'Charging', value: 'charging' },
+          { display: 'Error', value: 'error' }
+        ]
+      }
+    },
+    {
+      type: 'number',
+      label: 'battery',
+      name: 'battery',
+      placeholder: '0..1'
+    }
+  ],
+  help: 'scene/component/tugger'
+}
+
+const Base = Legendable(Placeable(RectPath(Shape))) as unknown as typeof Component
+
+/**
+ * Tugger has no cargo deck — just a powered tractor with a hitch. Trailers
+ * are separate scene components and are linked by data binding (a
+ * `currentTrailer` data field) rather than scene-tree containment, since
+ * trailers swap dynamically and don't share the tractor's transform.
+ *
+ * Default depth is shorter than a payload AGV — there's no operation surface
+ * to align to. ~600mm is enough for the motor housing + control panel.
+ */
+@sceneComponent('tugger')
+export default class Tugger extends Base {
+  static legends: Record<string, LegendBinding> = {
+    bodyColor: { from: 'status', legend: BODY_LEGEND },
+    lampEmissive: { from: 'status', legend: LAMP_EMISSIVE_LEGEND }
+  }
+
+  static placement: PlacementArchetype = 'floor'
+  static align: Alignment = 'bottom'
+  static defaultDepth = 600
+
+  get nature() {
+    return NATURE
+  }
+
+  get anchors() {
+    return []
+  }
+
+  /**
+   * 2D — render() draws the rounded body silhouette (auto-filled with
+   * bodyColor); postrender() adds the hitch arm + LiDAR + status lamp.
+   */
+  render(ctx: CanvasRenderingContext2D) {
+    const { width, height, left, top } = this.state
+    const radius = Math.min(width, height) * 0.18
+    ctx.beginPath()
+    ctx.roundRect(left, top + height * 0.10, width, height * 0.80, radius)
+  }
+
+  postrender(ctx: CanvasRenderingContext2D) {
+    super.postrender?.(ctx)
+
+    const { width, height, left, top } = this.state
+    const cx = left + width / 2
+    const accentColor = (this.state.lampEmissive as string) || '#44ff44'
+
+    ctx.save()
+
+    // Hitch arm + coupler at rear (top in top-down convention)
+    ctx.fillStyle = '#222233'
+    ctx.strokeStyle = '#111'
+    ctx.lineWidth = 1
+    const hitchW = width * 0.12
+    const hitchH = height * 0.10
+    ctx.fillRect(cx - hitchW / 2, top, hitchW, hitchH)
+    ctx.strokeRect(cx - hitchW / 2, top, hitchW, hitchH)
+    // Coupler ball
+    const ballR = Math.min(width, height) * 0.04
+    ctx.fillStyle = '#444455'
+    ctx.beginPath()
+    ctx.ellipse(cx, top + ballR, ballR, ballR, 0, 0, Math.PI * 2)
+    ctx.fill()
+    ctx.stroke()
+
+    // LiDAR sensor at front (bottom)
+    const lidarR = Math.min(width, height) * 0.07
+    ctx.fillStyle = '#222233'
+    ctx.beginPath()
+    ctx.ellipse(cx, top + height * 0.85, lidarR, lidarR, 0, 0, Math.PI * 2)
+    ctx.fill()
+    ctx.stroke()
+    ctx.fillStyle = accentColor
+    ctx.beginPath()
+    ctx.ellipse(cx, top + height * 0.85, lidarR * 0.4, lidarR * 0.4, 0, 0, Math.PI * 2)
+    ctx.fill()
+
+    // Status lamp on top of control panel (center)
+    const lampR = Math.min(width, height) * 0.06
+    ctx.fillStyle = accentColor
+    ctx.beginPath()
+    ctx.ellipse(cx, top + height * 0.45, lampR, lampR, 0, 0, Math.PI * 2)
+    ctx.fill()
+    ctx.stroke()
+
+    ctx.restore()
+  }
+
+  get fillStyle() {
+    return (this.state.bodyColor as string) || '#666'
+  }
+
+  buildRealObject(): RealObject | undefined {
+    return new Tugger3D(this as any)
+  }
+}