Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Data & analytics

cesiumjs-custom-shader

CustomShader authoring — vertexShaderText and fragmentShaderText against VertexInput, FragmentInput, FeatureIds, Metadata, czm_modelMaterial. Use when reading EXT_mesh_features or EXT_structural_metadata property textures/tables, vertex displacement, or shading VoxelPrimitive.

CesiumGS · AI review on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add CesiumGS/cesiumjs-skills --skill cesiumjs-custom-shader

About this skill


name: cesiumjs-custom-shader description: "CustomShader authoring — vertexShaderText and fragmentShaderText against VertexInput, FragmentInput, FeatureIds, Metadata, czm_modelMaterial. Use when reading EXT_mesh_features or EXT_structural_metadata property textures/tables, vertex displacement, or shading VoxelPrimitive."

CesiumJS CustomShader

Version baseline: CesiumJS 1.143. All imports use ES module style.

CustomShader injects user GLSL into the Model / Cesium3DTileset / VoxelPrimitive rendering pipeline. It exposes glTF attributes, feature IDs, and EXT_structural_metadata to per-vertex and per-fragment code, and returns values through the built-in czm_modelVertexOutput and czm_modelMaterial structs.

Use this skill for writing the shader body. Use:

  • cesiumjs-materials-shaders — for Fabric Material, ImageBasedLighting, PostProcessStage (bloom, SSAO, FXAA, tonemapping).
  • cesiumjs-3d-tiles — for declarative per-feature coloring via Cesium3DTileStyle, and for VoxelPrimitive setup/configuration.
  • cesiumjs-models-particles — for Model.fromGltfAsync, animations, ModelFeature.getProperty().

Out of scope

  • Fabric Material for entity polylines/polygons/walls — see cesiumjs-materials-shaders.
  • PostProcessStage screen-space effects — see cesiumjs-materials-shaders.
  • ImageBasedLighting — see cesiumjs-materials-shaders.
  • Cesium3DTileStyle declarative JSON styling — see cesiumjs-3d-tiles. Do not combine with CustomShader on the same tileset.
  • Authoring EXT_structural_metadata / EXT_mesh_features in glTF — tooling concern, not runtime.

Minimal example

import { CustomShader, Model } from "cesium";

const shader = new CustomShader({
  fragmentShaderText: `
    void fragmentMain(FragmentInput fsInput, inout czm_modelMaterial material) {
      material.diffuse = vec3(1.0, 0.0, 0.0);
      material.alpha = 0.8;
    }
  `,
});

const model = await Model.fromGltfAsync({ url: "./aircraft.glb", customShader: shader });
viewer.scene.primitives.add(model);

Applying a CustomShader

Model — constructor option or mutable property:

const model = await Model.fromGltfAsync({ url, customShader });
model.customShader = newShader;     // hot-swap
model.customShader = undefined;     // clear

Cesium3DTileset — constructor option or mutable property. Only Model-backed tile content is affected (not native I3S or other formats):

const tileset = await Cesium3DTileset.fromUrl(url, { customShader });
tileset.customShader = newShader;

Per the Cesium3DTileset.customShader JSDoc: "Using custom shaders with a Cesium3DTileStyle may lead to undefined behavior." The property is also marked @experimental — it uses 3D Tiles spec surface that is not final and may change without Cesium's standard deprecation policy.

VoxelPrimitive — fragment-only subset (see "VoxelPrimitive shader subset" below):

const voxelPrimitive = new VoxelPrimitive({ provider, customShader });

The engine calls customShader.update(frameState) automatically each frame. When finished with a CustomShader, call customShader.destroy() to release GPU texture resources owned by its TextureManager.

Constructor reference

new CustomShader({
  mode,                  // CustomShaderMode — default MODIFY_MATERIAL
  lightingModel,         // LightingModel — if omitted, model's default is preserved
  translucencyMode,      // CustomShaderTranslucencyMode — default INHERIT
  uniforms,              // { [name]: { type: UniformType, value } } — default {}
  varyings,              // { [name]: VaryingType } — default {}
  vertexShaderText,      // string or undefined
  fragmentShaderText,    // string or undefined
});

Either vertexShaderText or fragmentShaderText is typically required. See REFERENCE.md for exhaustive enum values.

Shader function signatures

The runtime calls these from generated pipeline stages. Parameter names are part of the contract — renaming them breaks the shader.

void vertexMain(VertexInput vsInput, inout czm_modelVertexOutput vsOutput) { ... }
void fragmentMain(FragmentInput fsInput, inout czm_modelMaterial material) { ... }

Uniforms

Declare uniforms with { type, value }. The type is a UniformType value; the JS value type must match (e.g. VEC3 → Cartesian3). Uniforms are accessible in GLSL by their declared name.

import { CustomShader, UniformType, TextureUniform, Cartesian3 } from "cesium";

const shader = new CustomShader({
  uniforms: {
    u_tint:   { type: UniformType.VEC3,      value: new Cartesian3(1.0, 0.5, 0.2) },
    u_time:   { type: UniformType.FLOAT,     value: 0.0 },
    u_detail: { type: UniformType.SAMPLER_2D, value: new TextureUniform({ url: "./detail.png", repeat: true }) },
  },
  fragmentShaderText: `
    void fragmentMain(FragmentInput fsInput, inout czm_modelMaterial material) {
      vec3 d = texture(u_detail, fsInput.attributes.texCoord_0).rgb;
      material.diffuse = mix(material.diffuse, u_tint, d.r + 0.1 * sin(u_time));
    }
  `,
});

// Update at runtime. For Cartesian/Matrix values, setUniform clones into existing storage.
shader.setUniform("u_time", performance.now() / 1000);

TextureUniform accepts either url (string or Resource) or typedArray + width + height — exactly one (constructor throws otherwise). Other options: repeat (default true), pixelFormat, pixelDatatype, minificationFilter, magnificationFilter, maximumAnisotropy.

SAMPLER_CUBE is declared on UniformType but rejected at construction — throws DeveloperError("CustomShader does not support samplerCube uniforms"). Only SAMPLER_2D is supported.

Varyings

Declared varyings are emitted as out <type> <name> in the vertex shader and in <type> <name> in the fragment shader. Write in vertex, read in fragment.

import { CustomShader, VaryingType } from "cesium";

const sh
Read the complete source ↗