mirror of
https://github.com/got-feedBack/feedBack.git
synced 2026-08-11 03:09:57 +00:00
87 lines
3.3 KiB
Markdown
87 lines
3.3 KiB
Markdown
# 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`](./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:
|
|
|
|
```js
|
|
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`](./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:
|
|
|
|
```js
|
|
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.
|