docs: refresh hand-tracking notes and drop context-lost investigation
This commit is contained in:
Tom Boullay
@@ -10,17 +10,23 @@ It is now also available to the production repair flow when a mission reaches a
|
||||
|
||||
## Runtime Flow
|
||||
|
||||
1. The browser captures webcam frames in `src/hooks/handTracking/useRemoteHandTracking.ts`.
|
||||
2. Frames are sent to the local Python backend over WebSocket.
|
||||
3. The backend runs MediaPipe hand landmark detection.
|
||||
4. The backend returns hand data including landmarks, handedness, score, center point, and `isFist`.
|
||||
5. React stores the latest snapshot in the hand tracking provider.
|
||||
6. `GrabbableObject` reads that snapshot each frame and uses fist state plus raycasting to grab objects.
|
||||
7. `HandTrackingGlove` reads the same snapshot and places the rigged `gant_l` and `gant_r` models on the detected hands when hand tracking is active.
|
||||
The frontend can run hand tracking with two interchangeable sources, selected from the debug source controller:
|
||||
|
||||
- **Browser JS** (`src/hooks/handTracking/useBrowserHandTracking.ts`) runs MediaPipe `hand_landmarker.task` directly in the browser via `@mediapipe/tasks-vision`. Default for debug.
|
||||
- **Backend** (`src/hooks/handTracking/useRemoteHandTracking.ts`) sends webcam frames as JPEG over WebSocket to a local Python process that runs MediaPipe and returns landmarks.
|
||||
|
||||
Both sources funnel into the same `HandTrackingContext` so all consumers see one shared snapshot:
|
||||
|
||||
1. The active source captures or receives landmarks.
|
||||
2. The hook applies an EMA smoothing pass on the landmarks before publishing the snapshot.
|
||||
3. `HandTrackingProvider` exposes that snapshot through React context.
|
||||
4. `GrabbableObject` reads the snapshot each frame and uses the fist state plus raycasting to grab objects.
|
||||
5. `HandTrackingGlove` reads the same snapshot and places a rigged glove on each detected hand.
|
||||
6. `HandTrackingVisualizer` paints an SVG wireframe overlay on top of the canvas.
|
||||
|
||||
## Activation Rules
|
||||
|
||||
Hand tracking is intentionally gated so the webcam and backend are not used all the time.
|
||||
Hand tracking is gated so the webcam and runtime are only spun up when actually needed.
|
||||
|
||||
The debug activation conditions are:
|
||||
|
||||
@@ -28,16 +34,26 @@ The debug activation conditions are:
|
||||
- scene mode is `physics`
|
||||
- the player is near an interaction, is holding an object, or is hand-holding an object
|
||||
|
||||
This keeps hand tracking active while the player is inside an interaction zone, even if the camera is not aimed directly at the object.
|
||||
|
||||
The production repair activation conditions are:
|
||||
|
||||
- active `mainState` is `ebike`, `pylon`, or `farm`
|
||||
- the active mission step is `inspected`, `repairing`, `reassembling`, or `done`
|
||||
|
||||
This keeps the webcam off during `waiting`, `fragmented`, and `scanning`, then enables hand input only when the repair flow is expected to use hands.
|
||||
This keeps the webcam off during `waiting`, `fragmented`, and `scanning`.
|
||||
|
||||
In the current production repair flow, `inspected` uses a two-fists hold gesture to advance to `fragmented`. The hold must last one second and is independent from local object interaction distance once the mission is in the correct state. Keyboard input for the same transition is handled separately by the repair case trigger, so pressing `E` requires the case to be focused through the shared interaction system.
|
||||
### Linger
|
||||
|
||||
Once activation turns off (player walks back out of a trigger zone, or a mission step transitions away), the runtime stays alive for `HAND_TRACKING_LINGER_MS` (2000 ms) before being torn down. This gives MediaPipe enough time to finish initializing the webcam and load the model on a fresh entry — without the linger, a quick walk-through of a trigger zone never produces a detected hand.
|
||||
|
||||
## Provider Stability
|
||||
|
||||
`HandTrackingProvider` always renders the same JSX root (`HandTrackingRuntime`) and exposes `enabled` as a prop. Returning two different element types (`<HandTrackingContext value=IDLE>` vs `<ActiveHandTrackingProvider>`) used to be the historical shape and was the root cause of WebGL context loss: every `enabled` toggle forced React to remount the entire subtree, including the `<Canvas>`, which destroyed the WebGL renderer.
|
||||
|
||||
The two source hooks are therefore mounted in permanence with an `enabled` flag that they early-return on. No webcam or MediaPipe resources are created while `enabled` is false.
|
||||
|
||||
## StrictMode Resilience
|
||||
|
||||
In development, `<StrictMode>` mounts → unmounts → remounts each effect to surface non-idempotent code. The two source hooks delay their actual `start()` call by `HAND_TRACKING_RUNTIME_START_DELAY_MS` (80 ms) and clear the timer on cleanup, so a StrictMode double-mount or a rapid `nearby` flicker never reaches `getUserMedia` twice.
|
||||
|
||||
## Backend
|
||||
|
||||
@@ -52,7 +68,27 @@ The Python process uses MediaPipe and the local model file:
|
||||
backend/hand_landmarker.task
|
||||
```
|
||||
|
||||
The backend sends normalized hand coordinates and landmarks. The frontend treats the values as screen-space inputs, then maps them into world space with the active Three.js camera.
|
||||
The frontend sends JPEG frames at `HAND_TRACKING_FRAME_WIDTH × HAND_TRACKING_FRAME_HEIGHT` (320×240) to keep WebSocket bandwidth low. The backend sends normalized hand coordinates and landmarks.
|
||||
|
||||
## Browser MediaPipe
|
||||
|
||||
The browser path uses `hand_landmarker.task` (float16) downloaded from Google's MediaPipe model storage. The requested webcam resolution is **640×480** (`HAND_TRACKING_BROWSER_CAMERA_WIDTH/HEIGHT`), independent from the backend's 320×240. The float16 model is more sensitive than the backend Python model and needs the higher-resolution frame to detect hands reliably.
|
||||
|
||||
The MediaPipe delegate is currently `"GPU"`. CPU works too but is significantly slower; on a loaded scene the inference drops to ~5fps and the user feels noticeable lag during grab. MediaPipe creates its own WebGL context separate from Three.js, so there is no direct contention.
|
||||
|
||||
A singleton instance of `HandLandmarker` is cached in `src/lib/handTracking/browserHandTracking.ts`. `releaseBrowserHandLandmarker()` is called on cleanup and on WebGL context lost.
|
||||
|
||||
## Smoothing
|
||||
|
||||
MediaPipe at ~10 fps produces noticeable landmark jitter that, when fed raw into the scene, makes both the glove rig and any grabbed object tremble.
|
||||
|
||||
A simple exponential moving average is applied to every landmark before the snapshot is published:
|
||||
|
||||
```ts
|
||||
smoothed.x = previous.x * (1 - factor) + next.x * factor;
|
||||
```
|
||||
|
||||
The factor is `HAND_TRACKING_LANDMARK_SMOOTHING` (0.4). Hands are matched across frames by `handedness` so left/right don't bleed into each other.
|
||||
|
||||
## Frontend Data Shape
|
||||
|
||||
@@ -106,24 +142,36 @@ This is less expressive than true depth-aware hand movement, but it is more stab
|
||||
The current debug UI includes:
|
||||
|
||||
- `HandTrackingDebugPanel` inside `DebugOverlayLayout` for status, usage, loaded glove model, server state, hand count, and fist state
|
||||
- `HandTrackingVisualizer` for the SVG landmark wireframe fallback
|
||||
- `HandTrackingGlove` for the left-hand `gant_l` and right-hand `gant_r` models in the R3F scene
|
||||
- `HandTrackingVisualizer` for the SVG landmark overlay
|
||||
- `HandTrackingFallback` for the last-resort hand silhouette overlay
|
||||
- `HandTrackingGlove` for the per-hand rigged glove models in the R3F scene
|
||||
- `r3f-perf` for render performance
|
||||
- `lil-gui` for scene, camera, lighting, interaction, and grab controls
|
||||
|
||||
The hand tracking debug panel is a compact HTML grid outside the canvas. `Model loaded` displays the successfully loaded glove models. The SVG hand wireframe is only a fallback while models are loading or if a glove model fails to load.
|
||||
The SVG visualizer uses a "blueish hand" style: white connection lines between landmarks, cyan circles with a dark blue outline. The outline gets thicker when the hand is detected as a fist, so the user gets a visual confirmation of the grab gesture without having to look at the debug panel.
|
||||
|
||||
The fallback overlay (`HandTrackingFallback`) draws a simple open-hand or fist silhouette positioned on the detected wrist landmark. It only renders for a hand whose matching glove is in the `"error"` state in `useHandTrackingGloveStatus`. This guarantees the user always sees something on their hand even when the 3D glove model fails to load.
|
||||
|
||||
## Glove Models
|
||||
|
||||
The current glove MVP uses `public/models/gant_l/model.gltf` and `public/models/gant_r/model.gltf`, which contain GLTF skins and armatures. Each model is positioned, oriented, and scaled from palm landmarks, then each finger bone chain is rotated toward the matching MediaPipe landmark chain.
|
||||
`HandTrackingGlove` loads `public/models/gant_l/model.gltf` for both hands. The right hand applies `scale.x = -1` at the group level to mirror the mesh, so the thumb ends up on the correct side. Both hands therefore share the same rig and the same material.
|
||||
|
||||
The glove models are intentionally smaller than the raw SVG overlay so they do not dominate the camera view.
|
||||
The historical `public/models/gant_r/model.gltf` is kept as legacy but is not loaded by the frontend — its GLB embeds three skeletons (`Hand_l`, `Hand_l_pad`, `Hand_r`) plus a `galet` mesh, which made the finger rig unreliable.
|
||||
|
||||
The `gant_l` material is set to `alphaMode: OPAQUE` with `doubleSided: true`. The opaque mode prevents transparency sorting issues that made folded fingers disappear behind the palm; the double-sided flag covers the back faces revealed by the mirror scale on the right hand.
|
||||
|
||||
Two additional glove variants exist on disk:
|
||||
|
||||
- `public/models/gant_l_pad/model.gltf`
|
||||
- `public/models/gant_r_pad/model.gltf`
|
||||
|
||||
They are intended for future swap-by-state usage but are **not yet rigged**. They cannot be animated by MediaPipe landmarks in their current form — re-exporting them from Blender with the same armature structure as `gant_l` is a prerequisite.
|
||||
|
||||
## Known Limitations
|
||||
|
||||
- Production usage is currently limited to repair mission steps that explicitly need hands.
|
||||
- MediaPipe depth is relative and currently not used for stable object depth control.
|
||||
- The virtual hit zone is an approximation based on multiple raycasts, not a real 3D collider.
|
||||
- There is no smoothing layer for hand position or depth yet.
|
||||
- The SVG hand visualization is a fallback, not the primary display when glove models load correctly.
|
||||
- The right glove is a mirrored copy of `gant_l` rather than its own mesh; in the future a dedicated right-hand model would give a better visual.
|
||||
- The `_pad` glove variants are not rigged yet, so swap-by-state (normal ↔ pad) is not wired in.
|
||||
- Finger bone animation is an approximate landmark-to-bone mapping; it still needs calibration for per-model twist, offsets, and smoothing.
|
||||
|
||||
@@ -1,367 +0,0 @@
|
||||
# WebGL Context Lost - Investigation
|
||||
|
||||
## Résumé court
|
||||
|
||||
Le projet subit des pertes de contexte WebGL pendant les phases où le jeu active
|
||||
ou prépare le hand tracking, les interactions physiques ou le repair game.
|
||||
|
||||
Le symptôme visible côté console est :
|
||||
|
||||
```txt
|
||||
THREE.WebGLRenderer: Context Lost.
|
||||
[ERROR] [WebGL] Context lost - attempting auto-restore
|
||||
THREE.WebGLRenderer: Context Restored.
|
||||
```
|
||||
|
||||
Le problème est bloquant parce que le hand tracking et le repair game sont au
|
||||
coeur de l'expérience. Quand le contexte WebGL saute, la scène Three.js peut se
|
||||
remonter, le joueur peut revenir au spawn, le pointer lock peut être perdu, et
|
||||
les tests de gameplay deviennent instables.
|
||||
|
||||
## Ce qui fonctionne aujourd'hui
|
||||
|
||||
La page principale monte un `<Canvas>` React Three Fiber dans
|
||||
`src/pages/page.tsx`.
|
||||
|
||||
`src/world/World.tsx` compose ensuite :
|
||||
|
||||
- la scène de jeu ou la scène de test physique ;
|
||||
- le player ;
|
||||
- les systèmes visuels de monde ;
|
||||
- les gants de hand tracking ;
|
||||
- les systèmes de debug.
|
||||
|
||||
Le hand tracking est centralisé dans
|
||||
`src/providers/gameplay/HandTrackingProvider.tsx`.
|
||||
|
||||
Il peut utiliser deux sources :
|
||||
|
||||
- `browser` : MediaPipe JS dans le navigateur ;
|
||||
- `backend` : backend Python local via WebSocket.
|
||||
|
||||
L'activation est déclenchée par :
|
||||
|
||||
- certaines étapes du repair game ;
|
||||
- les zones d'interaction qui demandent explicitement les mains ;
|
||||
- la scène Physique en debug, selon les objets présents.
|
||||
|
||||
## Problème observé
|
||||
|
||||
Les context lost arrivent dans plusieurs situations :
|
||||
|
||||
- entrée dans une zone d'interaction ;
|
||||
- lancement du hand tracking ;
|
||||
- lancement d'un repair game ;
|
||||
- scène Physique avec `TestMap`, `Physics`, `AnimatedModel`, waypoints GPS et
|
||||
objets interactifs ;
|
||||
- source browser JS ;
|
||||
- source backend.
|
||||
|
||||
Le fait que le crash existe avec les deux sources indique que le problème n'est
|
||||
probablement pas limité au backend Python ni à MediaPipe JS seul. Le hand
|
||||
tracking semble être un déclencheur fort, mais il arrive au moment où plusieurs
|
||||
ressources GPU et systèmes runtime se réveillent ensemble.
|
||||
|
||||
## Pourquoi c'est bloquant
|
||||
|
||||
Ce bug bloque la feature principale du projet :
|
||||
|
||||
- le repair game dépend du hand tracking pour valider certaines actions ;
|
||||
- les interactions main sont nécessaires pour tester les objets grabbables ;
|
||||
- un context lost casse la continuité du gameplay ;
|
||||
- le joueur peut être replacé au spawn après reconstruction ;
|
||||
- le pointer lock peut être perdu ;
|
||||
- les logs deviennent difficiles à lire parce que le jeu tente de restaurer la
|
||||
scène en boucle ;
|
||||
- le comportement n'est pas fiable pour une démo ou un déploiement.
|
||||
|
||||
Tant que ce problème n'est pas stable, on ne peut pas valider correctement :
|
||||
|
||||
- la mission e-bike ;
|
||||
- la mission pylône ;
|
||||
- la mission ferme ;
|
||||
- les interactions main ;
|
||||
- le switch browser/backend ;
|
||||
- le comportement en build de production.
|
||||
|
||||
## Hypothèses principales
|
||||
|
||||
### 1. Pression GPU au lancement du hand tracking
|
||||
|
||||
MediaPipe browser peut créer ses propres ressources GPU. Si Three.js charge
|
||||
déjà beaucoup de géométries, textures, ombres et modèles, l'ajout du hand
|
||||
tracking peut faire passer le navigateur au-dessus d'une limite GPU.
|
||||
|
||||
Le stash contient une tentative de mitigation en forçant MediaPipe browser et le
|
||||
backend à utiliser le CPU.
|
||||
|
||||
### 2. Activation trop brusque du runtime mains
|
||||
|
||||
Les logs montrent des transitions rapides :
|
||||
|
||||
```txt
|
||||
Browser JS runtime starting
|
||||
Runtime source selected
|
||||
Runtime snapshot changed
|
||||
Browser JS runtime stopped
|
||||
Browser JS runtime starting
|
||||
```
|
||||
|
||||
Ce type de start/stop rapide peut provoquer :
|
||||
|
||||
- création webcam ;
|
||||
- création MediaPipe ;
|
||||
- montage des gants ;
|
||||
- update du state React ;
|
||||
- re-render du monde ;
|
||||
- stress GPU au même moment.
|
||||
|
||||
### 3. Les gants 3D sont montés trop tôt
|
||||
|
||||
Si les gants de hand tracking sont montés avant d'avoir de vraies mains
|
||||
détectées, le jeu charge et prépare des modèles GPU sans utilité immédiate.
|
||||
|
||||
Le stash contient une tentative pour ne rendre les gants que lorsqu'une main
|
||||
existe réellement dans le snapshot.
|
||||
|
||||
### 4. Re-upload textures / GLTF trop agressif
|
||||
|
||||
`src/utils/three/optimizeGLTFScene.ts` modifie des textures GLTF. Si cette
|
||||
optimisation force trop souvent `needsUpdate`, mipmaps ou anisotropy, le
|
||||
navigateur peut recharger beaucoup de textures vers le GPU.
|
||||
|
||||
Le stash limite cette pression en évitant de forcer les mipmaps et en abaissant
|
||||
l'anisotropy.
|
||||
|
||||
### 5. Permission caméra au mauvais moment
|
||||
|
||||
Demander la caméra au moment exact où le joueur entre dans une interaction ou
|
||||
lance le repair game ajoute un gros événement runtime au pire moment.
|
||||
|
||||
Le stash contient une tentative de warmup caméra pour obtenir la permission plus
|
||||
tôt et réutiliser le stream au moment où le hand tracking devient nécessaire.
|
||||
|
||||
### 6. La scène Physique ajoute du bruit
|
||||
|
||||
La scène Physique est une scène de test volontairement riche :
|
||||
|
||||
- `Physics` Rapier ;
|
||||
- `GrabbableObject` ;
|
||||
- `TriggerObject` ;
|
||||
- `RepairGame` ;
|
||||
- `AnimatedModel` ;
|
||||
- GPS preview ;
|
||||
- waypoints verts ;
|
||||
- player ;
|
||||
- debug overlay.
|
||||
|
||||
Cette richesse est normale pour une scène de test, mais elle complique
|
||||
l'investigation parce qu'elle active beaucoup de systèmes à la fois.
|
||||
|
||||
## Fichiers modifiés dans le stash
|
||||
|
||||
Le stash `stash@{0}` contient 28 fichiers modifiés, environ `+530 / -152`.
|
||||
Il ne contient pas de fichiers untracked.
|
||||
|
||||
| Fichier | Rôle dans l'investigation |
|
||||
| --------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
|
||||
| `README.md` | Note sur les commandes backend depuis la racine du repo. |
|
||||
| `backend/README.md` | Documentation plus claire pour lancer le backend et réparer un `.venv` cassé. |
|
||||
| `backend/hand_tracker.py` | Force le backend MediaPipe en CPU. |
|
||||
| `docs/user/main-feature.md` | Ajustements de documentation utilisateur. |
|
||||
| `public/sounds/dialogue/subtitles/fr/electricienne.srt` | Ajustements de sous-titres, pas central pour le context lost. |
|
||||
| `public/sounds/dialogue/subtitles/fr/narrateur.srt` | Ajustements de sous-titres, pas central pour le context lost. |
|
||||
| `src/components/debug/DebugPlayerModel.tsx` | Ajustements de modèle debug player. |
|
||||
| `src/components/three/handTracking/HandTrackingGlove.tsx` | Retire le preload automatique des gants pour réduire la pression GPU. |
|
||||
| `src/components/three/interaction/GrabbableObject.tsx` | Marque les grabbables qui nécessitent vraiment le hand tracking. |
|
||||
| `src/components/three/interaction/InteractableObject.tsx` | Ajoute le flag `handTracking` aux interactables. |
|
||||
| `src/data/debug/testSceneConfig.ts` | Stabilise la scène Physique : sol, GPS, hauteur des waypoints. |
|
||||
| `src/data/handTrackingConfig.ts` | Ajoute délai d'activation, TTL warmup caméra, delegate CPU browser. |
|
||||
| `src/data/player/playerConfig.ts` | Corrige le spawn Physique avec `PLAYER_EYE_HEIGHT`. |
|
||||
| `src/hooks/debug/useSceneMode.ts` | Force `game` hors debug actif pour éviter des scènes debug en prod. |
|
||||
| `src/hooks/handTracking/useBothFistsHold.ts` | Sort le hold des deux poings de `useFrame` R3F vers `requestAnimationFrame`. |
|
||||
| `src/hooks/handTracking/useBrowserHandTracking.ts` | Encadre `detectForVideo`, release MediaPipe en cleanup, gère les erreurs. |
|
||||
| `src/hooks/three/useTerrainHeight.ts` | Ajustements terrain, liés au snap/player. |
|
||||
| `src/lib/handTracking/browserHandTracking.ts` | Force delegate CPU, garde une instance MediaPipe, ajoute `releaseBrowserHandLandmarker`. |
|
||||
| `src/lib/handTracking/handTrackingSession.ts` | Ajoute warmup caméra, cache stream, timeout et consommation du stream préparé. |
|
||||
| `src/managers/InteractionManager.ts` | Ajoute `handTrackingNearby` pour ne pas activer les mains sur toute interaction. |
|
||||
| `src/pages/page.tsx` | Gestion WebGL context lost/restored, DPR fixe, antialias off, release MediaPipe au crash. |
|
||||
| `src/providers/gameplay/HandTrackingProvider.tsx` | Ajoute activation différée, snapshot queued, warmup runtime. |
|
||||
| `src/types/interaction/interaction.ts` | Ajoute `handTracking` et `handTrackingNearby` aux types interaction. |
|
||||
| `src/utils/debug/Debug.ts` | Synchronise l'affichage du controller hand tracking source. |
|
||||
| `src/utils/three/optimizeGLTFScene.ts` | Réduit la pression GPU des textures GLTF. |
|
||||
| `src/world/World.tsx` | Ne rend les gants que si une main correspondante est détectée. |
|
||||
| `src/world/debug/TestMap.tsx` | Nettoie les logs, stabilise waypoints/GPS/scène Physique. |
|
||||
| `src/world/player/PlayerCamera.tsx` | Ajustements pointer lock/canvas ciblé. |
|
||||
|
||||
## Fichiers actuellement modifiés dans le worktree
|
||||
|
||||
Etat observé au moment de cette note :
|
||||
|
||||
| Fichier | Statut |
|
||||
| --------------------------------------------------------- | --------------------------------------------------------- |
|
||||
| `public/models/talkie/*` | Beaucoup d'anciennes textures/fichiers `.gltf` supprimés. |
|
||||
| `public/models/talkie/model.glb` | Nouveau fichier non suivi. |
|
||||
| `src/components/three/handTracking/HandTrackingGlove.tsx` | Modifié. |
|
||||
| `src/data/debug/testSceneConfig.ts` | Modifié. |
|
||||
| `src/data/gameplay/repairMissions.ts` | Modifié. |
|
||||
| `src/data/handTrackingConfig.ts` | Modifié. |
|
||||
| `src/data/player/playerConfig.ts` | Modifié. |
|
||||
| `src/data/world/mapLodConfig.ts` | Modifié. |
|
||||
| `src/hooks/handTracking/useBrowserHandTracking.ts` | Modifié. |
|
||||
| `src/hooks/handTracking/useRemoteHandTracking.ts` | Modifié. |
|
||||
| `src/lib/handTracking/browserHandTracking.ts` | Modifié. |
|
||||
| `src/lib/handTracking/handTrackingSession.ts` | Modifié. |
|
||||
| `src/pages/page.tsx` | Modifié. |
|
||||
| `src/providers/gameplay/HandTrackingProvider.tsx` | Modifié. |
|
||||
| `src/utils/debug/Debug.ts` | Modifié. |
|
||||
| `src/utils/three/optimizeGLTFScene.ts` | Modifié. |
|
||||
| `src/world/World.tsx` | Modifié. |
|
||||
| `src/world/debug/TestMap.tsx` | Modifié. |
|
||||
| `src/world/player/Player.tsx` | Modifié. |
|
||||
| `src/world/player/PlayerCamera.tsx` | Modifié. |
|
||||
| `src/world/player/PlayerController.tsx` | Modifié. |
|
||||
| `src/components/ui/RuntimeLoadingIndicator.tsx` | Nouveau fichier non suivi. |
|
||||
| `src/hooks/handTracking/useHandTrackingRuntimeWarmup.ts` | Nouveau fichier non suivi. |
|
||||
| `src/world/player/playerRuntimeSnapshot.ts` | Nouveau fichier non suivi. |
|
||||
|
||||
Attention : les fichiers supprimés/nouveaux du talkie semblent être un sujet
|
||||
séparé du context lost. Il faut les garder séparés dans les commits.
|
||||
|
||||
## Fichiers directement impactés par le bug
|
||||
|
||||
### Canvas et WebGL
|
||||
|
||||
- `src/pages/page.tsx`
|
||||
- `src/world/World.tsx`
|
||||
- `src/utils/three/optimizeGLTFScene.ts`
|
||||
|
||||
Ces fichiers influencent directement la charge GPU, la configuration du canvas,
|
||||
les ressources GLTF et le comportement au context lost/restored.
|
||||
|
||||
### Hand tracking
|
||||
|
||||
- `src/providers/gameplay/HandTrackingProvider.tsx`
|
||||
- `src/hooks/handTracking/useBrowserHandTracking.ts`
|
||||
- `src/hooks/handTracking/useRemoteHandTracking.ts`
|
||||
- `src/hooks/handTracking/useBothFistsHold.ts`
|
||||
- `src/hooks/handTracking/useHandTrackingRuntimeWarmup.ts`
|
||||
- `src/lib/handTracking/browserHandTracking.ts`
|
||||
- `src/lib/handTracking/handTrackingSession.ts`
|
||||
- `src/data/handTrackingConfig.ts`
|
||||
- `src/components/three/handTracking/HandTrackingGlove.tsx`
|
||||
- `backend/hand_tracker.py`
|
||||
|
||||
Ces fichiers contrôlent le déclenchement, la source, la caméra, MediaPipe, le
|
||||
backend et le rendu visuel des mains.
|
||||
|
||||
### Interactions et repair game
|
||||
|
||||
- `src/components/three/interaction/GrabbableObject.tsx`
|
||||
- `src/components/three/interaction/InteractableObject.tsx`
|
||||
- `src/managers/InteractionManager.ts`
|
||||
- `src/types/interaction/interaction.ts`
|
||||
- `src/components/three/gameplay/RepairGame.tsx`
|
||||
- `src/hooks/gameplay/useRepairMissionStep.ts`
|
||||
- `src/hooks/gameplay/useRepairMovementLocked.ts`
|
||||
|
||||
Ces fichiers sont impactés parce que l'entrée dans une zone ou une étape repair
|
||||
peut déclencher le hand tracking.
|
||||
|
||||
### Player et restauration après crash
|
||||
|
||||
- `src/world/player/Player.tsx`
|
||||
- `src/world/player/PlayerCamera.tsx`
|
||||
- `src/world/player/PlayerController.tsx`
|
||||
- `src/world/player/playerRuntimeSnapshot.ts`
|
||||
- `src/data/player/playerConfig.ts`
|
||||
|
||||
Ces fichiers influencent le spawn, la caméra, le pointer lock, et la possibilité
|
||||
de récupérer la dernière position après un context lost.
|
||||
|
||||
### Scène Physique / debug
|
||||
|
||||
- `src/world/debug/TestMap.tsx`
|
||||
- `src/data/debug/testSceneConfig.ts`
|
||||
- `src/components/debug/DebugPlayerModel.tsx`
|
||||
- `src/hooks/debug/useSceneMode.ts`
|
||||
- `src/utils/debug/Debug.ts`
|
||||
|
||||
Ces fichiers ne sont pas forcément la cause racine, mais ils créent une scène de
|
||||
stress utile pour reproduire le bug.
|
||||
|
||||
## Ce que le stash essayait de corriger
|
||||
|
||||
Le stash essaye de réduire le risque de context lost avec plusieurs leviers :
|
||||
|
||||
1. passer MediaPipe browser/backend en CPU ;
|
||||
2. libérer MediaPipe quand le runtime s'arrête ou quand WebGL saute ;
|
||||
3. éviter de monter les gants sans mains détectées ;
|
||||
4. retarder l'activation du hand tracking pour éviter les start/stop violents ;
|
||||
5. demander la caméra plus tôt et réutiliser le stream ;
|
||||
6. réduire la charge GPU du canvas avec DPR fixe et antialias off ;
|
||||
7. limiter les re-uploads de textures GLTF ;
|
||||
8. distinguer les interactions qui demandent vraiment le hand tracking ;
|
||||
9. restaurer WebGL avec une limite pour éviter les boucles infinies ;
|
||||
10. conserver la position du joueur après restauration.
|
||||
|
||||
## Ce qui reste à prouver
|
||||
|
||||
Il faut encore isoler le déclencheur exact :
|
||||
|
||||
- crash avec hand tracking désactivé complètement ;
|
||||
- crash avec source browser JS seulement ;
|
||||
- crash avec source backend seulement ;
|
||||
- crash avec gants 3D désactivés ;
|
||||
- crash avec MediaPipe CPU ;
|
||||
- crash avec `AnimatedModel` de TestMap désactivé ;
|
||||
- crash avec GPS preview/waypoints désactivés ;
|
||||
- crash avec shadows/antialias/DPR réduits ;
|
||||
- crash en scène game réelle, pas seulement scène Physique.
|
||||
|
||||
## Plan d'investigation recommandé
|
||||
|
||||
1. Stabiliser le worktree et ne pas mélanger assets talkie, LOD, docs backend et
|
||||
context lost dans le même commit.
|
||||
2. Garder le stash tant que le fix final n'est pas validé.
|
||||
3. Créer un commit ou patch isolé pour les logs context lost seulement.
|
||||
4. Ajouter un switch debug qui permet de couper séparément :
|
||||
- hand tracking runtime ;
|
||||
- gants 3D ;
|
||||
- MediaPipe browser ;
|
||||
- backend ;
|
||||
- GPS preview ;
|
||||
- AnimatedModel de TestMap.
|
||||
5. Reproduire le bug avec une matrice claire.
|
||||
6. Garder les changements qui diminuent réellement les context lost.
|
||||
7. Supprimer les logs temporaires une fois le diagnostic terminé.
|
||||
|
||||
## Recommandation Git
|
||||
|
||||
Ne pas supprimer le stash maintenant.
|
||||
|
||||
Il contient du travail réel sur le context lost. Même s'il n'est pas parfait, il
|
||||
sert de trace d'investigation et contient des morceaux utiles.
|
||||
|
||||
Avant de le supprimer, sauvegarder le patch :
|
||||
|
||||
```bash
|
||||
git stash show -p stash@{0} > context-lost-stash.patch
|
||||
```
|
||||
|
||||
Ensuite seulement, si tout a été repris dans des commits propres :
|
||||
|
||||
```bash
|
||||
git stash drop stash@{0}
|
||||
```
|
||||
|
||||
## Commits logiques proposés
|
||||
|
||||
Séparer en plusieurs commits pour éviter un gros commit illisible :
|
||||
|
||||
1. `docs: document webgl context lost investigation`
|
||||
2. `fix: reduce handtracking gpu pressure`
|
||||
3. `fix: delay handtracking activation`
|
||||
4. `fix: preserve player state after webgl restore`
|
||||
5. `fix: stabilize physics debug scene`
|
||||
6. `docs: clarify backend handtracking setup`
|
||||
@@ -3,10 +3,12 @@ import {
|
||||
HAND_TRACKING_FRAME_HEIGHT,
|
||||
HAND_TRACKING_FRAME_WIDTH,
|
||||
HAND_TRACKING_JPEG_QUALITY,
|
||||
HAND_TRACKING_LANDMARK_SMOOTHING,
|
||||
HAND_TRACKING_RESPONSE_TIMEOUT_MS,
|
||||
HAND_TRACKING_RUNTIME_START_DELAY_MS,
|
||||
HAND_TRACKING_TARGET_FPS,
|
||||
} from "@/data/handTrackingConfig";
|
||||
import { smoothHands } from "@/lib/handTracking/handSmoothing";
|
||||
import { getHandTrackingWsUrl } from "@/utils/handTracking/handTrackingEndpoint";
|
||||
import {
|
||||
INITIAL_HAND_TRACKING_SNAPSHOT,
|
||||
@@ -95,6 +97,7 @@ export function useRemoteHandTracking({
|
||||
const sendIntervalRef = useRef<number | null>(null);
|
||||
const responseTimeoutRef = useRef<number | null>(null);
|
||||
const waitingForResponseRef = useRef(false);
|
||||
const previousHandsRef = useRef<HandTrackingHand[]>([]);
|
||||
|
||||
useEffect(() => {
|
||||
if (!enabled) {
|
||||
@@ -128,6 +131,7 @@ export function useRemoteHandTracking({
|
||||
streamRef.current = null;
|
||||
videoRef.current = null;
|
||||
canvasRef.current = null;
|
||||
previousHandsRef.current = [];
|
||||
};
|
||||
|
||||
const markResponseReceived = (): void => {
|
||||
@@ -259,10 +263,16 @@ export function useRemoteHandTracking({
|
||||
}
|
||||
|
||||
if (data.type === "hands") {
|
||||
const smoothedHands = smoothHands(
|
||||
previousHandsRef.current,
|
||||
data.hands,
|
||||
HAND_TRACKING_LANDMARK_SMOOTHING,
|
||||
);
|
||||
previousHandsRef.current = smoothedHands;
|
||||
setSnapshot((current) => ({
|
||||
...current,
|
||||
hands: data.hands,
|
||||
usageStatus: data.hands.some((hand) => hand.isFist)
|
||||
hands: smoothedHands,
|
||||
usageStatus: smoothedHands.some((hand) => hand.isFist)
|
||||
? "active"
|
||||
: "available",
|
||||
serverStatus: null,
|
||||
|
||||
@@ -1789,6 +1789,26 @@ canvas {
|
||||
filter: drop-shadow(0 0 8px rgba(56, 189, 248, 0.55));
|
||||
}
|
||||
|
||||
.hand-tracking-fallback {
|
||||
position: fixed;
|
||||
inset: 0;
|
||||
z-index: 14;
|
||||
width: 100vw;
|
||||
height: 100vh;
|
||||
pointer-events: none;
|
||||
}
|
||||
|
||||
.hand-tracking-fallback__icon {
|
||||
position: absolute;
|
||||
width: 96px;
|
||||
height: 96px;
|
||||
fill: #67e8f9;
|
||||
stroke: #0c4a6e;
|
||||
stroke-width: 2;
|
||||
stroke-linejoin: round;
|
||||
filter: drop-shadow(0 0 8px rgba(56, 189, 248, 0.55));
|
||||
}
|
||||
|
||||
/* Zustand game state debug UI */
|
||||
.game-state-debug-panel {
|
||||
display: grid;
|
||||
|
||||
Reference in New Issue
Block a user