Tom Boullay
120 lines
3.7 KiB
Markdown
120 lines
3.7 KiB
Markdown
# Map LOD System
|
|
|
|
This document describes the runtime LOD system used by the production map.
|
|
|
|
## Goal
|
|
|
|
The map now supports two visual versions for selected models:
|
|
|
|
- the regular model in `public/models/<name>/`
|
|
- the lighter model in `public/models/<name>-LOD/`
|
|
|
|
The runtime chooses between those paths from the active graphics preset. This keeps nearby objects visually richer while reducing the cost of distant objects.
|
|
|
|
## Graphics Presets
|
|
|
|
Presets are configured in:
|
|
|
|
```txt
|
|
src/data/world/graphicsConfig.ts
|
|
```
|
|
|
|
Current behavior:
|
|
|
|
| Preset | Chunk load distance | Fog | LOD behavior |
|
|
| -------- | ------------------: | --- | ------------------------------------- |
|
|
| `low` | 10m | On | Always use `*-LOD` models |
|
|
| `medium` | 20m | On | Always use `*-LOD` models |
|
|
| `high` | 35m | Off | Regular model up to 10m, then `*-LOD` |
|
|
| `ultra` | 50m | Off | Regular model up to 20m, then `*-LOD` |
|
|
|
|
The unload distance stays slightly larger than the load distance to avoid rapid mount/unmount flickering when the player stands near a boundary.
|
|
|
|
## Runtime Selection
|
|
|
|
LOD path mapping lives in:
|
|
|
|
```txt
|
|
src/data/world/mapLodConfig.ts
|
|
```
|
|
|
|
The main selector is `selectMapModelPathByDistance()`. It receives:
|
|
|
|
- the current camera distance
|
|
- the map model name
|
|
- the regular model path
|
|
- the active graphics preset
|
|
|
|
It returns either the regular path or the `*-LOD` path.
|
|
|
|
## Chunked Instanced Models
|
|
|
|
Repeated static assets are rendered through:
|
|
|
|
```txt
|
|
src/world/map-instancing/MapInstancingSystem.tsx
|
|
```
|
|
|
|
For each visible chunk, the system checks the nearest instance in that chunk. If the nearest instance is inside the high-detail threshold, the whole chunk uses the regular model. Otherwise, it uses the `*-LOD` model.
|
|
|
|
This is intentionally chunk-level LOD instead of per-instance LOD. It matches the existing chunk streaming architecture and avoids splitting every object into many tiny batches.
|
|
|
|
## Single And Generated Models
|
|
|
|
Single map nodes use:
|
|
|
|
```txt
|
|
src/hooks/world/useMapLodModelPath.ts
|
|
src/world/GameMap.tsx
|
|
```
|
|
|
|
Some named map objects are rendered through dedicated generated components instead of the generic `GameMap` path. Those components must call `useMapLodModelPath()` directly.
|
|
|
|
Current dedicated generated components with LOD support:
|
|
|
|
```txt
|
|
src/components/three/world/EcoleModel.tsx
|
|
src/components/three/world/LaFabrikMapModel.tsx
|
|
```
|
|
|
|
This matters for `lafabrik`: adding `public/models/lafabrik-LOD/` is not enough by itself. The component must also be connected to `useMapLodModelPath()`.
|
|
|
|
## Adding A New LOD Model
|
|
|
|
To add LOD support for a model:
|
|
|
|
1. Add the light model in `public/models/<name>-LOD/model.gltf`.
|
|
2. Keep the regular model in `public/models/<name>/model.glb` or `public/models/<name>/model.gltf`.
|
|
3. Add the mapping in `src/data/world/mapLodConfig.ts`.
|
|
4. If the model uses a dedicated component, call `useMapLodModelPath()` in that component.
|
|
5. Preload both paths when the component is dedicated and uses `useGLTF.preload()`.
|
|
6. Verify the GLTF/GLB references: buffers, textures, opacity maps, and relative paths.
|
|
|
|
## Current LOD Models
|
|
|
|
The current explicit LOD mappings are:
|
|
|
|
```txt
|
|
ebike
|
|
eolienne
|
|
pylone
|
|
boiteimmeuble
|
|
ecole
|
|
immeuble1
|
|
lafabrik
|
|
maison1
|
|
panneauaffichage
|
|
talkie
|
|
```
|
|
|
|
## Regression Risks
|
|
|
|
The most common failure modes are:
|
|
|
|
- the `*-LOD` folder exists but is missing from `mapLodConfig.ts`
|
|
- a dedicated generated component keeps a hardcoded model path
|
|
- GLTF references point to textures that were renamed during export
|
|
- a model is added to LOD config but does not spawn through `GameMap` or `MapInstancingSystem`
|
|
|
|
Before committing model changes, validate both the regular and LOD folders for missing GLTF refs.
|