Cesium Agents Scene Architect

Cesium Agents : Scene Architect

Overview

This is an orchestration skill. It does not teach one API; it sequences the setup decisions for a CesiumJS scene and routes each one to the skill that covers it in depth. Follow the decisions in order. Each produces a concrete choice and names the skill to consult.

CesiumJS is WebGL2 only (1.124+). There is no WebGPU path; never plan for one.

When to Use

• Starting a new CesiumJS application or a new map feature.
• A prompt asks "how should I show this data in Cesium" or "how do I set this

up".

• Reviewing a scene that was assembled without a clear plan and renders slowly,

blank, or wrong.

The Setup Decision Order

Resolve these six decisions in sequence. Skipping ahead causes rework.

digraph setup {
  rankdir=TB; node [shape=box];
  d1 [label="1. Viewer or CesiumWidget"];
  d2 [label="2. Imagery base layer"];
  d3 [label="3. Terrain"];
  d4 [label="4. Data representation per dataset"];
  d5 [label="5. requestRenderMode"];
  d6 [label="6. Teardown plan"];
  d1 -> d2 -> d3 -> d4 -> d5 -> d6;
}

Decision 1 : Viewer or CesiumWidget

digraph viewer {
  q [shape=diamond, label="Need built-in UI widgets\n(timeline, geocoder, infobox)?"];
  v [shape=box, label="Viewer"];
  q2 [shape=diamond, label="Need one or two widgets?"];
  v2 [shape=box, label="Viewer, disable the rest"];
  cw [shape=box, label="CesiumWidget"];
  q -> v [label="yes, most"];
  q -> q2 [label="no / minimal"];
  q2 -> v2 [label="one or two"];
  q2 -> cw [label="none, custom UI"];
}

• ALWAYS set Ion.defaultAccessToken before constructing, if any ion asset is

used. A missing token is the top cause of a blank globe.

• Depth: cesium-core-architecture, cesium-syntax-viewer.

Decision 2 : Imagery Base Layer

| Need | Choice | Skill | |------|--------|-------| | Cesium-hosted default imagery | ImageryLayer.fromWorldImagery (ion) | cesium-syntax-imagery | | OpenStreetMap raster | OpenStreetMapImageryProvider | cesium-syntax-imagery | | Bing or ArcGIS imagery | BingMapsImageryProvider, ArcGisMapServerImageryProvider | cesium-syntax-imagery | | A custom XYZ or WMTS source (incl. MapTiler) | UrlTemplateImageryProvider or WebMapTileServiceImageryProvider | cesium-syntax-imagery | | No imagery, abstract globe | construct with baseLayer: false | cesium-syntax-viewer |

All metadata-fetching providers use async factories. NEVER plan around readyPromise.

Decision 3 : Terrain

| Need | Choice | Skill | |------|--------|-------| | Realistic global elevation | Terrain.fromWorldTerrain() or createWorldTerrainAsync() (ion) | cesium-syntax-terrain | | A custom quantized-mesh server | CesiumTerrainProvider.fromUrl(url) | cesium-syntax-terrain | | Esri elevation | ArcGISTiledElevationTerrainProvider.fromUrl(url) | cesium-syntax-terrain | | Flat ellipsoid, no elevation | EllipsoidTerrainProvider (default) | cesium-syntax-terrain |

When terrain is enabled, plan ground clamping for every dataset that must sit on the surface. Depth: cesium-errors-coordinates.

Decision 4 : Data Representation Per Dataset

This is the decision most often made wrong. Choose per dataset.

digraph datarep {
  q1 [shape=diamond, label="Streamed city, point cloud,\nphotogrammetry, or large BIM?"];
  tiles [shape=box, label="3D Tiles : Cesium3DTileset"];
  q2 [shape=diamond, label="Time-dynamic or interactive,\nunder ~10k features?"];
  entity [shape=box, label="Entity API"];
  q3 [shape=diamond, label="Large static geometry set\n(>10k), no time animation?"];
  prim [shape=box, label="Primitive API, batched"];
  single [shape=box, label="One glTF asset: Model.fromGltfAsync"];
  q1 -> tiles [label="yes"];
  q1 -> q2 [label="no"];
  q2 -> entity [label="yes"];
  q2 -> q3 [label="no"];
  q3 -> prim [label="yes"];
  q3 -> single [label="no, a single model"];
}

| Representation | Use for | Skill | |----------------|---------|-------| | Cesium3DTileset | cities, point clouds, photogrammetry, massive BIM | cesium-syntax-3d-tiles, cesium-impl-3d-tiles-styling | | Entity API | interactive markers, tracks, time-dynamic data under ~10k | cesium-syntax-entity, cesium-syntax-time | | Primitive API | large static geometry sets above ~10k features | cesium-syntax-primitive | | Model | a single glTF or glb asset | cesium-syntax-gltf-model | | GeoJsonDataSource, KmlDataSource, CzmlDataSource | file-based vector or time-dynamic data | cesium-syntax-datasources |

• NEVER place tens of thousands of individual Entity objects. The per-tick

visualizer loop becomes the bottleneck. Use batched primitives or 3D Tiles.

• For georeferencing a BIM or CityGML model, see cesium-impl-aec-georef.

Decision 5 : requestRenderMode

digraph rrm {
  q [shape=diamond, label="Does the scene change\nevery frame on its own?"];
  on [shape=box, label="requestRenderMode: true\ncall scene.requestRender() on manual change"];
  off [shape=box, label="Leave continuous rendering"];
  q -> off [label="yes, constant animation"];
  q -> on [label="no, mostly static"];
}

• ALWAYS enable requestRenderMode for a static or rarely-changing scene. It

is the largest single performance and battery win.

• Depth: cesium-core-performance, cesium-core-architecture.

Decision 6 : Teardown Plan

Decide teardown before shipping, not after a leak appears.

• ALWAYS plan one viewer.destroy() on the cleanup path.
• ALWAYS plan removers for every addEventListener, and destroy() for every

ScreenSpaceEventHandler and custom primitive.

• In a single-page app or React, plan ONE long-lived viewer, not one per route.
• Depth: cesium-core-memory, cesium-errors-memory.

React Applications

When the host app is React, the structural choices above still hold; the component wiring is delegated to cesium-impl-resium.

Output of This Skill

Applying the six decisions yields a written setup plan: the viewer class, the imagery and terrain providers, a representation per dataset, the render mode, and a teardown checklist. Hand each item to the named skill for the code.

Reference Files

• references/methods.md : the decision criteria as lookup tables with the

governing skill for each.

• references/examples.md : three worked scene plans (a static AEC site

viewer, a time-dynamic tracking app, a minimal custom-UI globe).

• references/anti-patterns.md : the recurring scene-architecture mistakes.

Related Skills

• cesium-core-architecture : the object hierarchy these decisions rest on.
• cesium-syntax-viewer, cesium-syntax-imagery, cesium-syntax-terrain.
• cesium-syntax-entity, cesium-syntax-primitive, cesium-syntax-3d-tiles.
• cesium-core-performance, cesium-core-memory.
• cesium-agents-skill-validator : checks the generated code after setup.

Sources

Built on the project research base (docs/research/vooronderzoek-cesium.md), itself verified via WebFetch against the CesiumJS API Reference and learn tutorials on the approved sources, 2026-05-20.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Impertio-Studio
• Source: Impertio-Studio/CesiumJS-Claude-Skill-Package
• License: MIT

Install and usage instructions live in the source repository linked above.