Cesium Core Versioning

CesiumJS Versioning and Migration

Overview

CesiumJS releases monthly. Between versions 1.104 and 1.142 a set of constructor, utility, and rendering changes turned most pre-2023 example code into code that throws at runtime. This skill maps every relevant change and gives a deterministic migration path for each legacy pattern.

Core principle: CesiumJS 1.124+ is the async-factory era. Resources that touch the network (tilesets, models, terrain, imagery) ALWAYS load through a static from* factory that returns a Promise. The synchronous new + readyPromise pattern was removed in 1.107 and NEVER works on a 1.124+ target.

When to Use This Skill

Use this skill when ANY of these symptoms appear:

• TypeError: tileset.readyPromise is not a function or ... is undefined
• TypeError: Cesium.Cesium3DTileset is not a constructor when called with new
• ReferenceError: defaultValue is not defined or Cesium.defaultValue is not a function
• Cesium.Cartesian3.fromDegrees is not a constructor (calling new on a factory)
• createWorldTerrain is not a function
• ModelExperimental referenced anywhere in a codebase
• Code copied from an old Sandcastle, blog post, or tutorial silently fails
• A scene renders but looks visually different after a CesiumJS upgrade
• A question of the form "what version introduced X" or "how do I upgrade"

Do NOT use this skill for a blank globe caused by a missing CESIUM_BASE_URL or a missing ion token. That is a build or configuration fault: see cesium-errors-rendering and cesium-impl-build-deploy.

The Async Era: One Rule

ALWAYS construct network-backed resources with their async factory and await the result. NEVER use new on a tileset, model, or provider, and NEVER read .ready or .readyPromise.

// MODERN : the awaited result is fully loaded and ready to use.
const tileset = await Cesium.Cesium3DTileset.fromIonAssetId(69380);
viewer.scene.primitives.add(tileset);
await viewer.zoomTo(tileset);

The awaited factory result replaces every old readiness signal. There is no .ready flag to poll and no .readyPromise to chain, because the await already guarantees the resource is ready.

Version Matrix: Baseline Changes (pre-1.124, baked into the target)

Every change below already took effect before the 1.124 support floor. Legacy code written against an older release hits these as hard failures.

Version Matrix: Within the 1.124 to 1.142 Window

Verified against the official CHANGES.md on 2026-05-20. The full per-version detail and exact changelog quotes are in references/methods.md.

Legacy Pattern Detection

Scan a codebase for the tokens in the left column. Each one is a removed or broken API on a 1.124+ target. The right column is the ONLY correct replacement.

The full grep-ready regex catalog for automated detection is in references/anti-patterns.md.

Decision Tree: Migrating Legacy Code

digraph migration {
    rankdir=TB;
    node [shape=box, fontname="Helvetica"];
    start [label="Code throws or renders wrong after a CesiumJS upgrade"];
    q_ready [shape=diamond, label="readyPromise, .ready, or new on\na tileset / model / provider?"];
    q_default [shape=diamond, label="defaultValue undefined?"];
    q_cart [shape=diamond, label="new on a Cartesian factory,\nor Cartesian is not a constructor?"];
    q_exag [shape=diamond, label="Globe.terrainExaggeration?"];
    q_visual [shape=diamond, label="Renders but looks different,\nno error thrown?"];
    fix_ready [label="Replace with the async from* factory.\nawait the result. Delete .ready / .readyPromise."];
    fix_default [label="Replace defaultValue(a, b) with a ?? b.\nReplace defaultValue.EMPTY_OBJECT with Frozen.EMPTY_OBJECT."];
    fix_cart [label="Drop the new keyword.\nCartesian3.fromDegrees(...) is a static factory."];
    fix_exag [label="Move to scene.verticalExaggeration\nand scene.verticalExaggerationRelativeHeight."];
    fix_visual [label="Expected: 1.121 changed MSAA and tonemap defaults.\nSet scene.msaaSamples = 1 to compare against the old look."];
    unknown [label="Read every Breaking Changes block in CHANGES.md\nbetween the old and new version (see section below)."];

    start -> q_ready;
    q_ready -> fix_ready [label="yes"];
    q_ready -> q_default [label="no"];
    q_default -> fix_default [label="yes"];
    q_default -> q_cart [label="no"];
    q_cart -> fix_cart [label="yes"];
    q_cart -> q_exag [label="no"];
    q_exag -> fix_exag [label="yes"];
    q_exag -> q_visual [label="no"];
    q_visual -> fix_visual [label="yes"];
    q_visual -> unknown [label="no"];
}

Migration 1: Async Factory Constructors (1.104 / 1.107)

This is the single largest source of broken CesiumJS code. It affects Cesium3DTileset, Model, every terrain provider, and every imagery provider.

// LEGACY : removed in CesiumJS 1.107. This code throws on a 1.124+ target.
const tileset = new Cesium.Cesium3DTileset({
  url: Cesium.IonResource.fromAssetId(69380),
});
viewer.scene.primitives.add(tileset);
tileset.readyPromise.then(function () {
  viewer.zoomTo(tileset);
});

// MODERN : async factory. await replaces the readyPromise chain entirely.
const tileset = await Cesium.Cesium3DTileset.fromIonAssetId(69380);
viewer.scene.primitives.add(tileset);
await viewer.zoomTo(tileset);

The factory rejects its promise on a load failure, so wrap the await in try / catch to surface errors. The full factory list per class is in references/methods.md; complete before/after ports are in references/examples.md.

Migration 2: defaultValue Removed (1.134)

The defaultValue helper was removed in 1.134. JavaScript nullish coalescing covers the same intent and ships in every supported runtime.

// LEGACY : removed in CesiumJS 1.134.
const height = Cesium.defaultValue(options.height, 0);
const opts = Cesium.defaultValue(options, Cesium.defaultValue.EMPTY_OBJECT);

// MODERN : nullish coalescing and the Frozen constant.
const height = options.height ?? 0;
const opts = options ?? Cesium.Frozen.EMPTY_OBJECT;

?? differs from defaultValue only in that it falls through on null and undefined but NOT on 0, false, or "". That difference is the correct behavior and was a known bug class with the old helper.

Migration 3: Cartesian ES6 Classes (1.139)

In 1.139 Cartesian2, Cartesian3, and Cartesian4 became ES6 classes. Calling new on one of their static factory methods now throws.

// LEGACY : throws since CesiumJS 1.139. fromDegrees is a factory, not a constructor.
const pos = new Cesium.Cartesian3.fromDegrees(-75.0, 40.0, 100.0);

// MODERN : call the static factory directly, with no new keyword.
const pos = Cesium.Cartesian3.fromDegrees(-75.0, 40.0, 100.0);

The real constructor new Cesium.Cartesian3(x, y, z) with raw numeric components remains valid. Only new applied to a from* factory throws.

Migration 4: Vertical Exaggeration Moved (1.113)

// LEGACY : Globe-based exaggeration removed in 1.113.
viewer.scene.globe.terrainExaggeration = 2.0;

// MODERN : vertical exaggeration is a Scene property and also affects 3D Tiles.
viewer.scene.verticalExaggeration = 2.0;
viewer.scene.verticalExaggerationRelativeHeight = 0.0;

API Surface Change: Viewer to CesiumWidget (1.123)

In 1.123 the members entities, dataSources, zoomTo, and flyTo were added to CesiumWidget. This is additive. Existing Viewer code is NOT affected. Code that previously built a bare CesiumWidget and attached a DataSourceDisplay by hand can now use the built-in members directly.

Visual Behavior Changes (1.121)

Release 1.121 changed two rendering defaults. No code throws, but a scene rendered against 1.124+ looks different from the same scene on an older build.

• MSAA is on by default at 4 samples. To restore the pre-1.121 aliased look or to measure cost, set viewer.scene.msaaSamples = 1.
• PBR Neutral tonemapping replaced ACES as the default tonemapper. Lit 3D Tiles and glTF models render with different brightness and color response. NEVER assume a scene looked identical across the 1.121 boundary. The tonemapper enum is documented in the API reference under Scene.

How to Read CHANGES.md for a Migration

CHANGES.md in the CesiumGS/cesium repository is the authoritative change log.

1. ALWAYS fetch the raw form: https://raw.githubusercontent.com/CesiumGS/cesium/main/CHANGES.md. The rendered GitHub blob page does not expose the changelog text to an automated fetch.
2. Each release block carries subsections in this order: ### Breaking Changes, ### Deprecated, ### Additions, ### Fixes.
3. To plan an upgrade, read every ### Breaking Changes and ### Deprecated block for each release between the current version and the target version.
4. A ### Deprecated notice ALWAYS names the version in which the API will be removed. Treat that as a hard deadline, not a suggestion.

Common Mistakes

Reference Files

• references/methods.md : per-class async factory signatures, the full version matrix with exact CHANGES.md quotes, and the CHANGES.md section structure.
• references/examples.md : complete before/after migration ports, including a full legacy-to-modern bootstrap rewrite.
• references/anti-patterns.md : the grep-ready legacy-token regex catalog and each removed-API failure with symptom, root cause, and fix.

Related Skills

• cesium-syntax-3d-tiles : the modern Cesium3DTileset async loading API.
• cesium-syntax-gltf-model : Model.fromGltfAsync usage.
• cesium-syntax-terrain : terrain provider async factories.
• cesium-core-coordinates : Cartesian3 and Cartographic usage detail.
• cesium-errors-tileset : runtime tileset load failures.
• cesium-agents-skill-validator : automated deprecated-pattern detection.