GameObjects and components

Forma relies on several GameObjects and components that you must use to set up the system to create configurators.

Configurator

In Unity Forma architecture, the Configurator is the top GameObject in your Unity project. The Configurator GameObject has several components and a specific hierarchy. They include:

• References to runtime components. These include the ConfigurationManager and the Switcher.
• The Product data model.
• Settings for choosing different Provider engines.
• Staging settings the multiple Products share.

You can attach additional metadata at the Configurator level, such as company, brand, and version information.

Configurator GameObject

Components

Property	Description
Transform	(No specific use)
Configurator	Instantiates the product. See Configurator component, below.
State Conductor	State conductor
Product Preview	Lets you preview the product in your Scene as it appears when you edit it. See Product Preview component.
Configurator Settings	See Configurator Settings component

Child GameObjects

GameObject	Description
Staging Manager	The Staging manager.
Switcher	The Switcher.
Spawn Point	Materializes the coordinates where the 3D model of the product instantiates in the scene. The Configurator instantiates the Product under this GameObject.
RuntimeUICreator	The Runtime UI creator.
IRuleEngine	The Rule Engine that defines Variant logic.
IPricingEngine	The Pricing Engine.
IInfoEngine	The Analytics Engine.

Configurator component

The Configurator component instantiates the product that the Configurator Settings component references. If the Product exists in your scene, you can find it under the Spawn Point GameObject in the Configurator GameObject hierarchy.

Properties

Property	Description
Debug Mode	Enable this option to show hidden Configurator elements that are useful for debugging.
Settings	A link to the Configurator Settings script component.
Staging Settings	Staging settings
Spawn Point	A link to the Configurator Spawn Point GameObject.
Splashscreen Prefab	A link to a Prefab that the configurator will use as a loading screen. To use the default Unity Spashscreen Prefab, see Templates
Export Settings	See Export settings

Buttons

Button	Description
Open Catalog Setup	Opens the Unity Forma interface.

Product Preview component

Add the Product Preview component to the same object where the Configurator Component exists. It instantiates a Product in your scene while you are in Edit mode.

Properties

Property	Description
Auto Load Product	Enable to make Forma automatically load the Product in your Scene. It can be useful to disable this property if your product is large or you are working on an environment.
Remove On Build	Enable to make sure that Forma removes the Product in the Preview before it builds the configurator application. Removing on build lets you create builds without a Product so that the configurator can load all Products as Addressable Assets
Unload Before Play	Enable to automatically unload the Product Preview before you switch from Edit mode to Play mode. This property is useful if you want to replicate the same environment that the consumer will see. If the Product is Dirty, the system saves it before it unloads the Preview. If your product is large, this can increase the time it takes to switch modes.
Product Dropdown	Use dropdown to select a Product to preview.

Configurator Settings component

The Configurator Settings component lets you customize different behaviors in the application and set default behaviors. Before you build a project, Forma moves the Configurator Settings component to an Addressable Asset Prefab so that you can export them separately as a Products Only build.

Configurator Settings properties are organized into these sections:

• Product Prefabs
• Provider Engines
• Runtime UI
• Export Settings

Product Prefabs

The Product Prefabs property lists the different Product Prefabs that the configurator uses. Any Product Prefab in the list must conform to requirements in the Product.

Provider Engines

The Provider Engines property lets you link to different Provider Engines that the configurator will use to relay information selections and products to the consumer in response to requests from Forma. Provider Engines offer extensibility that lets you customize the behavior of the configurator.

Property	Description
Rule Engine	Link to the Prefab that implements your Rule Engine. The Prefab must include a script component that implements the IRuleEngine programming interface. Note: By default, the Configurator uses the DummyRuleEngine, which does not let consumers make configuration changes.
Runtime UI Data Engine	Link to the Prefab that implements your Runtime UI Data Engine. The Prefab must include a script component that implements the IInfoEngine programming interface.
Pricing Engine	Link to the Prefab that implements your Pricing Engine. The Prefab must include a script component that implements the IPricingEngine programming interface.
Analytics Engine	Link to the Prefab that implements your Analytics Engine. The Prefab must include a script component that implements the IAnalyticsEngine programming interface.

Runtime UI

Use Runtime UI properties to configure the Runtime UI that the Configurator uses. See Runtime UI.

Property	Description
Create Runtime UI	Note: Other Runtime UI properties are only displayed when Create Runtime UI is selected.
Runtime UI Data Engine	The Runtime UI data engine you want to use.
Pricing Engine	The pricing engine.
Analytics Engine	The analytics engine you want to use.

Export Settings

Property	Description
Export Profiles	List of Export Profiles that define different export and build properties.

Product

The Product GameObject lets you define Product that consumers will customize in the configurator. For convenience, it features the following:

• A Nested Prefab that lets you re-import a Product.
• A Debug Mode for inspecting the Variant Table. (Use the API to make changes to the Variant Table.)
• Staging overrides let you set Environment, Camera, and Animation settings for an individual Product. Forma adds or replaces Staging settings with the Product Settings when it builds the configurator.
• Addressables
• Controls for setting the position of the Product in the Environment (the Spawn Point).
• Controls for setting different Hotspots on the Product and defining what the configurator shows for each.
• A component for defining the default configuration of the Product in the configurator.

Product Prefab

Product Component

Component	Description
Transform	The transform for the Prefab component.
Product	See Product Component

Prefab child GameObjects

Component	Description
Variant Table	Defines and stores all Variants for a Product. See Variant Table.
Context Collection	Regroups and defines the schema for Contexts. See Context Collection.
Spawn Point	Coordinates where the center of the Product will materialize in a Scene. Forma matches the coordinates of the Product Prefab spawn point with the coordinates you specifiy for the Configurator.
Presets	Specify different configuration presets that you can save for a Product. No other components use the presets.
Defaults	Default configurations specify the initial state of the product in a given Context. For each Context, specify the default configuration for the Product. You must set a default configuration for each Context. Typically, consumers do not select all Variants that you define for a Product; they open the configurator to see a default configuration and make selections to customize the Product further.

Properties

Property	Description
Staging Settings	Specify staging settings specific to the Product. Forma merges them with Staging settings you define for the Configurator when your product is instantiated. Specifying separate settings for the Product and the Configurator lets you add or override Camera Views or the Environment for a Product.
Debug Mode	Enable to show hidden elements that are useful when you need to debug your Product.
CAD Prefab	Optional
Spawn Point	Link to the Product Spawn Point GameObject.
Is Dirty	For internal use only (Specifies when there are modifications to the file that the system needs to Save.)

Buttons

Button	Description
Open Product Settings	Opens the Forma interface (Product Setup section).
Create Defualt	If you have not yet defined a default configuration for the Product, this button creates a default configuration in the Product. The button does not appear if you have already defined a default configuration.

Variant Table

The Variant Table stores definitions of any Variant you create. It defines the different aspects of your product that consumers can interact with or customize.

The Variant Table does not contain Product logic. To define the logic that determines when different Variants are visible or available to the Consumer, you must use a Rule Engine.

Variant Table GameObject and component

Variant Table component

Properties

Property	Description
Feature Sets	List of feature sets that can be either Variant Sets or Pack Sets.
Packs	List of Packs.
Force Standard Configuration	Enable to force all configurations to use a standard validation. Valid configurations have a default Variant selected in each Variant Set.

Variant Table GameObject hierarchy

The Variant Table GameObject has the following hierarchy of child GameObjects:

• Variant Set 1
  • Variant 1
    • Assignment (2 types: Material or Visibility)
      • Static Query Node (2 types: Material or Boolean)
      • Static List Query Node (2 types: material slot or GameObject)
  • Variant 2
  • Variant 3
  • ...
• Variant Set 2
• Variant Set 3
• …

Variant Table child GameObject types

Property	Description	Cardinality
Variant Set	Direct child of the Variant Table GameObject.	Unlimited
Variant	Direct child of the Variant Set GameObject	Unlimited
Material Assignment	Direct Child of a Variant GameObject when the Variant is a Material Variant	There can be only one Assignment GameObject per Variant GameObject
Visibility Variant	Direct child of a Variant GameObject when the Variant is a Visibility Variant	There can be only one Assignment GameObject per Variant Game Object.
Static Material Query Node	Direct child of a Material Assignment GameObject.	There can be only one Static Material Query Node GameObject per Material Assignment GameObject.
Static Bool Query Node	Direct child of a Visibility Assignment GameObject.	there can be only one Static Bool Query Node GameObject per Visibility Assignment GameObject.
Static List Material Slot Query Node	Direct child of a Material Assignment GameObject.	There can be only one static List Material Slot Query Node GameObject per Material Assignment GameObject.
Static List GameObject Query Node	Direct child of a Visibility Assignment GameObject.	There can be only one Static List GameOBject Query Node GameObject per Visibility Assignment GameObject.

Variant Set GameObject and component

The Variant Set GameObject includes a single Variant Set component. It also includes a Transform component which is for internal use only.

Properties

Property	Description
Label	Enter a label for the Variant Set.
Features	List features (Variants) in this Variant Set.
Selected Feature	The currently selected Variant for this Variant Set (Read-only Variant that cannot be modified manually.)

Variant GameObject and component

A Variant defines a single characteristic of a product. For example, in a Car configurator, you might create different Variants for a seat, a rim, a car paint color, a seat type, or a material. Variants represent marketing concepts and do not always correspond to engineering concepts in the Product. A single Variant might include several different manufactured parts and a material defintion that are all identified by a single marketing code.

Each Variant has Assigments that are made from a Value Query and a Target Query.

For information about creating custom Assignments and queries to support your configurator, see Variant Extensibility

Properties

Property	Description
Code	A string that uniquely identifies the Variant in the Configurator.
Feature Set	The feature set.
Assignments	List Assignments for this Variant

Material Variant

A Material Variant is a Variant that has only Material Assignments.

The system does not prevent you from adding Visibility or Custom Assignments to Material Variants.

Visibility Variant

A Visibility Variant is a Variant that has only Visibility Assignments.

The system does not prevent you from adding Material or custom assignments to Visibility Variants.

Variant Extensibility

Variants and the GameObjects associated with them (Variant Sets, Assignments, Queries, etc.) are extensible. You can extend them to support your own configurator requirements.

By default, Unity Forma only offers Material and Visibility Variants, and their related queries. The system is designed to let you create custom queries that meet the needs of your Variant Table.

Assignment GameObject and components

Assignments connect Variants to GameObjects in the Configurator. Each Assignment has the following:

• A target that indicates the objects that the Assignment affects.
• The values each object will have
• The type of Assignment (Visibility, Material, etc.)

The behavior of each Assignment corresponds to the following principle:

'Variant V will assign Value A to GameObjectX'

A Variant can have several Assignments that let it influence GameObjects in different ways. An Assignment can also have multiple targets. For example, you can assign one car paint material to multple car paint GameObjects.

By default, Forma supports Assignments that manipulate materials and visibility. If you need an Assignment to manipulate other GameObject properties, you can extend the class Assignment.

Properties

Property	Description
Target Query	The target query that fetches the target objects for this Assignment.
Value Query	The value query that the system applies to target objects for this Assignment, such as a Material or Visibility Boolean value.

Material Assignment

Material Assigments handle Material Values and specifically manipulate the material that the system assigns to a GameObject.

A Material Assignment applies a value query that returns a material to a target query. The target query returns a list of render slots and acts as a renderer with a material index.

Visibility Assignment

Visibility Assignments manipulate the Visible status of a GameObject. They handle Boolean values (on/off).

A Visibility Assignment is an Assignment type that sets the target query objects to the value of a value query, such as on or off.

Query Node GameObject

QueryNodes let you populate the target and value fields of an Assignment.

There are different strategies for determining which geometries a Variant affects, including the following:

• You can define a placeholder Material (such as a Target Look in DeltaGen).
• You can directly assign items to a VariantTable
• You can use metadata to associate different items with a VariantTable

QueryNodes are designed to support each strategy. By writing custom QueryNodes you can query GameObjects for almost any type of property and define matching criteria, such as name, placeholder material, metadata, hierarchy position, and more. You can use the results of the query as a target or value for the Assignment.

Examples of queries can include:

• 'Get GameObjects with assigned material t_carpaint'
• 'Get GameObjects whose name contains "PN23_"'
• 'Get GameObjects whose name satisfies the regular expression "^PN2[0-9]"'
• 'Get the first child of each GameObject whose name ...'

TargetQueryNode

Target QueryNodes return a collection of GameObjects. You can extend the class with a different mechanisms that return GameObjects (see Examples above.)

ValueQueryNode (generic)

ValueQueryNode is a generic class type. Different Assignments can manipulate different value types (Boolean for VisibilityAssigment, Material for MaterialAssignment, and so on). ValueQueryNodes can also return values that use any kind of algorithm you compose, including a static selection.

Refreshing queries and static queries

Queries are typically dynamic and can be refreshed so that they update the list of results (for example, as consequence of project updates).

To make the queries static, you can assign a GameObject to a QueryNode in a direct, static way. The queries are no longer dynamic or refreshable and they become static.

Context collection

The Context Collection GameObject groups and defines a schema for contexts.

Context collection GameObject

Components

Component	Description
Transform	(Internal use only)
ContextCollection	See Context Collection

Child GameObject hierarchy

Context Collection component

Properties

Property	Description
Contexts	List of Contexts
Keys	The schema for each Context

Because a Context is only a series of data without meaning for each element, you use the Context Collection Keys attribute to give each Context meaning. Each Key represents the meaning of each Context value, in the same order .

For example:

Context Collection Key	Context value	Meaning
Element 0: "Engine"	Element 0: "V8"	V8 is an Engine
Element 1: "Market"	Element 1:"United Kingdom"	The market is the United Kingdom

Context GameObject and component

A Context is a series of your own custom data that various components in the Configurator can use to determine behavior. Alone, Contexts do not have a function.

The runtime UI typically sets each Context to add extra information about the user or the user environment to the Configurator.

The Rule Engine can use Contexts to determine which features are available to a user. Other Provider Engines can also use Contexts.

A Configurator project typically contains a complete dataset (150% model) for each Product. The dataset includes Variants that are available under very different conditions, and for different markets.

For example, a right-hand drive steering wheel and a left-hand drive steering wheel would be available for different markets.

The dataset can even account for different product lines, such as a sedan and convertable.

The initial state of the product (the default configuration) cannot be the same for each of Context. For each market or product line, you need to specify a different default configuration.

Contexts let you select groups of features that uniquely identify a subset of a product, such as the number of doors, engine type, transmission, fuel, and more. They let you create default configurations by linking each to a different Context.

Component overview

Properties

Property	Description
values	List of data points. You define the meaning at each index of a Context in the Context Collection

Configuration

A Configuration arranges Product Variants so that the configurator can easily recall them.

Configurations are exceptionally useful when:

• A Product has a default Configuration (for example, a car with basic features and white car paint).
• A Product has specialty (hero) shots that are designed to arrange different Variants in an appealing way for marketing purposes.
• A consumer defines a configuration to open later.

Configurations cluster Product Variants and let you switch between them without needing to set each Variant again.

Runtime UI

The Runtime UI is the user interface that the consumer sees with they open your configurator application.

Deployment

Deployment describes the process of building your configurator and publishing it to a target destination where consumers can access it.

Export settings

You can define distinct builds for the different platforms and devices, and different quality profiles to respond to the resolution settings on consumer devices.

Note: You can only see Addressable Asset settings in the Unity Editor mode. (They are not available from the Forma interface.)

Working Platforms

Unity Forma supports exports to these platforms:

• Windows
• MacOS
• Linux
• Addressable Asset

Export - Addressable Assets (Products only)

You can update the Product data for the latest build only using the current platform config file (located in Assets/AddressableAssetsData/[Current_Platform]/addressables_content_state.bin.)

Forma does not generate a new executable file and the configurator creator must follow these steps:

1. Manually move new Addressable Asset files to the existing build.
2. If an instance is already running, relaunch the build to show new updated changes.

Forma creates new files under: [PROJECT PATH]/Library/com.unity.addressables/StreamingAssetsCopy/aa/[CURRENT_PLATFORM]/[BUILD_TARGET].

YOu must copy the new files to: [BUILD_PATH]/xxxxxxxxx_Data/StreamingAssets/aa/[CURRENT_PLATFORM]/[BUILD_TARGET]

Note: Each Addressable Asset Group has 4GB file size limit. By default, every Addressable resource goes into the Default Group.

Note: When you select the Product Only build, Forma does not compile new scripts. An Addressable Asset can be a Prefab, texture, material, audio clip, animiation, and more.

For more information, see Addressable Asset Hosting Services

Addressable Assets

Because Forma only lets you create executable builds, you can only deploy to locations where executables are supported.

User interface

The Forma user interface is an application that runs on top of the Unity Editor. For some tasks, you need to switch between the Unity Editor and the Forma interface.

To change interfaces, go to the Forma menu and a select Toggle Mode.

Extending

You can extend several features in Unity Forma.

Runtime UI

To customize the Runtime UI, you can do one of these things:

• Customize Runtime UI resources
• Create your ow Runtime UI from scratch

Customizing the existing runtime UI

To specify your own custom resource provider for the Runtime UI or to select an object that implements the class 'ProductRuntimeUI', you can edit the Runtime UI section under Configurator Settings.

The Custom Resource Provider field lets you specify any assets that implement the iResourceProvider interface. The default runtime UI lets you use a CustomResource Privider property that you can use to customize the UI with Prefabs.

Creating your own runtime UI

To create your own custom UI, you can use the 'ProductRuntimeUI' abstract class. You can select the ProductRuntimeUI class in the Runtime UI Type field in the Configuration Settings.

Importer

To create a custom importer, use the following example package: https://unity3d.atlassian.net/browse/CC-491

Configuration change flow

This table shows the key parts of a Configuration change:

Actor	Actions
Runtime UI	Select feature User requests a change to a feauture, such as the paint color.
Configuration Manager	QueryConfigurationChangeValidity (Configuration change) The Configurator manager queries the Rule Engine to check if the Configuration is valid.
Rule Engine	QueryConfigurationChangeValidity(Product, Context, Configuration, ConfigurationChange) The Rule Engine verifies that the Configuration is valid and returns a list of availabilities for each modified Variant, Variant Set, or Pack.
Configuration Manager	ApplyVerifiedConfigurationChange(VerifiedConfigurationChange) The verified Configuration that the Rule Engine returns is applied to the current Configuration and all selected Variants are sent to be switched on or off.
Switcher	SwitchConfiguration(VerifiedConfigurationChange)
Assignment Switcher	Apply Assignment(Assignment) For each Variant Assigment, the Assignment Switcher selects: Custom Action Conceptually, the Assignments value is applied to the corresponding target. For a Material Assignment Switcher, the Material is applied to the object renderers.
Runtime UI	Update Feature Availabilities The Runtime UI uses variaous events to update feature availabilities and its state.