By using AWS re:Post, you agree to the Terms of Use

Scripting Entity Creation in Sumerian


Hey folks, I want to script the creation of entities in Sumerian. I started with:

import * as s from 'module://sumerian-common/api/entity';

export default function CreationAction(ctx) {
[ s.entity.CreateEntityAction, { name:"thing", addToWorld:(true) } ]

This is attached to an existing entity. However, when I play the scene, nothing seems to happen. So:

  1. Can anyone point out where I am going wrong?
  2. Note I have specifically imported from api/entity/ - is this necessary, or will importing from api/ include subfolders such as entity/?
  3. Eventually, I want to source the entity to be created from an asset. How would that change the commands I need?

I've been wrestling with this for longer than I care to admit, so any help is massively appreciated! :-)


asked 9 months ago16 views
1 Answer
Accepted Answer

I've been wrestling with this for longer than I care to admit

Understandable. Spawning entities programmatically in Sumerian isn't super intuitive. I hope this will help...

The CreateEntityAction only creates an empty entity which is probably not very useful to you, especially given your stated goal #3. A more useful option is to use the LoadEntityInstanceAction. This action can be used to create new instances of an entity that already exists in your scene.

Side note: There's no way to directly reference assets that exist in the library but not in your scene. In fact, assets that aren't used in your scene get stripped from the final output during the publishing process.

Below is an example script that should be pretty close to what you've described. To use it, first add a Box or other entity that you'd like to use as the "template" for your spawned entities. Then, add this script to an Empty entity in your scene (I often use an empty entity that I name "Scripts".) After attaching the script, with the "Scripts" entity still selected, you'll see that a parameter is exposed called "Entity To Spawn". Simply drag-drop your Box entity from the Entities list into the "Entity To Spawn" field. Then run the scene and you should see that the entity gets duplicated and placed in a random position.

import * as s from 'module://sumerian-common/api';

export const PROPERTIES = {
	// This property will allow you to specify an existing entity in your scene that you would like to use as the basis
	// for new entities.
	entityToSpawn: {
		type: s.type.Entity

export default function(ctx, props) {
	// Uncomment the line below if you would like to hide the template entity.
	// Below we use the LoadEntityInstanceAction which allows us to create a new instance of an entity that exists
	// in our scene. This is an asynchronous action. So if we want to do anything to that new instance—such as change
	// its default location—we must wait until the action notifies us that it has completed its work. The mechanism the
	// action provides for this is the onCreate callback property.
		[s.entity.LoadEntityInstanceAction, { 
			entity: props.entityToSpawn, 
			onCreate: onSpawnedEntityReady
	// This function will be triggered as soon as the new entity instance has completed its initialization and is ready
	// for use.
	function onSpawnedEntityReady(spawnedEntity) {
		// Here we're just moving the new entity to a random location.
		const x = Math.random() * 2;
		const y = Math.random() * 2;
		const z = Math.random() * 2;
		spawnedEntity.position.setDirect(x, y, z);
profile picture
answered 9 months ago
  • Fantastic, thanks for a detailed and helpful answer!

You are not logged in. Log in to post an answer.

A good answer clearly answers the question and provides constructive feedback and encourages professional growth in the question asker.

Guidelines for Answering Questions