How to create a nested scene: Multi-Floor Building

If you nest configurators, and those configurators have 3D scenes, then you can choose to nest the scenes as well.  Nested scenes help you create complex visuals by combining simpler parts in a structured, easy-to-maintain way.  

This walkthrough will guide you step by step in building a complex nested scene from nested scenes.

Prerequisites

• You should already be familiar with creating a configurator, defining pages, groups, and fields, and creating simple value rules with Snap.
• You need a basic understanding of how to create a scene from scratch.
• You should have already completed the walkthrough How to create a nested configurator: Multi-Floor Building, as it is the starting point for this walkthrough.

Step-by-step guide

We'll follow these steps in creating our nested scenes:

Plan your design

Before starting work, review the requirements for the application.   

Our walkthrough will add visuals to an existing application that helps people configure their own building.  It can be a small retail store or a high-rise office tower... or anything in between.  That application is based on a nested setup, where a "Building" configurator can contain one or more "Building Floor" nested configurators.  Here, we will create the visuals for that application.

Adjust scene logic as necessary, so the scene elements work as expected

Design the parent scene

Design the child scene

The important requirements for us, during our visual design:

1. A building can have one or more floors.
2. Each floor has a "Use" which can be Residential (homes where people live), Commercial (offices where they work), or Retail (stores where they shop).
3. Each floor has a height property, defining how tall the floor is.

A good design habit is to maintain a 1-to-1 relationship between your configurator and your scene.  Remember that a scene can use information from the configurator it is related to, as well as from some other places.  But a good design habit is to ensure each scene represents the information found in the configurator or configurators that drive it, and no more.  For example, our "Building Floor" scene should show just information about the floor we are working on (for example, a visual representation of that floor's "Use" field, or the "Floor Height" field).  That floor scene will not show any other elements, such as contextual elements (like a tree that may be next to the building, or the street surrounding the building).  Those context elements are not part of the Building Floor, but part of the parent configurator, the Building itself.

There may be other attributes or changes that are needed to the configurators to support our scene.  We will discover those as we proceed.

Therefore, we will design:

1. A "Building Floor" scene, showing an individual floor.  We will represent that floor as a cube, with the intent that other floors will stack above and below it.
2. An object in the scene, representing the floor.  We'll use a simple primitive cube shape. 
3. The floor cube object will have a material which will change, depending on the "Use" field.  In this way, the floor will look different if it is Residential, Commercial, or Retail.
4. The floor cube object will have a dimension which will also change, depending on the "Floor Height" field.  By changing the floor height, the cube will represent a taller or shorter floor in the building.
5. The floor cube object will have a vertical position in the 3D space, based on a new "Floor Position" field we will add to the configurator.  
   
   
6. Another separate scene,"Building", showing the context for a building of 1 or more floors.  Since each floor is already represented, all we need to have in this scene are visual elements that are not part of any one floor.  For example, a tree that will stand next to the building, or a car parked by the building.  In this simple example, we will simply have...
7. An object in the scene, representing the ground the building is resting on.  We'll use a simple plane to represent the ground.  Adding other elements such as a tree or person are enhancements you can make on your own.
8. The ground object will have a material that will look like a street corner.

1. Create a new "Building Floor Scene" scene, and link it to your "Building Floor" configurator:
   
   
   
2. Create a new object to represent the floor by selecting Create > Polymesh > Box. 
3. In the Properties tab, name this new Box "thisFloor".
4. In the Properties tab, in the translation section, adjust the translation and scale of the cube to make it into a 20m x 20m building floor, and so that the bottom of the box rests on the origin plane.
   
   
   
5. Assign a material to the floor.  For example, by opening the Material Library bar below the ruler at the bottom of the scene admin window, and clicking "PBR Materials", and dragging a material onto the object.  Change the name of this material from "Physical" to something more descriptive, such as "FloorExterior".
6. Assign some lighting to the scene.  For example, again in the Material Library, click "HDR Environments" and double-click one of the environments.  You'll see many yellow blocks appear in your scene's material library.  There are other ways to implement lighting, of course, but here's a quick one.
7. Adjust your perspective camera: you may want to zoom it out, so you can see the entire floor.  For example, you can select the floor polymesh and then choose "View > Frame Selection" to adjust the camera.
8. Create a scene rule called "Set Floor Height", connecting the height of "thisFloor" to the correct configurator field:
   
   
   
9. Create another scene rule to make the Floor Material change its appearance, based on the use of the floor.  You can change the image or other techniques, but just to confirm the logic let's keep it simple and just change the color of the material:
   
   
   
10. Save your scene.  
11. Open your "Building Floor" configurator, and in the properties of the configurator set the viewer mode to "3D scene", and select your "Building Floor Scene"
    
    
    
12. Test your work by launching your "Building Floor" configurator.  You should see...
    1. a floor object appear in your scene,
    2. the height of the object change as you edit the Use field, and
    3. the material of the object change as you edit the Use field.
       

1. Create a new "Building Scene" scene, and link it to your "Building" configurator.
2. Create a new object to represent the ground by selecting Create > Polymesh > Plane. 
3. In the Properties tab, name this new Plane "thisStreet".
4. In the Properties tab, in the PolyMesh section, set the width and height of the plane to about 40, so it's larger than the building.  The plane is already positioned at the origin, so we don't need to translate it up or down.
5. Open your "Building" configurator, and adjust its properties so the viewer shows the "Building Scene".  Also, add the "Building Floor Scene" to the list of referenced scenes. This helps ensure that your nested scenes are pre-loaded and cached before they are needed.
   
   
   

Nest the scenes in the parent configurator

Test your work: if you launch your building configurator, you should now see your "Building Scene" scene with its "thisStreet" plane rendered.  Also, you should see your "thisFloor" object appear as well from your "Building Floor" scene.  Why does it appear here?  Since you nested the Building Floor configurator into your Building configurator, the scene is nested as well by default.

To turn scene nesting on or off, in your parent configurator edit the "Referenced Configurator" entry you created: edit the checkbox next to "Nest scenes".  In this walkthrough, we will leave the checkmark true.

Currently, there is no logic to set the position of each floor in the merged 3D scene.  So, regardless of if we have 2 stories or 20, they will all appear at ground level.  Let's fix that.

1. In the child Building Floor configurator, add a "Floor Position" number field, which will store the vertical position of this configurator in space.  While each child configurator may not know how to calculate this number, each child is at least responsible for storing this information about itself.
   
2. In the parent Building configurator, Add a "Set Nested Floor Position" value rule, which will loop through each floor setting it's Floor Position variable correctly.
   
   
   
3. Now that each floor has a position in space defined, let's use that info in our scene to position the floor.  In the Building Floor scene, add a new scene rule "Set Floor Position" that will use this Floor Position to set the translation of thisFloor in space.
   

After those 3 changes, you now should see each floor in the scene be positioned to the correct location in space.  (In our scene below, we added a car for scale.)

Tip

You may have noticed that the Building Floor configurator already has another rule, "Set Building Height", which loops through all the nested children to determine the overall building height.  We can add one line of code to that loop to have it set the Floor Position field in each child configurator:

So, given these two design patterns, you may wonder which is best – having separate rules go through their own loops (which is easier to maintain as a programmer), or packing as much logic into an existing rule (which has fewer overall lines of code and may run faster). Usually, it's best to try to optimize for ease of maintenance: separate your tasks into independent rules, so the code is easier to maintain.  If you do decide to combine tasks into one rule, remember to comment your work and rename the rule accordingly.