Configuration and debugging
Project settings (Tools → Cesium Settings)
Writes live Settings Registry and <project>/user/Registry/cesium.settings.setreg:
| Setting | Registry key (under /O3DE/Gems/Cesium3DTiles/) | Default |
|---|---|---|
| Ion access token | DefaultIonAccessToken | empty (use env) |
| Ion server URL | DefaultIonServerUrl | https://api.cesium.com/ |
| Request cache path | RequestCachePath | @user@/cesium_request_cache.sqlite |
| Cache max size | RequestCacheMaxSizeBytes | 512 MB |
| Cache max items | RequestCacheMaxItems | 0 (unlimited by count) |
| Requests per cache prune | RequestsPerCachePrune | 10000 |
| Default SSE | DefaultMaximumScreenSpaceError | 16 |
| Max simultaneous loads | MaximumSimultaneousTileLoads | 8 |
| Scale LOD by DPI | ScaleLevelOfDetailByDPI | false |
| Enable LargeWorld on activate | EnableLargeWorldOnActivate | true |
Token env var name: DefaultIonAccessTokenEnvVar = CESIUM_ION_TOKEN.
Gem default file: Gems/Cesium3DTiles/Registry/Cesium3DTiles.setreg.
Token resolution order
- Component ion access token (tileset or overlay)
.cesiumionserverassetDefaultAccessToken(when assigned)- Settings dialog /
DefaultIonAccessTokenin registry - Environment variable named by
DefaultIonAccessTokenEnvVar(defaultCESIUM_ION_TOKEN)
Use Troubleshoot Token from the tileset, ion panel, or Tools menu when loads return 401/404.
Bridge modes
/O3DE/Cesium3DTiles/Bridge/TerrainMode and WorldStreamingMode: Off / Bridge / Coexist (default Coexist). See
Environment, metadata, and bridges.
HTTP transport
Keys under /O3DE/Cesium3DTiles/Http/:
| Key | Default | Purpose |
|---|---|---|
UseMultiHandle | (gem default) | Curl multi event loop vs blocking fallback |
MaxConcurrentRequests | (gem default) | Concurrent HTTP transfers |
ConnectTimeoutSeconds | 15 | DNS + TCP + TLS handshake |
LowSpeedLimitBytesPerSecond | 1024 | Stall threshold |
LowSpeedTimeoutSeconds | 30 | Seconds below low-speed limit → dead |
MaxRetries | 3 | Transient GET retries (TLS/connect/timeout/drops) |
RetryBaseDelayMilliseconds | 500 | Exponential backoff base |
Proxy | empty | e.g. http://host:port (multi path) |
CaCertFile / CaCertPath | empty | PEM overrides; empty uses OS store |
Transient transport failures retry with a fresh connection; deterministic protocol / cert-verify / HTTP status errors do not.
Diagnostics registry
| Key | Purpose |
|---|---|
/O3DE/Cesium3DTiles/Diagnostics/EnableWorldBoundsChecks | Warn when the camera drifts far from the render origin |
/O3DE/Cesium3DTiles/Diagnostics/RenderOriginWarnDistanceMeters | Threshold (default ~100 km); suggests attaching Origin Shift |
Console and CVars
| Command / cvar | Purpose |
|---|---|
cesium_drawTileBounds | Draw tile AABBs / OBBs |
cesium_drawTileInfo | Per-tile ID + geometric error |
cesium_drawVoxelGrids | Voxel grid debug |
cesium_drawSubLevelLoadRadii | Sub-level load spheres |
CesiumDumpWsBridgeStats | WorldStreaming bridge stats |
CesiumDumpTerrainBridgeStats | Terrain bridge stats |
CesiumDumpNavMeshBridgeStats | NavMesh bridge stats |
Tileset flags: Log selection stats, Log shared asset stats. Offline capture: SetOfflineRenderingEnabled blocks until load progress hits 100% (30 s timeout).
System: Cesium3DTilesSystemRequestBus::ClearRequestCache() clears the SQLite request cache.
Troubleshooting
| Symptom | Likely cause | What to try |
|---|---|---|
| Black / empty globe | Missing token, network, or georeference | Set CESIUM_ION_TOKEN; confirm Georeference entity; Troubleshoot Token |
| Jitter far from origin | LargeWorld / Origin Shift off | Enable LargeWorld; add Origin Shift UpdateRenderOrigin on camera |
| Imagery missing | Wrong overlay asset ID / slot | ion 2 (or your imagery ID); material slot 0; overlay defaults to 0 = unset |
| 401 / 404 on ion | Token scope or asset access | Token troubleshooter; check ion dashboard permissions |
| SSL / connect errors | Transient TLS or proxy / CA | Raise MaxRetries; set Proxy / CaCertFile; check firewall |
| Ground stays coarse after flying | Adaptive SSE stuck (rare) | Idle after flight; lower SSE; avoid huge frame-time spikes |
| Imagery seams between zooms | Data-source LOD mismatch | Lower geometry SSE; expected for multi-zoom imagery |
| PIE memory spike | Editor + runtime tilesets both live | Enable Unload tiles in play mode |
| Credits not visible | ImGui disabled / no Credit component | Enable ImGui Gem; add CesiumCreditSystemComponent |
| Physics raycast misses | Colliders off | Create physics meshes = true |
| LOD ignores a camera | Source filter / wrong manager | Check per-tileset camera toggles and Camera manager entity |