Load a Scene

import Foundation
import IMGLYEngine

@MainActor
func loadSceneFromRemote(engine: Engine) async throws {
  let baseURL = try engine.guidesBaseURL

  let sceneURL =
    baseURL.appendingPathComponent("ly.img.templates/templates/cesdk_business_card_1.scene")

  try await engine.scene.load(from: sceneURL)

  guard let text = try engine.block.find(byType: .text).first else { return }
  try engine.block.setDropShadowEnabled(text, enabled: true)
}

import Foundation
import IMGLYEngine

@MainActor
func loadSceneFromString(engine: Engine) async throws {
  let baseURL = try engine.guidesBaseURL

  let sceneURL = baseURL.appendingPathComponent("ly.img.templates/templates/cesdk_business_card_1.scene")
  let sceneBlob = try await URLSession.shared.data(from: sceneURL).0
  guard let blobString = String(data: sceneBlob, encoding: .utf8) else { return }

  try await engine.scene.load(from: blobString)

  let text = try engine.block.find(byType: .text).first!
  try engine.block.setDropShadowEnabled(text, enabled: true)
}

import Foundation
import IMGLYEngine

@MainActor
func loadSceneFromBlob(engine: Engine) async throws {
  let baseURL = try engine.guidesBaseURL

  let sceneURL = baseURL.appendingPathComponent("ly.img.templates/templates/cesdk_business_card_1.scene")
  let sceneBlob = try await URLSession.shared.data(from: sceneURL).0

  guard let blobString = String(data: sceneBlob, encoding: .utf8) else { return }

  try await engine.scene.load(from: blobString)

  let text = try engine.block.find(byType: .text).first!
  try engine.block.setDropShadowEnabled(text, enabled: true)
}

Scene files contain layout, properties, and asset references, but not the assets themselves. When loading a scene, make sure the referenced asset URLs remain accessible. For self-contained packages with bundled assets, use archives instead.

This guide covers loading scenes from URLs, strings, and blobs, and modifying a loaded scene.

Load a Scene from URL#

The most common approach loads a scene from a remote URL. Pass a URL that points to a .scene file to engine.scene.load(from:). The call is asynchronous and replaces any existing scene with the loaded one. It throws if the scene cannot be loaded.

try await engine.scene.load(from: sceneURL)

Load a Scene from String#

When a scene is stored in a database or local storage, load it from a string — typically the output of a previous engine.scene.saveToString() call. Here, fetch the scene over the network and decode it to a string.

let sceneURL = baseURL.appendingPathComponent("ly.img.templates/templates/cesdk_business_card_1.scene")
let sceneBlob = try await URLSession.shared.data(from: sceneURL).0
guard let blobString = String(data: sceneBlob, encoding: .utf8) else { return }

Pass the string to engine.scene.load(from:). As with the URL form, the editor resets and presents the loaded scene.

try await engine.scene.load(from: blobString)

Load a Scene from In-Memory Data#

When you already hold the scene’s bytes in memory — from a file upload or blob storage — start from Data. Here, fetch the bytes to stand in for that in-memory data.

let sceneURL = baseURL.appendingPathComponent("ly.img.templates/templates/cesdk_business_card_1.scene")
let sceneBlob = try await URLSession.shared.data(from: sceneURL).0

load(from:) accepts a URL or a String, but not raw Data, so decode the bytes to a UTF-8 string first.

guard let blobString = String(data: sceneBlob, encoding: .utf8) else { return }

Then load it with engine.scene.load(from:).

try await engine.scene.load(from: blobString)

Modify a Loaded Scene#

After loading, the scene is immediately editable. Locate elements with engine.block.find(byType:), then change them with the block APIs. This example adds a drop shadow to the first text block.

guard let text = try engine.block.find(byType: .text).first else { return }
try engine.block.setDropShadowEnabled(text, enabled: true)

A scene load can be reverted with engine.editor.undo().

Scene Files vs Archives#

Scene files (.scene) are lightweight: they store only references to assets, so the scene won’t display correctly if those asset URLs become unavailable. For a self-contained package with bundled assets, load an archive with engine.scene.loadArchive(from:) — all asset paths resolve relative to the archive’s location. See Import Design from Archive for the full archive workflow. To redirect asset requests to a different location, register a custom resolver; see the URI Resolver guide.

Troubleshooting#

Scene fails to load#

• Verify the URL is reachable and returns a valid .scene file.
• Ensure the scene format is compatible with your CE.SDK version.

Assets not displaying after load#

• Scene files store asset references as URLs — make sure those URLs remain accessible.
• Use archives for self-contained scenes with bundled assets.
• Configure a URI resolver if assets are hosted on a different server.

String content is invalid#

• Ensure the string is the exact output of engine.scene.saveToString().
• Verify the string was not modified or truncated during storage.

API Reference#

Next Steps#

• Save Scenes — Persist your work as a scene file or archive for later loading.
• Import Design from Archive — Load self-contained archives that bundle every referenced asset.
• Blocks — Edit blocks, properties, and content in a loaded scene.
• URI Resolver — Redirect asset requests to custom locations.