Search Docs
Loading...
Skip to content

Save

Save and serialize designs in CE.SDK for later retrieval, sharing, or storage using string or archive formats.

Save designs showing different save format options

8 mins
estimated time
Download
StackBlitz
GitHub

CE.SDK provides two formats for persisting designs. Choose the format based on your storage and portability requirements.

Save Format Comparison#

Format Method Assets Best For
String saveToString() Referenced by URL Database storage, cloud sync
Archive saveToArchive() Embedded in ZIP Offline use, file sharing

String format produces a lightweight Base64-encoded string where assets remain as URL references. Use this when asset URLs will remain accessible.

Archive format creates a self-contained ZIP with all assets embedded. Use this for portable designs that work offline.

Both formats are saved as .imgly files — use this extension when persisting them. Either kind loads back through the same engine.scene.load() call, which detects the format automatically; .scene and .zip files also load.

Save to String#

Serialize the current scene to a Base64-encoded string suitable for database storage.

const sceneString = await engine.scene.saveToString();

The string contains the complete scene structure but references assets by their original URLs.

Save to Archive#

Create a self-contained ZIP file with the scene and all embedded assets.

const archiveBlob = await engine.scene.saveToArchive();

The archive includes all pages, elements, and asset data in a single portable file.

Compression Options#

Saved scenes are compressed with Zstd by default, which makes them much smaller and speeds up both saving and loading. Pass a format explicitly to change the level, or to turn compression off.

import { CompressionFormat, CompressionLevel } from '@cesdk/cesdk-js';


// Save a scene string with Zstd compression
const compressed = await cesdk.engine.scene.saveToString({
  compression: {
    format: CompressionFormat.Zstd,
    level: CompressionLevel.Default
  }
});


// Save an archive whose scene is compressed
const archive = await cesdk.engine.scene.saveToArchive({
  compression: {
    format: CompressionFormat.Zstd,
    level: CompressionLevel.Default
  }
});

Compression Formats:

  • CompressionFormat.Zstd - Zstandard compression (default)
  • CompressionFormat.None - No compression

Compression Levels:

  • CompressionLevel.Fastest - Fastest compression, larger output
  • CompressionLevel.Default - Balanced speed and size (recommended)
  • CompressionLevel.Best - Best compression, noticeably slower

A compressed scene string stays a plain string, so you can still store it in a text column or send it as JSON. It carries a UBQ2 prefix instead of UBQ1; load accepts both.

In an archive, compression applies to the scene only. Bundled images, video and fonts are stored as they are, because they already are compressed formats — so the saving depends on how much of your archive is scene rather than media.

Download to User Device#

Use cesdk.utils.downloadFile() to trigger a browser download with the correct MIME type.

For scene strings, convert to a Blob first:

const sceneBlob = new Blob([sceneString], {
  type: 'application/octet-stream'
});
await cesdk.utils.downloadFile(sceneBlob, 'text/plain;charset=UTF-8');

For archive blobs, pass directly to the download utility:

await cesdk.utils.downloadFile(archiveBlob, 'application/zip');

This utility handles creating and revoking object URLs automatically.

Load Scene from File#

Use the built-in importScene action to open a file picker for scene files (.imgly or .scene). This restores a previously saved design from its serialized string format.

const handleLoadScene = async () => {
  await cesdk.actions.run('importScene', { format: 'scene' });
};

Scene files are lightweight but require the original asset URLs to remain accessible.

Load Archive from File#

Load a self-contained .imgly archive (the .zip extension also works) that includes all embedded assets.

const handleLoadArchive = async () => {
  await cesdk.actions.run('importScene', { format: 'archive' });

Archives are portable and work offline since all assets are bundled within the file.

Built-in Save Action#

CE.SDK includes a built-in saveScene action that integrates with the navigation bar.

Running an Action#

Trigger the default save behavior programmatically using actions.run():

await cesdk.actions.run('saveScene');

This executes the registered handler for saveScene, which by default downloads the scene file named with the .imgly extension.

Customizing an Action#

Override the default behavior by registering a custom handler:

cesdk.actions.register('saveScene', async () => {
  const sceneString = await engine.scene.saveToString();
  // Send to your backend API
  console.log('Custom save:', sceneString.length, 'bytes');
});

The registered handler runs when the built-in save button is clicked or when the action is triggered via actions.run().

API Reference#

Method Description
engine.scene.saveToString() Serialize scene to Base64 string
engine.scene.saveToArchive() Save scene with assets as ZIP blob
engine.scene.load() Load scene or archive from URL or string
cesdk.utils.downloadFile() Download blob or string to user device
cesdk.actions.run() Execute a registered action with parameters
cesdk.actions.register() Register or override an action handler

Next Steps#