Settings

Settings are configuration values that control CE.SDK editor behavior without modifying scene content. They are accessed via key paths (e.g., page/title/show) and support multiple types including Bool, Int, Float, String, Color, and Enum. Use settings to customize visual appearance, interaction behavior, resource paths, and feature toggles.

When to Change Settings#

Settings can be changed at any time after engine initialization, but they fall into two categories based on when they should be modified.

Initialization-Only Settings#

Some settings should only be set once during or immediately after engine initialization. Changing them later may have no effect or cause unexpected behavior:

• license - The license key validates on startup; changing it later has no effect
• basePath - The base URL for resolving assets; should be set before loading any resources
• defaultFontFileUri / defaultEmojiFontFileUri - Default fonts used when no font is specified; should be set early
• maxImageSize - Memory limit for images; changing mid-session won’t affect already-loaded images

Runtime Settings#

Most settings can be changed at any time and take effect immediately:

• Visual appearance: highlightColor, snappingGuideColor, cropOverlayColor, page/title/color
• Interaction behavior: doubleClickToCropEnabled, doubleClickSelectionMode, touch/*, mouse/*
• Control gizmos: controlGizmo/showResizeHandles, controlGizmo/showRotateHandles
• Page display: page/title/show, page/dimOutOfPageAreas, page/title/separator
• Feature toggles: blockAnimations/enabled, useSystemFontFallback, forceSystemEmojis
• Snapping thresholds: positionSnappingThreshold, rotationSnappingThreshold

These runtime settings are commonly used to adapt the editor UI to different modes, user preferences, or workflow states.

Using the Settings API#

Discover Available Settings#

Use findAllSettings() to get a list of all available settings:

const allSettings = engine.editor.findAllSettings();

Read and Write Settings#

Use getSetting() and setSetting() to read and write settings. The API automatically handles the correct type based on the setting key:

// Boolean settings
engine.editor.setSetting('doubleClickToCropEnabled', true);
const cropEnabled = engine.editor.getSetting('doubleClickToCropEnabled');

// Number settings
engine.editor.setSetting('maxImageSize', 4096);
engine.editor.setSetting('positionSnappingThreshold', 2.0);

// String settings
engine.editor.setSetting('page/title/separator', ' | ');

// Color settings
engine.editor.setSetting('highlightColor', { r: 1, g: 0, b: 1, a: 1 });

// Enum settings
engine.editor.setSetting('doubleClickSelectionMode', 'Direct');
const enumOptions = engine.editor.getSettingEnumOptions(
  'doubleClickSelectionMode',
);

Subscribe to Settings Changes#

React to settings changes using onSettingsChanged():

const unsubscribe = engine.editor.onSettingsChanged(() => {
  console.log('Editor settings have changed');
});

// Later, to stop listening:
unsubscribe();

Role Management#

Roles apply predefined defaults for scopes and settings:

// Get current role
const currentRole = engine.editor.getRole();

// Set role and apply role-dependent defaults
engine.editor.setRole('Adopter');

// React to role changes
const unsubscribe = engine.editor.onRoleChanged(role => {
  console.log('Role changed to:', role);
});

Available Settings#

Settings Type#

Editor Settings

This section describes the all available editor settings.

GlobalScopes#