Programmatically referring to entities in a Sumerian scene

EntitySets in Sumerian provide a convenient way to query your scene for entities that match certain criteria. You can query entities by name (as displayed in the "Entities" outline) or by tag. You can use literal strings or Regular Expressions to define your match criteria.

Below is some example code that creates an EntitySet by searching your scene for two entity name strings ("MyBox" and "MySphere") and then loops over those entities to create copies of them.

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

export default function(ctx) {
	
	// Create an EntitySet containing the source entities
	// we care about.
	const spawnableEntities = ctx.world.entities.withName("MyBox", "MySphere");
	
	// Loop through each source entity in our EntitySet
	// and spawn a copy of each.
	spawnableEntities.forEach(entity => {
		ctx.start(
			[s.entity.LoadEntityInstanceAction, { 
				entity: entity, 
				onCreate: onSpawnedEntityReady
			}]);
	});
	
	// This function will be triggered as soon as each 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);
	}
}

An alternative to using the .withName() method is to use the .withTag() method. With that approach, you could tag multiple entities with a tag name of your choosing, for example "copy_me". Then you would use ctx.world.entities.withTag("copy_me") to create your EntitySet.