Code API for SwiftUI

The Code API allows you to seamlessly integrate interactive 3D experiences into your projects, offering greater control and customization. It enables you to trigger actions, modify object properties, and create dynamic, responsive 3D environments directly from your existing code and user interface.

Key capabilities

• Event Listeners: React to real-time events within your 3D scenes.

• Adjust Properties: Dynamically update position, scale, rotation, and more.

• Trigger Transitions: Create transitions and animations based on events.

• Adjust variables: Retrieve and update variables in a Spline scene.

Usage

Getting started

First, make sure you’re familiar with and you can already embed 3D content in your SwiftUI projects.

struct ContentView: View {
    var body: some View {
        let url = URL(string: "https://build.spline.design/4-2CGowqS9z7MGA62D-B/scene.splineswift")!

        SplineView(sceneFileURL: url)
    }
}

Then, to access the API, create a SplineController object and pass it to SplineView initializer for the view you want to control.

struct ContentView: View {
		private var controller = SplineController()
		
    var body: some View {
        let url = URL(string: "https://build.spline.design/4-2CGowqS9z7MGA62D-B/scene.splineswift")!

        SplineView(sceneFileURL: url, controller: controller)
    }
}

Read and modify Spline objects

You can query any Spline object in the scene via findObject(name:) or findObject(id:) functions. Then, you can read or write any of its properties.

(You can get the ID of the object from the right-click context panel on the object).

struct ContentView: View {
    private var controller = SplineController()

    var body: some View {
        let url = URL(string: "https://build.spline.design/4-2CGowqS9z7MGA62D-B/scene.splineswift")!

        SplineView(sceneFileURL: url, controller: controller)

        Button("Move") {
            let cube = controller.findObject(name: "Cube")
            cube?.position.y += 10
        }
    }
}

The function returns nil if an object with the specified name was not found.

Note that SplineView loads its content asynchronously, and so these and all other functions may return nil or may do nothing when the scene file still hasn’t finished loading. This is especially important when you want to access the API right at the start. For this, see the next example.

Listen to events

You can listen to any Spline Event you set in the Events panel of the editor by attaching a listener to the controller. You can find a list of all of the Spline Event listeners in the API section.

To register event listeners when the view loads, make sure to use a task() or onAppear() modifier on the view that holds loaded content (SplineContent) and not the SplineView itself.

struct ContentView: View {
    private var controller = SplineController()

    var body: some View {
        let url = URL(string: "https://build.spline.design/4-2CGowqS9z7MGA62D-B/scene.splineswift")!

        SplineView(sceneFileURL: url, controller: controller) { phase in
            phase.content?.task {
                controller.addEventListener(.mouseUp) { obj in
                    if obj.name == "Cube" {
                        print("Cube clicked")
                    }
                }
            }
        }
    }
}

Trigger Spline events from outside

You can trigger any animation Event you set in the Events panel in the Spline Editor. You can use the emitEvent(_:) function, passing the event type and the name or ID of your object.

(You can get the ID of the object from the right-click context panel on the object).

struct ContentView: View {
    private var controller = SplineController()

    var body: some View {
        let url = URL(string: "https://build.spline.design/4-2CGowqS9z7MGA62D-B/scene.splineswift")!

        SplineView(sceneFileURL: url, controller: controller)

        Button("Jump") {
            controller.emitEvent(.keyUp, nameOrUUID: "Cube")
        }
    }
}

Or you can query the spline object first, and then trigger the event:

struct ContentView: View {
    private var controller = SplineController()

    var body: some View {
        let url = URL(string: "https://build.spline.design/4-2CGowqS9z7MGA62D-B/scene.splineswift")!

        SplineView(sceneFileURL: url, controller: controller)

        Button("Jump") {
            let cube = controller.findObject(name: "Cube")
            cube?.emitEvent(.keyUp)
        }
    }
}

You can find a list of all of the Spline Events you can pass to the emitEvent(:_) function in the Spline Events section.

Handling multiple views

If you have several SplineView's in a SwiftUI view hierarchy, and multiple of them are using the Code API, each view must have its own SplineController object.

struct ContentView: View {
    private var cubes = SplineController()
    private var spheres = SplineController()

    var body: some View {
        let urlCubes = ...
        let urlSpheres = ...
        let urlCylinders = ...

        SplineView(sceneFileURL: urlCubes, controller: cubes)
        SplineView(sceneFileURL: urlSpheres, controller: spheres)
        SplineView(sceneFileURL: urlCylinders)

        Button("Go Cube") {
            cubes.emitEvent(.keyUp, nameOrUUID: "Cube1")
        }

        Button("Go Sphere") {
            spheres.emitEvent(.keyUp, nameOrUUID: "Sphere1")
        }
    }
}

Updating scene variables

If you set up variables in your Spline scene from the editor, you can change them from code after the scene is loaded.

struct ContentView: View {
    private var controller = SplineController()

    var body: some View {
        let url = URL(string: "https://build.spline.design/4-2CGowqS9z7MGA62D-B/scene.splineswift")!

        SplineView(sceneFileURL: url, controller: controller) { phase in
            phase.content?.task {
                controller.setNumberVariable(name: "opacity", value: 25)
            }
        }
    }
}

Download Xcode Demo

See how it works by downloading an Xcode demo project using Spline's cloud iOS embeds and SwiftUI Code API.

Trying out the demo:

1. On Xcode, go to File > Open and select the unzipped folder with your project;

2. Select iPhone as the build device – you can use your physical device or a simulator;

3. Trigger the preview on Xcode or press ▶️ to build your project.

Before Building

1. You might need to go into Signing & Capabilities, and under Signing, add your team manually.

2. Optionally, make sure to change the Bundle Identifier to a unique one.

3D Scene:

• https://app.spline.design/file/f68f548d-9f78-4eee-90ce-fc72dafca6de

API

Spline Controller Methods

You can call all these different methods on the SplineController instance.

Spline Objects Methods and Properties

After retrieving a Spline Object with controller.findObject(id:) or controller.findObject(name:), there are a variety of properties and methods you can call on those.

Spline Events

These are all the Spline event types that you can pass to the addEventListener(:), emitEvent(:) and emitEventReverse(_:) functions.