feedBack/plugins/highway_3d/FREECAM_BRIDGE.md

3D Highway — Free-Camera Bridge

🇬🇧 English · 🇪🇸 Español más abajo

What this modification does (EN)

This change adds a small, opt-in hook inside camUpdate() in screen.js that lets an external plugin drive the 3D Highway camera (orbit, height, zoom, tilt, pan) without forking the renderer.

The renderer reads a single shared object once per frame:

window.__h3dCamCtl = {
  enabled,     // master switch — when false the renderer auto-frames as usual
  heightMul,   // camera height multiplier
  distMul,     // dolly / zoom multiplier
  yaw,         // orbit around the look target (radians)
  pitch,       // tilt offset (highway K-units)
  panX, panY   // look-target pan (highway K-units)
};

Safety / backward compatibility

• The bridge object is read once (_freeCam) and reused for both the position and the look-at transforms.
• Every field is coerced with Number.isFinite to a safe default (heightMul/distMul → 1, everything else → 0) before use, so a malformed bridge object can never feed NaN into cam.position.set / cam.lookAt.
• When window.__h3dCamCtl is absent or enabled === false, behaviour is byte-for-byte identical to before: the if is skipped and lookAt uses the existing else path.

The shared -FOCUS_D * 0.35 look-at Z is computed once (_lookAtZ) and reused.

The plugin that uses this bridge

Camera Director — a floating, bilingual (EN/ES) control panel to author, save and share highway camera views:

➡️ https://github.com/nimuart/cameradirector_feedback

Camera Director creates and writes window.__h3dCamCtl; this renderer only reads it. That one-object contract is the entire integration surface — no other globals, no patching of the renderer's internals.

---

Qué hace esta modificación (ES)

Este cambio agrega un hook pequeño y opcional dentro de camUpdate() en screen.js que permite que un plugin externo maneje la cámara del 3D Highway (órbita, altura, zoom, inclinación, paneo) sin tener que forkear el renderer.

El renderer lee un único objeto compartido una vez por frame:

window.__h3dCamCtl = {
  enabled,     // interruptor maestro — si es false, el renderer encuadra solo
  heightMul,   // multiplicador de altura
  distMul,     // multiplicador de dolly / zoom
  yaw,         // órbita alrededor del objetivo (radianes)
  pitch,       // inclinación (unidades K del highway)
  panX, panY   // paneo del objetivo (unidades K del highway)
};

Seguridad / compatibilidad

• El objeto se lee una sola vez (_freeCam) y se reutiliza para la posición y para el look-at.
• Cada campo se valida con Number.isFinite y cae a un default seguro (heightMul/distMul → 1, el resto → 0), así un objeto mal formado nunca mete NaN en cam.position.set / cam.lookAt.
• Si window.__h3dCamCtl no existe o enabled === false, el comportamiento es idéntico al de antes.

El plugin que usa este puente

Camera Director — panel flotante y bilingüe (EN/ES) para crear, guardar y compartir vistas de cámara del highway:

➡️ https://github.com/nimuart/cameradirector_feedback

Camera Director crea y escribe window.__h3dCamCtl; este renderer solo lo lee. Ese contrato de un solo objeto es toda la superficie de integración.