Scripting Entity Creation in Sumerian

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.
	//props.entityToSpawn.hide();
	
	// 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.
	
	ctx.start(
		[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);
	}
}