Warning

Warning: Unity Simulation is deprecated as of December 2023, and is no longer available.

Create a new Initializer

The Permutations package comes with a set of pre-defined Initializers that simplify some processes, like spawning objects and then pruning any that may be colliding. By default, the implementation details of a given Initializer are condensed into a "Simple View" which provides a summary of what that Initializer is doing. However, you may find yourself wanting to add or remove steps in an Initializer, tweak advanced parameters, reorder the execution of steps, or create a totally new Initializer from scratch. Here, you'll find more information on how to configure a custom Initializer to use in your simulation.

In configuring a custom Initializer, you may want to do any of the following:

• Select specific assets to spawn or modify
• Filter the valid assets to grab only a desired subset
• Choose custom or different Operations to execute
• Change the order in which the Steps run

We'll take an in-depth look at customizing an Initializer by describing the process of building one from scratch—but note that you can always just edit an existing Initializer rather than always needing to build a new one!

Create the Initializer

Each Initializer encapsulates an Initializer Plan which is composed of an ordered list of Steps that define its functionality. Any given Initializer works on one specific Asset Source and one specific Region, defined within the scope of that Initializer's Plan. Each Step within the Plan will select from among objects defined in the Plan's Asset Source and, in some cases, new objects created in previous Steps of the Plan, and perform an Operation on that specific set of objects.

• Start by creating a new GameObject in your scene, and add the Scene Initializer component

The Scene Initializer is the central component that has everything you'll need to set up and run an Initializer. It starts in the "Simple View," which lets you select a pre-configured Initializer from a dropdown, and modify only the necessary values before running. To set up our own steps from scratch, let's dig into the details.

• Uncheck Show Simple View to reveal the Initializer Plan hierarchy. Click the ▶ to expand it

Choose Your Assets

You'll see a series of empty fields relating to asset selection and an empty list of steps. All of the initializing actions need to choose whether they apply to assets that are in the scene or not yet in the scene.

• In the expanded Initializer Plan, expand the dropdown for Asset Source Mode. Select the mode that best encompasses the objects you want to affect:

  • Entire Scene: Grabs all the applicable objects in the currently loaded environment
  • Region: Finds all the applicable objects enclosed by a defined geometry (represented by the Region Spline components)
  • Asset Group: Selects all applicable assets from disk, defined by an Asset Group

• If you've selected the Asset Group mode, assign your configured group to the Asset Group field

• If you've selected the Region mode, add a Region component to this Initializer object. You'll note that a new Region GameObject has been added as a child and assigned in the Splines list on the Region component

More on Asset Selection

For more information on setting up the Region or Asset Group, check out the Configure the Asset Selection guide.

Set up Steps

Next, we can configure the steps that will execute sequentially.

• Expand the Steps list if it isn't already open, and click the + to start adding a step

Choose Subsets of Assets

This is where you can configure a subset of the selected assets via an Asset Selector Parameter and Asset Filters, and choose an Operation to run.

• Expand the** Assets to Use:** dropdown and select your chosen parameter
  • Newly Spawned Assets: Creates newly spawned clones randomly selected from the assets in the Asset Source, which can either be objects in the scene, or assets on disk. Will continue to spawn new clones indefinitely until the Operation terminates
  • Random Number of Newly Spawned Assets: Creates n newly spawned clones of randomly selected assets from the asset source, which can either be objects in the scene, or assets on disk, where n is randomly selected from a configurable range
  • All Placed: Use all objects that have been placed in the scene so far by this Initializer
  • All Colliding Clones in Region: Select any cloned in-scene objects in the Region that are overlapping within the area over the defined allowance. The cloned objects must have the substring (Clone) in their names
  • All in Region: Select all in-scene objects found in the Region (even those not placed by this Initializer)
  • Percent in Region: Select a subset of the in-scene objects in the Region, totaling the percent coverage defined
  • Random in Region: Select n number of of in-scene objects in the Region, where n is randomly selected from a configurable range

Once set, you can optionally configure a list of filters for the assets as well. Note that some asset parameters include some filters by default, like All Colliding Clones in Region adding an object name filter and a collision allowance threshold.

• After adding a filter, you can first select a Filter Mode, and then configure the filter with the given field(s)
  • Contains in Name: Checks if the Filter String is contained in the GameObject name
  • Is Colliding: Checks if GameObjects are overlapping over the Collision Allowance

Select an Operation

Now, you've successfully configured the set of objects you want to operate on. Now, you can select which action you want to take on these objects!

• Expand the Operation: dropdown and select your desired Operation
  • Reset Transform: Sets each object's position to Vector3.zero, the rotation to Quaternion.identity, and the local scale to Vector3.one
  • Use Global Position and Rotation: Sets each object's position and rotation to match the Region's position and rotation
  • Wiggle Randomly: Slightly shifts and rotates each object by a small, defined position and rotation
  • Place Using Poisson Disk Sampling: Sample positions evenly but randomly using the Poisson Disk Sampling method, and place objects at those positions
  • Prune: Safely remove the objects from the scene

You can add as many steps as needed here! You can also reorder and reconfigure these steps at any time, or even add custom-written Operations by following the Write a New Operation guide.

Once you're satisfied with your configuration, you're ready to run your customized Initializer!

• Click Execute Plan to run all of the steps of your Initializer!

Glossary

Asset Filter: a rule to define how to select a subset of objects from a larger group of objects

Asset Group: a container (ScriptableObject) for assets, used for grabbing assets from disk (usually used for spawning objects)

Initializer: a script which executes a pre-defined list of Operations on a Region in the scene

Initializer Plan: the structure defining an Initializer's functionality; a container for an ordered list of Steps

Operation: an action that can be executed on an arbitrary set of GameObjects

Region: a collection of boundaries in the scene which define the space within which an Initializer can act

Step: a container binding specific asset selection parameters to an Operation