@almadar/ui 5.98.0 → 5.99.0

package/dist/components/game/3d/index.cjs

@@ -1872,6 +1872,7 @@ function SideScene({
 var UNIT_BASE_MODEL_SCALE = 0.5;
 var UNIT_BASE_BILLBOARD_HEIGHT = 1.2;
 var UNIT_BASE_PRIMITIVE_RADIUS = 0.3;
+var TILE_TOP_OFFSET = 0.1;
 var EVENT_COLORS = {
   hit: "#ff5544",
   damage: "#ff5544",
@@ -1998,12 +1999,14 @@ function DefaultUnit({
             }
           ) })
         ) : model?.url ? (
-          /* GLB unit model — LOLO's `animation` field drives the named clip */
+          /* GLB unit model — LOLO's `animation` field drives the named clip;
+             `heading` (radians) faces the model along its travel direction (driving). */
           /* @__PURE__ */ jsxRuntime.jsx(
             ModelLoader,
             {
               url: model.url,
               scale: modelScale,
+              rotation: [0, unit.heading ?? 0, 0],
               animation: unit.animation ?? "idle",
               fallbackGeometry: "box",
               castShadow: true
@@ -2394,6 +2397,16 @@ var GameCanvas3D = React8.forwardRef(
       }
       return cameraTarget;
     }, [player, pixelsPerUnit, worldHeight, units, selectedUnitId, gridBounds, gridConfig, cameraTarget]);
+    const followOffset = React8.useMemo(() => {
+      if (cameraMode === "chase") {
+        const selected = units.find((u) => u.id === selectedUnitId);
+        const h = selected?.heading ?? 0;
+        const dist = 7;
+        const height = 4;
+        return [-Math.sin(h) * dist, height, -Math.cos(h) * dist];
+      }
+      return player ? [0, 2, 9] : [5, 7, 5];
+    }, [cameraMode, units, selectedUnitId, player]);
     if (externalLoading || assetsLoading && preloadAssets.length > 0) {
       return /* @__PURE__ */ jsxRuntime.jsx(
         Canvas3DLoadingState,
@@ -2446,11 +2459,11 @@ var GameCanvas3D = React8.forwardRef(
                   },
                   children: [
                     /* @__PURE__ */ jsxRuntime.jsx(CameraController, { onCameraChange: eventHandlers.handleCameraChange }),
-                    cameraMode === "follow" && /* @__PURE__ */ jsxRuntime.jsx(
+                    (cameraMode === "follow" || cameraMode === "chase") && /* @__PURE__ */ jsxRuntime.jsx(
                       FollowCamera,
                       {
                         target: followTarget,
-                        offset: player ? [0, 2, 9] : [5, 7, 5]
+                        offset: followOffset
                       }
                     ),
                     /* @__PURE__ */ jsxRuntime.jsx("ambientLight", { intensity: 0.6 }),
@@ -2536,7 +2549,7 @@ var GameCanvas3D = React8.forwardRef(
                         const position = gridToWorld2(
                           feature.x,
                           feature.z ?? feature.y ?? 0,
-                          (feature.elevation ?? 0) + 0.5
+                          (feature.elevation ?? 0) + TILE_TOP_OFFSET
                         );
                         const key = feature.id ?? `feature-${index}`;
                         if (CustomFeatureRenderer) {
@@ -2557,7 +2570,7 @@ var GameCanvas3D = React8.forwardRef(
                         const position = gridToWorld2(
                           unit.x ?? unit.position?.x ?? 0,
                           unit.z ?? unit.y ?? unit.position?.y ?? 0,
-                          (unit.elevation ?? 0) + 0.5
+                          (unit.elevation ?? 0) + TILE_TOP_OFFSET
                         );
                         return /* @__PURE__ */ jsxRuntime.jsx(LerpedGroup, { target: position, enabled: interpolateUnits, children: CustomUnitRenderer ? /* @__PURE__ */ jsxRuntime.jsx(CustomUnitRenderer, { unit, position: [0, 0, 0] }) : /* @__PURE__ */ jsxRuntime.jsx(
                           DefaultUnit,
@@ -2590,7 +2603,7 @@ var GameCanvas3D = React8.forwardRef(
                       drei.OrbitControls,
                       {
                         ref: controlsRef,
-                        enabled: cameraMode !== "follow",
+                        enabled: cameraMode !== "follow" && cameraMode !== "chase",
                         target: cameraTarget,
                         enableDamping: true,
                         dampingFactor: 0.05,

package/dist/components/game/3d/index.js

@@ -1851,6 +1851,7 @@ function SideScene({
 var UNIT_BASE_MODEL_SCALE = 0.5;
 var UNIT_BASE_BILLBOARD_HEIGHT = 1.2;
 var UNIT_BASE_PRIMITIVE_RADIUS = 0.3;
+var TILE_TOP_OFFSET = 0.1;
 var EVENT_COLORS = {
   hit: "#ff5544",
   damage: "#ff5544",
@@ -1977,12 +1978,14 @@ function DefaultUnit({
             }
           ) })
         ) : model?.url ? (
-          /* GLB unit model — LOLO's `animation` field drives the named clip */
+          /* GLB unit model — LOLO's `animation` field drives the named clip;
+             `heading` (radians) faces the model along its travel direction (driving). */
           /* @__PURE__ */ jsx(
             ModelLoader,
             {
               url: model.url,
               scale: modelScale,
+              rotation: [0, unit.heading ?? 0, 0],
               animation: unit.animation ?? "idle",
               fallbackGeometry: "box",
               castShadow: true
@@ -2373,6 +2376,16 @@ var GameCanvas3D = forwardRef(
       }
       return cameraTarget;
     }, [player, pixelsPerUnit, worldHeight, units, selectedUnitId, gridBounds, gridConfig, cameraTarget]);
+    const followOffset = useMemo(() => {
+      if (cameraMode === "chase") {
+        const selected = units.find((u) => u.id === selectedUnitId);
+        const h = selected?.heading ?? 0;
+        const dist = 7;
+        const height = 4;
+        return [-Math.sin(h) * dist, height, -Math.cos(h) * dist];
+      }
+      return player ? [0, 2, 9] : [5, 7, 5];
+    }, [cameraMode, units, selectedUnitId, player]);
     if (externalLoading || assetsLoading && preloadAssets.length > 0) {
       return /* @__PURE__ */ jsx(
         Canvas3DLoadingState,
@@ -2425,11 +2438,11 @@ var GameCanvas3D = forwardRef(
                   },
                   children: [
                     /* @__PURE__ */ jsx(CameraController, { onCameraChange: eventHandlers.handleCameraChange }),
-                    cameraMode === "follow" && /* @__PURE__ */ jsx(
+                    (cameraMode === "follow" || cameraMode === "chase") && /* @__PURE__ */ jsx(
                       FollowCamera,
                       {
                         target: followTarget,
-                        offset: player ? [0, 2, 9] : [5, 7, 5]
+                        offset: followOffset
                       }
                     ),
                     /* @__PURE__ */ jsx("ambientLight", { intensity: 0.6 }),
@@ -2515,7 +2528,7 @@ var GameCanvas3D = forwardRef(
                         const position = gridToWorld2(
                           feature.x,
                           feature.z ?? feature.y ?? 0,
-                          (feature.elevation ?? 0) + 0.5
+                          (feature.elevation ?? 0) + TILE_TOP_OFFSET
                         );
                         const key = feature.id ?? `feature-${index}`;
                         if (CustomFeatureRenderer) {
@@ -2536,7 +2549,7 @@ var GameCanvas3D = forwardRef(
                         const position = gridToWorld2(
                           unit.x ?? unit.position?.x ?? 0,
                           unit.z ?? unit.y ?? unit.position?.y ?? 0,
-                          (unit.elevation ?? 0) + 0.5
+                          (unit.elevation ?? 0) + TILE_TOP_OFFSET
                         );
                         return /* @__PURE__ */ jsx(LerpedGroup, { target: position, enabled: interpolateUnits, children: CustomUnitRenderer ? /* @__PURE__ */ jsx(CustomUnitRenderer, { unit, position: [0, 0, 0] }) : /* @__PURE__ */ jsx(
                           DefaultUnit,
@@ -2569,7 +2582,7 @@ var GameCanvas3D = forwardRef(
                       OrbitControls,
                       {
                         ref: controlsRef,
-                        enabled: cameraMode !== "follow",
+                        enabled: cameraMode !== "follow" && cameraMode !== "chase",
                         target: cameraTarget,
                         enableDamping: true,
                         dampingFactor: 0.05,

package/dist/components/game/3d/molecules/GameCanvas3D.d.ts

@@ -31,8 +31,10 @@ export interface GameEvent {
     y?: number;
     message?: string;
 }
-/** Camera mode for 3D view. `follow` tracks the side-view player (or the selected unit). */
-export type CameraMode = 'isometric' | 'perspective' | 'top-down' | 'follow';
+/** Camera mode for 3D view.
+ *  - `follow` tracks the side-view player (or the selected unit) from a fixed offset.
+ *  - `chase` sits behind + above the followed unit relative to its `heading` (driving). */
+export type CameraMode = 'isometric' | 'perspective' | 'top-down' | 'follow' | 'chase';
 /** Per-role model manifest — the 3D analogue of Canvas2D's assetManifest (values are GLB Assets). */
 export interface GameCanvas3DAssetManifest {
     terrains?: Record<string, Asset>;

package/dist/components/game/shared/isometricTypes.d.ts

@@ -99,6 +99,9 @@ export type IsometricUnit = {
     animation?: AnimationName;
     /** Frame index within the animation — driven by the LOLO state machine; renderer defaults to 0 */
     frame?: number;
+    /** Y-axis heading in radians (3D) — travel/facing direction. Orients the unit model and
+     *  drives the `chase` camera (behind + above, looking along heading). Driving boards set this. */
+    heading?: number;
 };
 /** A map feature (resource, building, portal, etc.) */
 export type IsometricFeature = {
@@ -120,6 +123,8 @@ export type IsometricFeature = {
     color?: string;
     /** Elevation offset for 3D rendering */
     elevation?: number;
+    /** Y-axis rotation in radians (3D) — orients directional features (arches, signs, docks). */
+    rotation?: number;
 };
 /** Camera state for pan/zoom */
 export interface CameraState {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@almadar/ui",
-  "version": "5.98.0",
+  "version": "5.99.0",
   "description": "React UI components, hooks, and providers for Almadar",
   "type": "module",
   "sideEffects": [