3D mini-apps

Door_FL_Open / Door_FL_Close
Door_FR_Open / Door_FR_Close
Door_RL_Open / Door_RL_Close
Door_RR_Open / Door_RR_Close
Hood_Open    / Hood_Close
Trunk_Open   / Trunk_Close
Sunroof_Open / Sunroof_Close
Window_FL_Open / Window_FL_Close
Window_FR_Open / Window_FR_Close
Window_RL_Open / Window_RL_Close
Window_RR_Open / Window_RR_Close
Headlights_On  / Headlights_Off
Indicator_Left_Blink   (loop)
Indicator_Right_Blink  (loop)
Wheel_Spin             (loop — 1 sec = 1 revolution)

// car.identity — memoised per car for the lifetime of the controller.
const identity = await client.car.identity();
// {
//   brand: 'byd',
//   modelCode: 'leopard8',
//   modelDisplay: 'BYD Leopard 8',
//   modelAssetPath: 'assets/3d/leopard8/leopard8.glb',
//   clips: ['Door_FL_Open', 'Door_FR_Open', /* … 14 more */],
//   variants: {
//     paint: ['paint_default', 'paint_lava_black', /* … */],
//     wheels: ['wheels_silver', 'wheels_black', 'wheels_bronze'],
//     glass: ['glass_clear', 'glass_smoke', 'glass_dark'],
//   },
// }

// car.asset — base64 round-trips on the wire, bytes on the SDK side.
const asset = await client.car.asset(identity.modelAssetPath!);
// {
//   path: 'assets/3d/leopard8/leopard8.glb',
//   contentType: 'model/gltf-binary',
//   size: 18_400_000,
//   bytes: Uint8Array,         // already decoded by the SDK
// }

import { AnimationAction, AnimationMixer, LoopOnce, LoopRepeat, Scene } from 'three';
import { MiniAppClient, CarSignalEvent } from 'i99dash';

export async function bindCarSignals(
  mixer: AnimationMixer,
  scene: Scene,
  client: MiniAppClient,
): Promise<() => void> {
  // One AnimationAction per clip — look them up once.
  const action = (name: string): AnimationAction | null =>
    mixer.clipAction(scene.animations.find((c) => c.name === name) ?? null!);

  const doorClips: Record<string, [AnimationAction | null, AnimationAction | null]> = {
    door_lf: [action('Door_FL_Open'), action('Door_FL_Close')],
    door_rf: [action('Door_FR_Open'), action('Door_FR_Close')],
    door_lr: [action('Door_RL_Open'), action('Door_RL_Close')],
    door_rr: [action('Door_RR_Open'), action('Door_RR_Close')],
  };
  const turnLeft = action('Indicator_Left_Blink');
  const turnRight = action('Indicator_Right_Blink');
  const wheelSpin = action('Wheel_Spin');
  [turnLeft, turnRight, wheelSpin].forEach((a) => a?.setLoop(LoopRepeat, Infinity));

  return client.car.subscribe({
    names: ['door_lf', 'door_rf', 'door_lr', 'door_rr',
            'turn_left', 'turn_right', 'speed_kmh'],
    onEvent: (e: CarSignalEvent) => {
      if (e.name in doorClips) {
        const [open, close] = doorClips[e.name];
        const next = e.value === 1 ? open : close;
        next?.reset().setLoop(LoopOnce, 1).play();
      } else if (e.name === 'turn_left') {
        if (e.value === 1) turnLeft?.reset().play();
        else turnLeft?.stop();
      } else if (e.name === 'turn_right') {
        if (e.value === 1) turnRight?.reset().play();
        else turnRight?.stop();
      } else if (e.name === 'speed_kmh' && wheelSpin) {
        // Wheel_Spin clip is 1 rev / sec by spec — set timescale
        // from km/h via wheel circumference. Real binding scales
        // by `(speed_kmh * 1000 / 3600) / wheelCircumference`.
        wheelSpin.timeScale = Math.max(0, (e.value ?? 0) / 30);
        if ((e.value ?? 0) > 0 && !wheelSpin.isRunning()) wheelSpin.play();
        if ((e.value ?? 0) === 0 && wheelSpin.isRunning()) wheelSpin.stop();
      }
    },
  });
}

import {
  AnimationMixer,
  PerspectiveCamera,
  Scene,
  WebGLRenderer,
  Clock,
  Color,
} from 'three';
import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
import { MiniAppClient } from 'i99dash';
import { bindCarSignals } from './bind-car-signals';

export async function mountCarScene(canvas: HTMLCanvasElement): Promise<() => void> {
  const client = MiniAppClient.fromWindow();
  const identity = await client.car.identity();
  if (!identity.modelAssetPath) {
    throw new Error(`car ${identity.brand}/${identity.modelCode} has no 3D model yet`);
  }

  // Load the GLB bytes through the bridge — the SDK has already
  // base64-decoded for us; hand the `Uint8Array.buffer` straight to
  // GLTFLoader.parse so we don't pay a re-encode round-trip.
  const asset = await client.car.asset(identity.modelAssetPath);
  const loader = new GLTFLoader();
  const gltf = await loader.parseAsync(
    asset.bytes.buffer.slice(
      asset.bytes.byteOffset,
      asset.bytes.byteOffset + asset.bytes.byteLength,
    ),
    /* path */ '',
  );

  // Standard Three.js scene boilerplate.
  const scene = new Scene();
  scene.background = new Color(0x07090e);
  scene.animations = gltf.animations;
  scene.add(gltf.scene);
  const camera = new PerspectiveCamera(35, canvas.clientWidth / canvas.clientHeight, 0.1, 100);
  camera.position.set(5, 1.8, 5);
  camera.lookAt(0, 0.8, 0);
  const renderer = new WebGLRenderer({ canvas, antialias: true });
  renderer.setSize(canvas.clientWidth, canvas.clientHeight, false);
  const mixer = new AnimationMixer(gltf.scene);
  const clock = new Clock();
  let rafHandle = 0;
  const tick = (): void => {
    mixer.update(clock.getDelta());
    renderer.render(scene, camera);
    rafHandle = requestAnimationFrame(tick);
  };
  rafHandle = requestAnimationFrame(tick);

  // Live-signal binding — the same subscription drives every clip
  // and the variant switches you trigger from your UI controls.
  const offSignals = await bindCarSignals(mixer, scene, client);

  // Connection banner — pause animations on disconnect so the user
  // doesn't see a frozen-but-spinning scene.
  const offConn = await client.car.connectionSubscribe((state) => {
    if (state === 'disconnected' && rafHandle) cancelAnimationFrame(rafHandle);
  });

  return () => {
    offSignals();
    offConn();
    cancelAnimationFrame(rafHandle);
    renderer.dispose();
  };
}