
The babylon scene manager extension provides runtime life cycle management for game objects. The extension supports a scene component application programming interface to enable the usage of **modern game mechanics** to ease web browser game development and provide a **native game editor style development** experience simular to native [Unity](https://www.unity3d.com/) and [Unreal Engine](https://www.unrealengine.com/) game development.

## Babylon Scene Manager

The [Scene Manager](https://github.com/BabylonJS/Extensions/tree/master/SceneManager) is packaged with latest toolkit extension but is availble on github for download and customization. You can preview the latest stable [TypeScript Definitions](https://github.com/BabylonJS/UnityExporter/blob/master/Manager/babylon.manager.d.ts) file. To use a custom build you must copy your new output files to your project's **Assets > Babylon > Library** folder as:

- **babylon.manager.bjs** - Scene manager compiled javascript output file renamed to .bjs extension

- **babylon.manager.d.ts** - Scene manager application programming interface script definition file

## Babylon Scene Controller

The scene controller script is designed to be used as the main entry point and logic controller for the specified scene. The scene contoller exposes and addition life cyle function called **Ready** that gets called during the scene loading **Execute When Ready** stage. This is the ideal place for main scene setup code that runs **before** the game render loop is started. The scene controller is a sub class of **BABYLON.MeshComponent** and should be used on a single empty game object in the scene.

Example scene controller script file:

```javascript
    module PROJECT {
        export class NewSceneController extends BABYLON.MeshComponent {
            public constructor(owner: BABYLON.AbstractMesh, scene: BABYLON.Scene, tick: boolean = true, propertyBag: any = {}) {
                super(owner, scene, tick, propertyBag);
            }

            protected ready() :void {
                // Scene execute when ready
            }

            protected start() :void {
                // Start component function
            }

            protected update() :void {
                // Update render loop function
            }

            protected after() :void {
                // After render loop function
            }

            protected destroy() :void {
                // Destroy component function
            }
        }
    }
```

## Babylon Scene Components

Managed scene components provide modern game mechanic helper functions to ease web game development. Some notable toolkit managed scene component examples:

**GetProperty** - Gets a property from the attached editor script component.

```javascript
    module PROJECT {
        export class TestMeshComponent extends BABYLON.MeshComponent {

            protected start() :void {
                var hello:string = this.getProperty("hello", "Default Value");
                console.log("Echo Hello: " + hello);
            }
        }
    }
```

**GetComponent** - Get a reference to another component attached to the owner object.

```javascript
    module PROJECT {
        export class TestMeshComponent extends BABYLON.MeshComponent {

            protected start() :void {
                var animator:BABYLON.AnimationState = this.getComponent("BABYLON.AnimationState");
                if (animator) console.log("Echo Owner: " + animator.owned.name);
            }
        }
    }
```

**GetUserInput** - Get the **local multiplayer** user input from the scene manager for the specified input axis.

```javascript
    module PROJECT {
        export class TestMeshComponent extends BABYLON.MeshComponent {

            protected update() :void {
                var vertical:number = this.manager.getUserInput(BABYLON.UserInputAxis.Vertical, BABYLON.PlayerNumber.One);
                var horizontal:number = this.manager.getUserInput(BABYLON.UserInputAxis.Horizontal, BABYLON.PlayerNumber.One);
                console.log("Echo Input: " + vertical.toString() + " x " + horizontal.toString());
            }
        }
    }
```

## Mesh Script Components

The mesh component script is to be used by **All Non Light And Camera** game objects. The component provides access to the owner mesh via its **BABYLON.AbtractMesh** property:

```javascript
    module PROJECT {
        export class NewMeshComponent extends BABYLON.MeshComponent {

            protected start() :void {
                console.log("Starting mesh component for owner: " + this.mesh.name);
            }
        }
    }
```

## Light Script Components

The light component script is to be used on **Light** game objects **Only**. The component provides runtime access to the owner light via its **BABYLON.Light** property.

```javascript
    module PROJECT {
        export class NewLightComponent extends BABYLON.LightComponent {

            protected start() :void {
                console.log("Starting light component for owner: " + this.light.name);
            }
        }
    }
```

## Camera Script Components

The camera component script is to be used on **Camera** game objects **Only**. The component provides runtime access to the owner camera via its **BABYLON.Camera** property.

```javascript
    module PROJECT {
        export class NewCameraComponent extends BABYLON.CameraComponent {

            protected start() :void {
                console.log("Starting camera component for owner: " + this.camera.name);
            }
        }
    }
```

## Babylon Global Script Files

Global scripts enable inline global function for all scenes in the project. The global application script can also be used to capture window load and scene exeute when ready events for the entire project.

Example global startup script:

```javascript
BABYLON.SceneManager.OnWindowLoad(() => {
  // Global Page Loaded Handler
});

BABYLON.SceneManager.ExecuteWhenReady((scene: BABYLON.Scene, manager: BABYLON.SceneManager) => {
  // Global Scene Ready Handler
});
```



There is a close relationship between **Materials**, **Shaders** and **Textures** within a game engine render pipeline:

- **Materials** are definitions of how a surface should be rendered, including references to textures used, tiling information, colour tints and more. The available options for a material depend on which shader the material is using.

- **Shaders** are small scripts that contain the mathematical calculations and algorithms for calculating the colour of each pixel rendered, based on the lighting input and the Material configuration.

- **Textures** are bitmap images. A Material may contain references to textures, so that the Material’s shader can use the textures while calculating the surface colour of an object. In addition to basic colour (albedo) of an obejct’s surface, textures can represent many other aspects of a material’s surface such as its reflectivity or roughness.

A material specifies one specific shader to use, and the shader used determines which options are available in the material. A shader specifies one or more textures variables that it expects to use, and the Material Inspector in Unity allows you to assign your own texture assets to these these texture variables.

For most normal rendering - by which we mean characters, scenery, environments, solid and transparent objects, hard and soft surfaces etc., the Standard Shader is usually the best choice. This is a highly customisable shader which is capable of rendering many types of surface in a highly realistic way. You may choose the **Babylon Standard Material** shader for a legacy diffuse workflow.

Please refer to the [Unity Material](https://docs.unity3d.com/Manual/class-Material.html) documentation for details.

## Creating And Using Shader Materials

To create a new Material, use **Assets > Create > Material** from the main menu or the Project View context menu.

By default, new materials are assigned the **Standard Shader**, with all map properties empty, like this:

![Standard Shader](/img/exporters/unity/material.jpg)

Once the Material has been created, you can apply it to an object and tweak all of its properties in the Inspector. To apply it to an object, just drag it from the Project View to any object in the Scene or Hierarchy.

## Set Shader Material Properties

You can select which Shader you want any particular Material to use. Simply expand the Shader drop-down in the Inspector, and choose your new Shader. The Shader you choose will dictate the available properties to change. The properties can be colors, sliders, textures, numbers, or vectors. If you have applied the Material to an active object in the Scene, you will see your property changes applied to the object in real-time.

There are two ways to apply a Texture to a property.

- Drag it from the Project View on top of the Texture square

- Click the Select button, and choose the texture from the drop-down list that appears

## Unity Shader Technical Details

A Shader is a script which contains mathematical calculations and algorithms for how the pixels on the surface of a model should look. The standard shader performs complex and realistic lighting calculations. Other shaders may use simpler or different calculations to show different results. Within any given Shader are a number of properties which can be given values by a Material using that shader. These properties can be numbers, colours definitions or textures, which appear in the inspector when viewing a Material. Materials are then used by Renderer components attached to Game Objects, to render each Game Object’s mesh.

It is possible and often desirable to have several different Materials which may reference the same textures. These materials may also use the same or different shaders, depending on the requirements.

Below is an example of a possible set-up combination using three materials, two shaders and one texture.

![Material Diagram](/img/exporters/unity/diagram.jpg)

In the diagram we have a red car and a blue car. Both models use a separate material for the bodywork, “Red car material” and “Blue car material” respectively.

Both these bodywork materials use the same custom shader, “Carbody Shader”. A custom shader may be used because the shader adds extra features specifically for the cars, such as metallic sparkly rendering, or perhaps has a custom damage masking feature.

Each car body material has a reference to the “Car Texture”, which is a texture map containing all the details of the bodywork, without a specific paint colour.

The Carbody shader also accepts a tint colour, which is set to a different colour for the red and blue cars, giving each car a different look while using a single texture for both of them.

The car wheel models use a separate material again, but this time both cars share the same material for their wheels, as the wheels do not differ on each car. The wheel material uses the Standard Shader, and has a reference again to the Car Texture.

Notice how the car texture contains details for the bodywork and wheels - this is a texture atlas, meaning different parts of the texture image are explicitly mapped to different parts of the model.

Even though the bodywork materials are using a texture that also contains the wheel image, the wheel does not appear on the body because that part of the texture is not mapped to the bodywork geometry.

Similarly, the wheel material is using the same texture, which has bodywork detail in it. The bodywork detail does not appear on the wheel, because only the portion of the texture showing the wheel detail is mapped to the wheel geometry.

This mapping is done by the 3D artist in an external 3d application, and is called “UV mapping”.

To be more specific, a Shader defines:

The method to render an object. This includes code and mathematical calculations that may include the angles of light sources, the viewing angle, and any other relevant calculations. Shaders can also specify different methods depending on the graphics hardware of the end user.
The parameters that can be customised in the material inspector, such as texture maps, colours and numeric values.
A Material defines:

Which shader to use for rendering this material.
The specific values for the shader’s parameters - such as which texture maps, the colour and numeric values to use.
Custom Shaders are meant to be written by graphics programmers. They are created using the GLSL shader language, which is quite simple. However, getting a shader to work well on a variety graphics cards is an involved job and requires a fairly comprehensive knowledge of how graphics cards work.

## Babylon Shader Material Pipeline

## Physical Based Rendering

The **BABYLON.PBRMaterial** is the default shader material that will be used for **all** materials using **Unity Standard Shader** pipeline properties. These include the built-in Standard, Standard Roughness, Standard Specular and **any** other shader that uses **Metallic Type** properties (IE: \_Metallic).

## Diffuse Shader Materials

The **BABYLON.StandardMaterial** is used as the base shader for **all non** physical babsed rendering shaders. During exportation, the toolkit will **scrape** all materials looking for standard shader properties like **\_MainTex** and assign them to the standard diffuse shader pipeline.

## Custom Shader Materials

Custom shader materials creates a custom unity shader (.shader) program for use as the design time shader. You can change the content of the unity design time as it is only used for design time _ **WYSIWYG** _ display purposes. The actual **Shader Controller** class defines the native babylon shader material class to control the material export.

You can create a custom shader material from the **Create** menu at the top left of the Project panel or by selecting **Assets > Create > Babylon > Custom Shader Material** from the main menu.

Example library **Water Material** shader asset:

```
    Shader "Babylon/Library Materials/Water Material"
    {
        Properties {
            _WaterColor("Main Color", Color) = (0.1, 0.1, 0.6,1.0)
            _BumpMap("Normal Map", 2D) = "bump" {}
            _TagIndex("Tag Index", Int) = 0
            _WindForce("Wind Force", Float) = 6
            _WaveSpeed("Wave Speed", Float) = 1.0
            _WaveLength("Wave Length", Float) = 0.1
            _WaveHeight("Wave Height", Float) = 0.4
            _BumpHeight("Bump Height", Float) = 0.4
            _ColorBlendFactor("Blend Factor", Float) = 0.2
            _SecondBlendFactor("Second Factor", Float) = 0.2
            _WindDirectionX("Wind Direction X", Float) = 0.0
            _WindDirectionY("Wind Direction Y", Float) = 1.0
            _SecondColor("Secondary Color", Color) = (0.1, 0.1, 0.6,1.0)
            _SpecColor("Specular Color", Color) = (0.0,0.0,0.0,1.0)
            _Shininess("Specular Power", Range(0.0, 1.0)) = 0.5
            _Color("Diffuse Color", Color) = (1.0,1.0,1.0,1.0)

            [ToggleOff] _Wireframe("Show Wireframe", Int) = 0
            [ToggleOff] _BackFaceCulling("Back Face Culling", Int) = 1
            [ToggleOff] _DisableLighting("Disable Surface Lighting", Int) = 0
            _MaxSimultaneousLights("Max Simultaneous Lights", Int) = 4

            [HideInInspector] _MainTex ("Base (RGB)", 2D) = "white" {}
        }

        CGINCLUDE
        #ifdef BABYLON_INFO
            controller: "BABYLON.WaterMaterialController"
        #endif //BABYLON_INFO_END
        ENDCG

        SubShader {
            Tags { "RenderType"="Opaque" }
            LOD 300

            CGPROGRAM
            #pragma surface surf Lambert

            sampler2D _MainTex;
            sampler2D _BumpMap;
            fixed4 _WaterColor;

            struct Input {
                float2 uv_MainTex;
                float2 uv_BumpMap;
            };

            void surf (Input IN, inout SurfaceOutput o) {
                o.Albedo = _WaterColor.rgb;
                o.Alpha = _WaterColor.a;
                o.Normal = UnpackNormal(tex2D(_BumpMap, IN.uv_BumpMap));
            }
            ENDCG
        }
        FallBack "Legacy Shaders/Diffuse"
    }
```

The **CGINCLUDE** section defines that native **BABYLON.PushMaterial** shader controller sub class:

```
 CGINCLUDE #ifdef BABYLON_INFO controller: "BABYLON.WaterMaterialController" #endif //BABYLON_INFO_END ENDCG`

```

## Shader Controller Scripts

The shader controller class is used to interface between the Unity Material inspector properties and the native **BABYLON.PushMaterial** sub class properties. The controller class uses the shader properties specfied in the custom shader material (.shader) asset. It reads the properties from the material inspector properties and assigns them to the native shader material properties.

You can create a custom shader controller script from the **Create** menu at the top left of the Project panel or by selecting **Assets > Create > Babylon > Babylon TypeScript > Shader Controller** from the main menu.

Example library **Water Material** shader controller with life cycle:

```javascript
module BABYLON {
    export class WaterMaterialController extends BABYLON.WaterMaterial {
        constructor(name: string, scene: Scene, public renderTargetSize: Vector2 = new Vector2(512, 512)) {
            super(name, scene, renderTargetSize);
            this.initializeInstance();
        }

        protected start() :void {
            var meshes:BABYLON.Mesh[] = this.getScene().getMeshesByTags(this.getWaterTagLabel());
            if (meshes != null && meshes.length > 0) {
                meshes.forEach(mesh => {
                    this.addToRenderList(mesh);
                });
            }
        }

        /* Shader Material Water Tag Functions */

        private _waterTagLabel:string = "WATER_TAG_0";
        protected getWaterTagLabel():string {
            return this._waterTagLabel;
        }
        protected setWaterTagIndex(index:number) : void {
            var tagIndex = (index >= 0) ? index : 0;
            this._waterTagLabel = "WATER_TAG_" + tagIndex.toString();
        }

        /* Shader Material Factory Class Functions */

        public clone(name: string): BABYLON.WaterMaterialController {
            return BABYLON.SerializationHelper.Clone(() => new BABYLON.WaterMaterialController(name, this.getScene()), this);
        }

        public serialize(): any {
            var serializationObject = BABYLON.SerializationHelper.Serialize(this);
            serializationObject.customType = "BABYLON.WaterMaterialController";
            return serializationObject;
        }

        public static Parse(source: any, scene: BABYLON.Scene, rootUrl: string): BABYLON.WaterMaterialController {
            var material =  BABYLON.SerializationHelper.Parse(() => new BABYLON.WaterMaterialController(source.name, scene), source, scene, rootUrl);
            var property = "_Properties";
            // Parse custom shader properties
            if (source.vectors4) {
                property = "_WaterColor";
                if (source.vectors4[property]) {
                    material.waterColor = BABYLON.Color3.FromArray(source.vectors4[property]);
                }
                property = "_SecondColor";
                if (source.vectors4[property]) {
                    material.waterColor2 = BABYLON.Color3.FromArray(source.vectors4[property]);
                }
            }
            if (source.floats) {
                var tagIndex:number = 0;
                property = "_TagIndex";
                if (source.floats[property]) {
                    tagIndex = source.floats[property];
                }
                if (tagIndex <= 0) tagIndex = 0;
                material.setWaterTagIndex(tagIndex);

                property = "_WindForce";
                if (source.floats[property]) {
                    material.windForce = source.floats[property];
                }
                property = "_WaveSpeed";
                if (source.floats[property]) {
                    material.waveSpeed = source.floats[property];
                }
                property = "_WaveLength";
                if (source.floats[property]) {
                    material.waveLength = source.floats[property];
                }
                property = "_WaveHeight";
                if (source.floats[property]) {
                    material.waveHeight = source.floats[property];
                }
                property = "_BumpHeight";
                if (source.floats[property]) {
                    material.bumpHeight = source.floats[property];
                }
                property = "_ColorBlendFactor";
                if (source.floats[property]) {
                    material.colorBlendFactor = source.floats[property];
                }
                property = "_SecondBlendFactor";
                if (source.floats[property]) {
                    material.colorBlendFactor2 = source.floats[property];
                }

                var windDirX:number = 0.0;
                var windDirY:number = 1.0;
                property = "_WindDirectionX";
                if (source.floats[property]) {
                    windDirX = source.floats[property];
                }
                property = "_WindDirectionY";
                if (source.floats[property]) {
                    windDirY = source.floats[property];
                }
                material.windDirection = new BABYLON.Vector2(windDirX, windDirY);
            }
            return material;
        }
    }
}
```



Collider components define the shape of an object for the purposes of physical collisions. A collider, which is invisible, need not be the exact same shape as the object’s mesh and in fact, a rough approximation is often more efficient and indistinguishable in gameplay.

The simplest (and least processor-intensive) colliders are the so-called primitive collider types. In 3D, these are the Box Collider, Sphere Collider and Capsule Collider. Any number of these can be added to a single object to create compound colliders.

With careful positioning and sizing, compound colliders can often approximate the shape of an object quite well while keeping a low processor overhead. Further flexibility can be gained by having additional colliders on child objects (eg, boxes can be rotated relative to the local axes of the parent object). When creating a compound collider like this, there should only be one **Physics State** component, placed on the root object in the hierarchy.

There are some cases, however, where even compound colliders are not accurate enough. In 3D, you can use Mesh Colliders to match the shape of the object’s mesh exactly.

Colliders can be added to an object component to create floors, walls and other motionless elements of a scene. These are referred to as static colliders. Colliders on an object that does have a **Physics State** are known as dynamic colliders. Static colliders can interact with dynamic colliders but since they don’t have a **Physics State**, they will not move in response to collisions.

Please refer to the [Unity Collision](https://docs.unity3d.com/Manual/CollidersOverview.html) documentation for details.

## Managed Runtime Collision Events

Example **Collision Event** script component:

```javascript
    module PROJECT {
        export class ShotController extends BABYLON.MeshComponent {
            protected start() :void {
                // Physcis collision
                this.onCollisionEvent((collider:BABYLON.AbstractMesh, tag:string) => {
                    if (tag === "Asteroid" || tag === "Enemy" || tag === "Player") {
                        var metadata: BABYLON.ObjectMetadata = this.manager.findSceneMetadata(collider);
                        if (metadata.getProperty<boolean>("destroyed", false) === false) {
                            metadata.setProperty("destroyed", true);
                            if (this.shotType === 0) {
                                // Player shot
                                if (tag === "Asteroid" || tag === "Enemy") {
                                    var points:number = 0;
                                    if (tag === "Asteroid") {
                                        points = SpaceController.AsteroidPoints;
                                        this.manager.instantiatePrefab("Asteroid_Explosion", "Asteroid_Explode_" + this.shotName, collider.position.clone(), collider.rotation.clone());
                                    } else if (tag === "Enemy") {
                                        points = SpaceController.EnemyPoints;
                                        this.manager.instantiatePrefab("Enemy_Explosion", "Enemy_Explode_" + this.shotName, collider.position.clone(), collider.rotation.clone());
                                    }

                                    // Safely destroy game objects
                                    this.manager.safeDestroy(this.mesh);
                                    this.manager.safeDestroy(collider);
                                    SpaceController.Instance.addScore(points);
                                }
                            } else if (this.shotType === 1) {
                                if (tag === "Player") {
                                    this.manager.instantiatePrefab("Player_Explosion", "Player_Explode_" + this.shotName, collider.position.clone(), collider.rotation.clone());
                                    // Safely destroy game objects
                                    this.manager.safeDestroy(this.mesh);
                                    this.manager.safeDestroy(collider);
                                    SpaceController.Instance.gameOver(false);
                                }
                            }
                        }
                    }
                });
            }
        }
    }
```



The toolkit's **Terrain Builder** system allows you to add vast landscapes to your games. At runtime, terrain rendering is highly optimized for rendering efficiency while in the editor, a selection of tools is available to make terrains easy and quick to create. Please refer to the [Unity Terrain](https://docs.unity3d.com/Manual/script-Terrain.html) documentation for details.

## Creating And Editing Terrains

To add a Terrain game object to your Scene, select **GameObject > 3D Object > Terrain** from the menu. This also adds a corresponding **Terrain Asset** to the Project view. When you do this, the landscape is initially a large, flat plane. The Terrain’s Inspector window provides a number of tools you can use to create detailed landscape features.

![Terrain Editing](https://docs.unity3d.com/uploads/Main/1.1-TerrainInspector.png)

With the exception of the tree placement tool and the settings panel, all the tools on the toolbar provide a set of “brushes” and settings for brush size and opacity. It is no coincidence that these resemble the painting tools from an image editor because detail in the terrain is created precisely that way, by “painting” detail onto the landscape. If you select the leftmost tool on the bar (Raise/Lower Terrain) and move the mouse over the terrain in the scene view, you will see a cursor resembling a spotlight on the surface. When you click the mouse, you can paint gradual changes in height onto the landscape at the mouse’s position. By selecting different options from the Brushes toolbar, you can paint with different shapes. The Brush Size and Opacity options vary the area of the brush and the strength of its effect respectively.

The details of all of the tools will be given in subsequent sections. However, all of them are based around the concept of painting detail and with the exception of the tree placement tool, all have the same options for brushes, brush size and opacity. The tools can be used to set the height of the terrain and also to add coloration, plants and other objects.

## Terrain Keyboard Shortcuts

You can use the following keyboard shortcuts in the terrain inspector:

- Press the keys from F1 to F6 to select the corresponding terrain tool (for example, F1 selects the Raise/Lower tool).

- The comma (,) and period (.) keys cycle through the available brushes.

- Shift-comma (&lt;) and Shift-dot (>) cycle through the available objects for trees, Textures and details.

Additionally, the standard F keystroke works slightly differently for terrains. Normally, it frames the selection around the whole object when the mouse is over the scene view. However, since terrains are typically very large, pressing F will focus the scene view on the area of terrain where the mouse/brush is currently hovering. This provides a very quick and intuitive way to jump to the area of terrain you want to edit. If you press F when the mouse is away from the terrain object, the standard framing behavior will return.

## Still Under Development

The following **Terrain Builder** features are still under development:

- Terrain Splatmap Shader

- Tree Billboard Meshes

- Painting Grass Meshes

- Painting Detail Prototypes

- Terrain Physics Imposters (Ammo.js)



The toolkit's **Animation System** includes features like retargetable animations, full control of animation weights at runtime, event calling from within the animation playback, sophisticated state machine hierarchies and transitions, blend shapes for facial animations, and much more. Please refer to the [Unity Animation](https://docs.unity3d.com/Manual/AnimationSection.html) documentation for details.

## Animation State Machines

It is common for a character or other animated Game Object to have several different animations that correspond to different actions it can perform in the game. For example, a character may breathe or sway slightly while idle, walk when commanded to and raise its arms in panic as it falls from a platform. A door may have animations for opening, closing, getting jammed, and being broken open. Mecanim uses a visual layout system similar to a flow-chart, to represent a state machine to enable you to control and sequence the animation clips that you want to use on your character or object.

Please refer to the [Unity Animation Controller](https://docs.unity3d.com/Manual/AnimatorControllers.html) documentation for details.

## Managed Runtime Support

Example **Animation State** script component:

```javascript
    module PROJECT {
        export class TestPlayerController extends BABYLON.MeshComponent {
            private animator:BABYLON.AnimationState = null;
            protected start() :void {
                this.animator = this.getComponent("BABYLON.AnimationState");
            }
            protected update() :void {
                var vertical:number = this.manager.getUserInput(BABYLON.UserInputAxis.Vertical, BABYLON.PlayerNumber.One);
                var horizontal:number = this.manager.getUserInput(BABYLON.UserInputAxis.Horizontal, BABYLON.PlayerNumber.One);
                // ..
                if (this.animator != null) {
                    this.animator.setFloat("Forward", vertical);
                    this.animator.setFloat("Strafe", horizontal);
                }
            }
        }
    }
```

## Still Under Development

The following **Animation System** features are still under development:

- 2D Blend Trees

- Animation Curves

- Animation Events

- Animation Behaviours



It is convenient to build a game object in the scene by adding components and setting their properties to the appropriate values. This can create problems, however, when you have an object like an NPC, prop or piece of scenery that is reused in the scene several times. Simply copying the object will certainly produce duplicates but they will all be independently editable. Generally, you want all instances of a particular object to have the same properties, so when you edit one object in the scene, you would prefer not to have to make the same edit repeatedly to all the copies.

Fortunately, Unity has a Prefab asset type that allows you to store a game object complete with components and properties. The prefab acts as a template from which you can create new object instances in the scene. Any edits made to a prefab asset are immediately reflected in all instances produced from it but you can also override components and settings for each instance individually.

**Note:** When you drag an asset file (eg, a Mesh) into the scene, it will create a new object instance and all such instances will change when the original asset is changed. However, although its behaviour is superficially similar, the asset is not a prefab, so you won’t be able to add components to it or make use of the other prefab features described below.

Check out the [Unity Prefab Concept Video](https://unity3d.com/learn/tutorials/topics/interface-essentials/prefabs-concept-usage) for details on the prefab usage.

## Unity Prefab System

## Using Runtime Prefabs

You can create a prefab by selecting **Asset > Create Prefab** and then dragging an object from the scene onto the “empty” prefab asset that appears. If you then drag a different game object onto the prefab you will be asked if you want to replace your current game object with the new one. Simply dragging the prefab asset from the project view to the scene view will then create instances of the prefab. Objects created as prefab instances will be shown in the hierarchy view in blue text. (Normal objects are shown in black text.)

As mentioned above changes to the prefab asset itself will be reflected in all instances but you can also modify individual instances separately. This is useful, say, when you want to create several similar NPCs but introduce variations to make them more realistic. To make it clear when a property has been overridden, it is shown in the inspector with its name label in boldface. (When a completely new component is added to a prefab instance, all of its properties will be shown in boldface.)

![Prefab Override](https://docs.unity3d.com/uploads/Main/PrefabsAddedObjectIndicator1.png)

You can also create instances of prefabs at runtime from your scripts. See the **Managed Runtime Support** section for further details.

## Editing Runtime Prefabs

The inspector for a prefab instance has three buttons not present for a normal object: **Select**, **Revert** and **Apply**.

The **Select** button selects the prefab asset from which the instance was generated. This allows you to edit the main prefab and thereby change all its instances. However, you can also save overridden values from an instance back to the originating prefab using the **Apply** button (modified transform position values are excluded for obvious reasons). This effectively lets you edit all instances (except those which override the value changed) via any single instance and is a very quick and convenient way to make global changes.

If you experiment with overriding properties but then decide you preferred the default values, you can use the **Revert** button to realign the instance with its prefab.

## Babylon Prefab Layer

![Prefab Layer](/img/exporters/unity/prefablayer.jpg)

The prefab layer can prepare your objects to take advantage of the toolkit's deep cloning to instantiate game object prefabs at runtime. This step is required to use _ **Unity Style Prefabs** _ in a web browser environment. Web games cannot directly instaniate a prefab from disk, so game objects intended to be used as runtime prefabs must be present but disabled in the scene.

By setting game objects to the **Babylon Prefab** layer you will create disabled source meshes used for deep cloning when you call the scene manager instantiate prefab function.

## Managed Runtime Support

The toolkit scene manager provides easy to use helper functions for client side prefab instantiation:

```javascript
    declare module BABYLON {
        class SceneManager {

            /** Checks the scene has the specified prefab mesh. */
            hasPrefabMesh(prefabName: string): boolean;

            /** Gets ths the raw prefab mesh from scene. */
            getPrefabMesh(prefabName: string): BABYLON.Mesh;

            /** Instantiates the specfied prefab object into scene. */
            instantiatePrefab(prefabName: string, cloneName: string, newPosition?: BABYLON.Vector3, newRotation?: BABYLON.Vector3, newScaling?: BABYLON.Vector3, newParent?: Node): BABYLON.Mesh;
        }
    }
```

Example **Runtime Prefab** script component:

```javascript
    module PROJECT {
        export class TestMeshComponent extends BABYLON.MeshComponent {
            public constructor(owner: BABYLON.AbstractMesh, scene: BABYLON.Scene, tick: boolean = true, propertyBag: any = {}) {
                super(owner, scene, tick, propertyBag);
            }
            protected start() :void {

                // Spawn player game object
                var player:BABYLON.Mesh = this.manager.instantiatePrefab("Player", "NewPlayer", BABYLON.Vector3.Zero());
                console.log("Echo Player: " + player.name);
            }
        }
    }

```



Static batching allows the engine to reduce draw calls for geometry of any size provided it shares the same material, and does not move. It is often more efficient than dynamic batching (it does not transform vertices on the CPU), but it uses more memory.

In order to take advantage of static batching, you need to explicitly specify that certain game objects are **static** and do not move, rotate or scale in the game. To do so, set the game object to the **Babylon Static** layer.

Please refer to the [Unity Layer](https://docs.unity3d.com/Manual/Layers.html) documentation for details.

## Babylon Static Layer

![Static Layer](/img/exporters/unity/staticlayer.jpg)

The static batching layer can prepare your objects to take advantage of the toolkit's static batching export. This step is useful as a performance optimization allowing the engine to reduce number of draw-calls dramatically, but keep amount of rendered geometry intact.

By setting game objects to the **Babylon Static** layer you will create internal meshes at export time which will contain combined geometry. This allows game objects to stay seperate peices at design time allowing the easy placement and movement of static geometry. You can also use the **Geometry Tools** to pre bake and combine meshes at design time. Any pre baked meshes will no longer be seperate moveable meshes during game development.

Game objects with the same material will be batched together, thus it is useful to share as many textures/material as you can. **Texture Atlas** support is also included in the toolkit to help improve rendering performance.



The process of creating a navigation mesh from the level geometry is called **NavMesh Baking**. The process collects the **Render Meshes** and **Terrains** of all game objects which are marked as Navigation Static, and then processes them to create a navigation mesh that approximates the walkable surfaces of the level. Please refer to [Unity Navigation](https://docs.unity3d.com/Manual/nav-Overview.html) documentation on navigation.

In Unity, navigation mesh generation is handled from the _ **Navigation** _ window (Menu: **Window > Navigation**).

Building a navigation mesh for your scene can be done in 4 quick steps. Please refer to the [Unity Navigation Mesh](https://docs.unity3d.com/Manual/nav-BuildingNavMesh.html) documentation for details.

## Babylon Navigation Mesh

The [Babylon Navigation Mesh](https://github.com/wanadev/babylon-navigation-mesh) extension is a path finder for AI agents. It uses the **A Star** and **Funnel** algorithms to calculate a path on the exported baked navigation mesh and is packaged as a toolkit plugin.

## Managed Runtime Support

The toolkit scene manager provides easy to use helper functions for client side navigation:

```javascript
    declare module BABYLON {
        class SceneManager {

            /** Gets the native babylon mesh navigation tool */
            getNavigationTool(): Navigation;

            /** Gets the current navigation zone */
            getNavigationZone(): string;

            /** Finds a navigation path and returns a array of navigation positions */
            findNavigationPath(origin: BABYLON.Vector3, destination: BABYLON.Vector3): BABYLON.Vector3[];

            /** Gets true if the scene has a navigation mesh */
            hasNavigationMesh(): boolean;

            /** Returns the current scene's navigation mesh */
            getNavigationMesh(): BABYLON.AbstractMesh;

            /** Builds the current scene's navigation nodes */
            buildNavigationMesh(mesh: BABYLON.AbstractMesh): any;

            /** Returns a picked navigation point */
            getNavigationPoint(position: BABYLON.Vector3, raise?: number, length?: number): BABYLON.Vector3;

            /** Moves the specified navigation again along a path of positions */
            moveNavigationAgent(agent: BABYLON.AbstractMesh, path: BABYLON.Vector3[], speed?: number, loop?: boolean, callback?: () => void): void;

            /** Returns an array of navigation agents */
            getNavigationAgents(): BABYLON.Mesh[];

            /** Returns the specfied navigation agent info */
            getNavigationAgentInfo(agent: BABYLON.AbstractMesh): BABYLON.NavigationAgent;

            /** Returns the current scene's navigation area table */
            getNavigationAreaTable(): BABYLON.INavigationArea[];

            /** Returns the current scene's navigation area indexes */
            getNavigationAreaIndexes(): number[];

            /** Returns the current scene's navigation area names */
            getNavigationAreaName(index: number): string;

            /** Returns the current scene's navigation area cost */
            getNavigationAreaCost(index: number): number;
        }
    }
```

Example **Navigation Mesh** script component:

```javascript
    module PROJECT {
        export class NavMeshComponent extends BABYLON.MeshComponent {
            private navmesh:BABYLON.AbstractMesh = null;
            public constructor(owner: BABYLON.AbstractMesh, scene: BABYLON.Scene, tick: boolean = true, propertyBag: any = {}) {
                super(owner, scene, tick, propertyBag);
            }
            protected start() :void {
                this.navmesh = this.manager.getNavigationMesh();
                if (this.navmesh) {
                    var minimoi = BABYLON.Mesh.CreateBox("MiniMoi", 0.5, this.scene);
                    minimoi.material = new BABYLON.StandardMaterial("MoiMaterial", this.scene);
                    (<BABYLON.StandardMaterial>minimoi.material).diffuseColor = new BABYLON.Color3(1., 0., 0);
                    minimoi.position = new BABYLON.Vector3(0, 0.25, 0);

                    // Setup point and click demo navigation
                    var canvas = document.getElementById("cvs");
                    canvas.addEventListener('click', (evt)=> {
                        var pickingInfo = this.scene.pick(this.scene.pointerX, this.scene.pointerY, (mesh) => { return (mesh === this.navmesh); });
                        if (pickingInfo.hit) {
                            var navpoint = pickingInfo.pickedPoint;
                            var path = this.manager.findNavigationPath(minimoi.position, navpoint);
                            if (path != null) {
                                this.manager.moveNavigationAgent(minimoi, path, 5.0);
                            }
                        }
                    });
                }
            }
        }
    }
```



Windows 10 introduced the Universal Windows Platform (**UWP**), which provides a common app platform on every device that runs Windows 10. The **UWP** core APIs are the same on all Windows devices. If your app only uses the core APIs, it will run on any Windows 10 device no matter whether you are targeting a desktop PC, Xbox, Mixed-reality headset, and so on. Please refer to the [Universal Windows Platform](https://docs.microsoft.com/en-us/windows/uwp/index) documentation for details.

## Hosted Web Applications

**Progressive Web Apps** are simply web apps that are progressively enhanced with native **UWP** features on supporting platforms and browser engines, such as launch-from-homescreen installation, offline support, and push notifications. On Windows 10 with the Microsoft Edge (EdgeHTML) engine, PWAs enjoy the added advantage of running independently of the browser window as Universal Windows Platform apps. Please refer to the [Progressive Web Apps](https://docs.microsoft.com/en-us/microsoft-edge/progressive-web-apps/windows-features) documentation for details.

**Development Release Builds**

You must use your toolkit address or hostname as the application start page. Example: **http://192.168.0.250:8888**

**Production Release Builds**

You must use your production hostname as the application start page. Example: **https://www.myserver.com/game**

## Windows Runtime Library

When you write a Universal Windows Platform (**UWP**) app, you can use **Windows Runtime Library** classes, methods, and properties in much the same way that you would use native JavaScript objects, methods, and properties. Please refer to the [JavaScript Windows Runtime](https://docs.microsoft.com/en-us/scripting/jswinrt/using-the-windows-runtime-in-javascript) documentation for details.

## Managed Xbox Live Services

The toolkit's [Xbox Live Plugin](https://www.nuget.org/packages/BabylonToolkit.XboxLive/) provides built-in access to the **Microsoft.Xbox.Services** runtime for your game projects. Simply install the plugin into your hosted **UWP** application with the **NuGet Package Manager** command:

    Install-Package BabylonToolkit.XboxLive

The toolkit scene manager provides easy to use helper functions for Xbox Live context management:

```javascript
declare module BABYLON {
    class SceneManager {

        /** Are unversial windows platform services available. */
        static IsWindows(): boolean;

        /** Are xbox one platform services available. */
        static IsXboxOne(): boolean;

        /** Are xbox live platform services available. */
        static IsXboxLive(): boolean;

        /** Are xbox live platform services available and user enabled. */
        static IsXboxLivePluginEnabled(): boolean;

        /** Is xbox live user signed in if platform services enabled. */
        static IsXboxLiveUserSignedIn(systemUser?: Windows.System.User, player?: BABYLON.PlayerNumber): boolean;

        /** Validated sign in xbox live user if platform services available. */
        static XboxLiveUserSignIn(player?: BABYLON.PlayerNumber, oncomplete?: (result: Microsoft.Xbox.Services.System.SignInResult) => void, onerror?: (error: any) => void, onprogress?: (progress: any) => void): void;

        /** Silent sign in xbox live user if platform services available. */
        static XboxLiveUserSilentSignIn(player?: BABYLON.PlayerNumber, oncomplete?: (result: Microsoft.Xbox.Services.System.SignInResult) => void, onerror?: (error: any) => void, onprogress?: (progress: any) => void): Windows.Foundation.Projections.Promise<void>;

        /** Dialog sign in xbox live user if platform services available. */
        static XboxLiveUserDialogSignIn(player?: BABYLON.PlayerNumber, oncomplete?: (result: Microsoft.Xbox.Services.System.SignInResult) => void, onerror?: (error: any) => void, onprogress?: (progress: any) => void): Windows.Foundation.Projections.Promise<void>;

        /** Loads a xbox live user profile if platform services available. */
        static LoadXboxLiveUserProfile(player?: BABYLON.PlayerNumber, oncomplete?: (result: Microsoft.Xbox.Services.Social.XboxUserProfile) => void, onerror?: (error: any) => void, onprogress?: (progress: any) => void): Windows.Foundation.Projections.Promise<void>;

        /** Get xbox live user if platform services available. */
        static GetXboxLiveUser(player?: BABYLON.PlayerNumber): Microsoft.Xbox.Services.System.XboxLiveUser;

        /** Get xbox live user if platform services available. */
        static GetXboxLiveSystemUser(systemUser: Windows.System.User, player?: BABYLON.PlayerNumber): Microsoft.Xbox.Services.System.XboxLiveUser;

        /** Get xbox live user context if platform services available. */
        static GetXboxLiveUserContext(player?: BABYLON.PlayerNumber): Microsoft.Xbox.Services.XboxLiveContext;

        /** Resets xbox live user context if platform services available. */
        static ResetXboxLiveUserContext(player?: BABYLON.PlayerNumber): void;

        /** Get xbox live context property if platform services available. */
        static GetXboxLiveContextProperty(name: any): any;

        /** Get xbox live context property if platform services available. */
        static SetXboxLiveContextProperty(name: any, property: any): void;

        /** Resets xbox live property context bag if platform services available. */
        static ResetXboxLivePropertyContexts(): void;

        /** Sets the Xbox User Sign Out Complete Handler */
        static SetXboxLiveSignOutHandler(handler?: (result: Microsoft.Xbox.Services.System.SignOutCompletedEventArgs) => void): void;
    }
}
```

Example **Xbox Live Authentication** script component:

```javascript
module PROJECT {
    export class TestSceneController extends BABYLON.MeshComponent {
        public constructor(owner: BABYLON.AbstractMesh, scene: BABYLON.Scene, tick: boolean = true, propertyBag: any = {}) {
            super(owner, scene, tick, propertyBag);
        }
        protected onSignInButton() :void {
            if (BABYLON.SceneManager.IsXboxLivePluginEnabled()) {
                var player:BABYLON.PlayerNumber.One = BABYLON.PlayerNumber.One;
                if (!BABYLON.SceneManager.IsXboxLiveUserSignedIn(null, player)) {

                    BABYLON.SceneManager.XboxLiveUserSignIn(player, (result: Microsoft.Xbox.Services.System.SignInResult) => {
                        var user = BABYLON.SceneManager.GetXboxLiveUser(player);
                        var msg = "(" + user.xboxUserId + ") - " + user.gamertag;
                        BABYLON.SceneManager.Alert(msg, "Xbox Live User Signed In");
                    }, (err)=>{
                        console.log(err);
                        var msg:string = "Encountered Sign Error";
                        BABYLON.Tools.Warn(msg);
                        BABYLON.SceneManager.Alert(msg, "Xbox Live Warning");
                    });

                } else {
                    BABYLON.Tools.Warn("Xbox Live User Already Signed In");
                    BABYLON.SceneManager.Alert("User Already Signed In", "Xbox Live Warning");
                }
            }
        }
    }
}

```



Good performance is critical to the success of many games. The graphical parts of your game can primarily impact on two systems of the computer: the GPU and the CPU.

**Common Bottlenecks:**

- The **GPU** has too many vertices to process. The number of vertices that is acceptable to ensure good performance depends on the GPU and the complexity of vertex shaders. Generally speaking, aim for no more than 100,000 vertices on mobile. A PC manages well even with several million vertices, but it is still good practice to keep this number as low as possible through optimization.

- The **CPU** has too many vertices to process. This could be in skinned meshes, cloth simulation, particles, or other game objects and meshes. As above, it is generally good practice to keep this number as low as possible without compromising game quality. See the section on CPU optimization below for guidance on how to do this.
  If rendering is not a problem on the GPU or the CPU, there may be an issue elsewhere - for example, in your script or physics. Use the Unity Profiler to locate the problem.

The art tools provided by the toolkit allow you to optimize your game assets for maximum performance using the **WebGL** platform.

# Maya Arts Tools

**Maya Scripts** plattform folder locations:

- **Windows** - C:\Users\USERNAME\Documents\maya\*VERSION\*\scripts

- **Macintosh** - ~/Library/Preferences/Autodesk/maya/_VERSION_/scripts

Check out the [Maya Arts Tools Tutorial](http://www.babylontoolkit.com/videos/MayaArtTools.mp4) to get started optimizing your geometry for web based game development.

# Babylon Reskin Tool

Reskin and combine selected meshes with new max influencers. Download and install the [Babylon Reskin Tool](https://github.com/BabylonJS/Exporters/blob/master/Maya/Tools/babylonReskinTool.mel) file in your **Maya Scripts** folder.

Open the Script Editor and go to the Mel tab, copy and paste command below:

    babylonReskinTool();

Highlight it and click on "Save Script to Shelf...", specify a name ('Reskin') and click "OK".

# Babylon Namespace Tool

Removes unwanted namespace text from selected object. Download and install the [Babylon Namespace Tool](https://github.com/BabylonJS/Exporters/blob/master/Maya/Tools/babylonReskinTool.mel) file in your **Maya Scripts** folder.

Open the Script Editor and go to the Mel tab, copy and paste command below:

    babylonNameTool();

Highlight it and click on "Save Script to Shelf...", specify a name ('Names') and click "OK".

# Unity Art Tools

# Geometry Tools

The geometry tools help improve overall scene performance by optimizing game art for **WebGL** rendering. The toolkit supports combining meshes, seperating meshes, generating blocking volumes for collision and baking a texture atlas for **Static Mesh Filter** game objects.

![Geometry Tools](/img/exporters/unity/combinemeshes.jpg)

# Height Mapping

The height mapping tool enables **16-Bit RAW Greyscale** image manipulations. This is very useful to convert to and from **RAW** and **PNG** image formats and to scale height maps to the desired mesh detail resolution.

![Height Mapping](/img/exporters/unity/heightmapping.jpg)

# Cubemap Baking

The cubemap baking tool can pre bake environment **Skybox** and **Radiance** texture images. The toolkit supports **Low Dynamic Range**, **High Dynamic Range**, and **Direct Draw Surface** image file formats. An internal [Cubemap Filtering Tool](https://github.com/dariomanesku/cmft) plugin is used to process cubemap textures. It reaches very fast processing speeds by utilizing both multi-core CPU and OpenCL GPU at the same time.

![Cubemap Baking](/img/exporters/unity/cubemapbaking.jpg)

# Texture Atlas Skin

The texture atlas skin tool allows you to bake a texture atlas for **Skinned Mesh Renderer** game objects. It will parse all the sub meshes (materials) and combine all the textures into a group of texture atlas images. The toolkit will encode new uv sets and bake new geometry assets using the combined texture atlas material assets.

![Texture Atlas Skin](/img/exporters/unity/textureatlasskin.jpg)



**Note:** The scene exporter panel is the primary toolkit interface. It must be opened or docked to enable the toolkit features during project development.

![Scene Exporter](/img/exporters/unity/exporter.jpg)

## Global Export Options

* Project Bin Path        - Specifies the exported project binary path.

* Project Build Path      - Specifies the exported project build path.

* Project Scene Path      - Specifies the exported project scene path.

* Project Script Path     - Specifies the exported project script path.

* Project Index Page      - Specifies the exported project index page.

## Default Engine Options

![Engine Options](/img/exporters/unity/engine.jpg)

* Enable Physics Engine   - Enables or disables the built-in physics engine.

* Default Physics Engine  - Specifies the default physics engine for the project.

* Set Engine Antialias    - Enables or disables the engine anti alias option.

* Adaptive Device Ratio   - Sets the engine to adapt to device ratio.

* Set Image Encoding      - Enables or disables default image encoding options.

* Default Texture Format  - Specifies the default image encoding format.

* Set Texture Quality     - Sets the default texture image quality.

* Set Mesh Vertex Limit   - Enables or disables the static mesh vertex limit (65000).

## Terrain Builder Options

![Terrain Options](/img/exporters/unity/terrain.jpg)

* Terrain Scale Factor    - Sets the shader texture scale factor for all terrain splatmaps.

* Texture Atlas Size      - Sets the terrain splatmap texture atlas maximum size.

* Texture Image Scaling   - Sets the mode when scaling tile images to point or bilinear.

* Shadow Lightmap Index   - Sets the lightmap index channel. Must be 0 or 1.

## Collision System Options

![Collision Options](/img/exporters/unity/collision.jpg)

* Enable Collisions       - Enable built-in collision mesh system.

* Generate Colliders      - Auto generate collision meshes for each collider component.

* Collision Visibilty     - Sets the default collision mesh visibilty level for debugging.

* Show Debug Colliders    - Show all collider component collision meshes for debugging.

* Show Debug Sockets      - Show all socket component collision meshes for debugging.

* Socket Collider Size    - Sets the size of the socket component collision mesh for debugging.

* Default Collider Detail - Set the collision mesh goemetry detail level for all generated mesh colliders.

## Lightmap Baking Options

![Lightmap Options](/img/exporters/unity/lightmap.jpg)

* Export Lightmaps        - Enable built-in shadow lightmap baking system.

* Bake Iterative Maps     - Enable built-in final lightmap gather and bake option.

* Coordinates Index       - Sets the default texture coordinate index for lightmaps.

* Use Material Instance   - Enables or disables material instances for shared material lightmaps.

* Area Baking Lights      - Include or exclude lightmap area baking lights into exported scene.

## Project Compiler Options

![Compiler Options](/img/exporters/unity/compilers.jpg)

* Build Typescript Files  - Enables or disables optional runtime script compiler.

* Typescript Compiler     - Specifies the default TypeScript compiler location.

* Node Runtime System     - Specifies the default Node runtime system location.

## Windows Platform Options

![Windows Options](/img/exporters/unity/windows.jpg)

* Launching Mode          - Specifies UWP Application initial window state.

* Run App Protocol        - Enables and specifies the UWP Application protocol.

* Xbox Live Services      - Enables the toolkit managed Xbox Live Service API.

* Xbox Live Plugin        - Launches the toolkit managed Xbox Live Service API NuGet install info.

* Switch Windows Sandbox  - Launches the toolkit local Windows Sandbox Switcher amdinistrative tool.

## Toolkit Exporter Options

![Export Options](/img/exporters/unity/export.jpg)

* Attach Unity Editor     - Enables the built-in toolkit play to build and preview features.

* Host Preview Server     - Toggle internal and external web server hosting options for project.

* Default Server Port     - Specifies the default web server host port for previewing scene.

* Remote Server Path      - Specifies the remote server host address for external server option.

* Show Render Stats       - Toggle debug rendering stats default page options for project.

* Set Default Scene       - Set the index page default scene name option for project.

* Enable Main Menu        - Toggle html project main menu page options for project.

* Truevision Graphics     - Toggle the native TARGA image file support options for project.

* Embed Html Pages        - Toggle internal embed html pages into makrup store options for project.

* Export Http Module      - Enables the web server http scene content management module.

* Export Web Assembly     - Enables or disables the exported wasm content option.

* Export Unity Metadata   - Enables or disables the default scene object metadata information.

* Precompress Contents    - Enables or disables the exported precompressed content option.

* Minify Project Scripts  - Enables or disables the exported script minification option.

* Debug Exporter Output   - Enables or disables pretty print json and compiler source maps.

## Scene Builder Options

![Builder Options](/img/exporters/unity/builder.jpg)

* Compile Script          - Compiles the projects typescript files only with no previewing

* Export Scene File       - Exports scene only content with no compiling or previewing.

* Build And Preview       - Exports a full scene build with compiling and optional previewing.

* Rebuild Editor Project  - Rebuilds the native Unity Editor project source code.

* Launch Preview Window   - Launches the current preview build in browser.


## Output Window

![Output Window](/img/exporters/unity/output.jpg)

The output window traces the toolkit export progress for every build. Any exported camera, light or mesh detail information will appear in this window. The output window can be docked to the editor during game development for easy access.

.


## Exportation

The toolkit exports game objects that have a camera, light or mesh component attached. The toolkit also provides built in script components to support native babylon engine features at desgin time. The toolkit's [Export Inspector](Exporter) window provides easy access to global exportation properties. Docking this window is recommended to enable the **Unity Editor** game development and exportation features.

**Camera Rigs**

Perspective and orthographic cameras are supported. The Camera Rig component supports detailed camera control allowing easy camera type selection and specfic runtime camera mode options. Please refer to the [Unity Camera](https://docs.unity3d.com/Manual/class-Camera.html) documentation for details.

**Scene Lighting**

The toolkit exports directional, point and spot lights. Realtime lights are standard lights that illuminate the scene at runtime. Mixed lights support baked lighting and require the [Subtractive](https://docs.unity3d.com/Manual/LightMode-Mixed-Subtractive.html) lightmapper mode.

Fully baked lighting (including all area lights) are used for lightmap shadow baking at design time and will **not** be included in the exported scene file. This will allow for detailed lightmap baking using as many baking lights as required to achieve the best shadow effects as possible without using any of the baking light resources at runtime. Please refer to the [Unity Baked Lighting](https://docs.unity3d.com/Manual/LightMode-Baked.html) documentation for details.

**Scene Environment**

Skyboxes for the scene are primarily controlled via the [Unity Lighting Window](https://docs.unity3d.com/Manual/GlobalIllumination.html). The default scene controller **Skybox Options** allow for more detailed settings at runtime. The toolkit supports native hdr, exr and dds cubemaps. Please refer to the [Unity Skybox Rendering](https://docs.unity3d.com/Manual/class-Skybox.html) documentation for details.

**Default Color Space**

The preferred **Color Space** for realistic rendering is **Linear**. A significant advantage of using **Linear** color space is that the colors supplied to shaders within your scene will brighten linearly as light intensities increase. This can be selected using the **Color Space** property from **Edit>Project Settings>Player** settings panel.


## Getting Started

The [Project Setup](Projects) section outlines basic project setup, scene configuration and runtime script compiler options. You can auto detect the platform script compiler locations in the **Project Compiler Options** section on the main export panel. Check out the [Getting Started Video](http://www.babylontoolkit.com/videos/GettingStarted.mp4) to get started with **Babylon Toolkit** style game development.


## Toolkit Features
    
### Script Components

[Script Components](01_ScriptComponents) are the primary way of attaching native babylon classes to game objects and prefabs in the editor.

The **Editor Script Components** are C# design-time components used to input client properties. They are not intended to execute at runtime. They are simply to allow the use
of design-time editor properties for your native babylon client scripts. Each editor script specifies the native javascript or typescript backing class to use at runtime. Please refer to the [Unity Component](https://docs.unity3d.com/Manual/UsingComponents.html) documentation for details.

The client scripts are your native babylon javascript or typescript classes that actually contain your game logic code. Each class has a **ready** function that gets
called once during the scene execute when ready phase. A **start** function that gets called once during the first frame. An **update** function that gets called every frame.
An **after** function that gets called after the scene render phase and a **destroy** function that get called on component disposal.

### Scene Manager

The [Scene Manager](02_SceneManager) application programming interface exposes a unity like scene component development pattern. This allows script components to be attached to
game objects like meshes, cameras and lights. Each component type has a ready, start, update, after and destroy function that will get called by the scene manager during it's life cycle.

### Shader Materials

[Shader Materials](03_ShaderMaterials) are used to assign unity standard and legacy shaders to native babylon material classes. Custom shaders are supportted if they follow the unity shader property naming standard. The universial shader material component encapsulates both Unity design time shader and babylon runtime shader information. Please refer to 
the [Unity Material Editor](https://docs.unity3d.com/Manual/Materials.html) documentation for details.

### Collision Meshes

[Collision Meshes](04_CollisionMeshes) are generated to provided simple collision for each component type (box, sphere, capsule, wheel, mesh and terrain). This allows simple geometry to be be used for physics collisions and mesh intersections instead of the original detailed geometry. Please refer to the [Unity Collider Components](https://docs.unity3d.com/Manual/CollidersOverview.html) documentation for details.

### Terrain Builder

[Terrain Builder](05_TerrainBuilder) options are used to export dynamic terrain geometry generation at export time. Up to 12 textures and normal maps may be used to paint terrains. Texture atlas maps are created to optimize multiple terrain splat textures. Terrain mesh colliders are supported to optimize runtime collision checking. Colliders can be segmented up to 16 x 16 low poly collision meshes that cover the orginal high poly terrain surface.

The terrain builder supports custom terrain splatmap shaders to allow design time editor access to the terrain render material. If no custom terrain splatmap material is selected, default options will be used. Please refer to the [Unity Terrain Settings](https://docs.unity3d.com/Manual/terrain-OtherSettings.html) documentation for details.

### Animation State

[Animation State](06_AnimationState) is supported for both transform and skeleton animations. Transform animations are used to animate the position, rotation and scale of any light, camera or mesh. Skeleton animation are used to animate the bones of a skeletal mesh. Legacy Animation controls are used to enable standard bone key frame animations only. 

The newer standard Animator controls are used to enable the built-in Unity Mechanim humanoid animation rigging system. Please refer to the [Unity Animation Group](https://docs.unity3d.com/Manual/comp-AnimationGroup.html) documentation for details.

### Runtime Prefabs

[Runtime Prefabs](07_RuntimePrefabs) are used to allow client side prefab instantiation. Game objects that are assigned to the **Babylon Prefab** layer are marked for client side prefab usage and will not be enabled in the scene. The scene manager function **instantiate prefab** is used to create fully scipted components at runtime. The scene manager uses deep cloning with hierarchy.

### Static Batching

[Static Batching](08_StaticBatching) allows design time mesh combining. Game objects that are assigned to the **Babylon Static** layer are marked for mesh optimization at scene export. Meshes will automatically be grouped by material, combined, baked and serialized as a single mesh per material. Texture atlas materials are supported to increase multiple texture rendering optimizations.

### Navigation Mesh

[Navigation Mesh](09_NavigationMesh) support is provided by [Babylon-Navigation-Mesh](https://github.com/wanadev/babylon-navigation-mesh). A path finder for AI agents. It use the **A Star** and **Funnel** algorithms to calculate a path on a navigation mesh. The toolkit supports the unity navigation mesh generation tools to produced and serialize the navigation mesh geometry into your scene. Please refer to the [Unity Navigation Mesh](https://docs.unity3d.com/Manual/Navigation.html) documentation for details.

### Windows Platform

The [Windows Platform](10_WindowsPlatform) toolset provides built-in support to develop hosted [Universal Windows Platform](https://docs.microsoft.com/en-us/windows/uwp/get-started/universal-application-platform-guide) applications to serve as self contained web browser application for your game projects. This allows for native platform intergration support for the **Windows Runtime Library** including **Xbox Live Services** for both ** Windows 10 PC** and **Xbox One** game consoles.

### Babylon Art Tools

The [Babylon Art Tools](11_BabylonArtTools) included in the toolkit provides a number of art tools to aid in creating optimized game ready assets.


## Exported Content

### Editor Script Components

The toolkit provided abstract base class **Editor Script Component** is the only supported script component that will be exported. All other non supported components will be ignored. The pre built toolkit components and your [Custom Script Components](01_ScriptComponents) are all derived from the base editor script component class and will be included in the exported scene.

Native JavaScript Libraries (renamed to .bjs) that are included anywhere in the **Assets** folder will be packaged up and included in your project script file. This allow easy packaging of third-party script packages. TypeScript definition files are supported by most IDE and should also be included for auto complete usage in your game project development.

### Supported Unity Features

* **Scene**
 * Assets
 * Metadata
* **Cameras**
 * Name
 * Position
 * Target
 * FOV
 * LOD Groups
 * Clip Range Start
 * Clip Range End
 * Check Collisions
 * Gravity
 * Ellipsoid
 * Animations (Position)
* **Lights**
 * Type (Point, Directional, Spot)
 * Name
 * Position
 * Direction
 * Spot Angle
 * Intensity
 * Diffuse Color
 * Animations (Position)
 * Shadow Maps
 * Light Maps
* **Materials**
 * Name
 * Diffuse Color
 * Specular Color
 * Specular Power
 * Emissive Color
 * Alpha
 * Backface Culling
 * Diffuse Texture
 * Reflection Texture
 * Emissive Texture
 * Bump Texture
* **Physically Based Rendering**
 * Metallic Setup
 * Roughness Setup
 * Specular Setup
* **Multi-Materials**
 * Name
 * Child Materials
* **Textures**
 * Name
 * Associated File
 * Use Alpha
 * uOffset / voffset
 * uScale / uScale
* **Meshes**
 * Name
 * Geometry (Positions &amp; Normals)
 * Position
 * Rotation
 * Scaling
 * Texture Coordinates (2 Channels)
 * Check Collisions
 * Receive &amp; Cast Shadows
 * Animations (Position, Rotation, Scaling)
 * Skeletons (Shared Cloning)
* **Shaders**
 * Vertex Shaders
 * Fragment Shaders
 * Custom Shaders
* **Layers**
 * Custom Layers
 * Object Layers
 * Static Layers
 * Prefab Layers
 * Ignore Layers (Void)
* **Tagging**
 * Object Tag Name
 * Custom Tag Names
* **Terrains**
 * Multiple Terrains
 * Splatmap Textures
 * Tree Instances
 * Grass Patches (Under Construction)
 * Detail Prototypes (Under Construction)
* **Components**
 * Mesh Filter
 * Mesh Renderer
 * Skinned Mesh Renderer
* **Collisions**
 * Box Collider
 * Sphere Collider
 * Capsule Collider
 * Mesh Collider
 * Wheel Collider
 * Terrain Collider
* **Navigation**
 * Navigation Mesh
 * Nav Mesh Agent
 * Off Mesh Link
 * Nav Mesh Obstacle
* **Local Multiplayer**
 * Multiplayer Input 
 * Multiplayer Camera
* **Miscellaneous**
 * Tree Component
 * Terrain Component
 * Animator Component
 * Animation Component

.


Download the [Babylon Editor Toolkit](https://github.com/BabylonJS/UnityExporter/tree/master/Redist) and use **Import Package** to install into current project. Once installed, unity will detect the plugin, compile it and add the toolkit [Export Inspector](Exporter) window to your project.


## Create New Project

![New Unity Project](/img/exporters/unity/newproject.jpg)

Create a new unity game project then add the **Babylon Editor Toolkit** to your project. You can download and import the toolkit unity package [distribution](https://github.com/BabylonJS/UnityExporter/tree/master/Redist) file.

## Set Compiler Options

![Node Runtime Compilers](/img/exporters/unity/compilers.jpg)

Configure optional **Runtime Script Compiler** locations. You can download and install or update the current [Node Runtime](https://nodejs.org/en/) to the default location. Then use node package manager to install or update the latest [TypeScript Compiler](https://www.typescriptlang.org/) to the default location.

**Install TypeScript Command**

    Mac OSX: sudo npm install -g typescript

    Windows: npm install -g typescript

**Default TypeScript Location**

    Mac OSX: /usr/local/bin/tsc

    Windows: C:\Users\<YourName>\AppData\Roaming\npm\node_modules\typescript\bin\tsc

**Default Node Runtime Location**

    Mac OSX: /usr/local/bin/node

    Windows: C:\Program Files\nodejs\node.exe

## Save Export Settings

On the Scene Exporter panel, press the **Save Export Settings** button to save the project export settings to disk. Export settings will also detect changes and save on each build.


## Scene Configuration

* **File > New Scene** - To create a new empty scene. Unity will create a main camera and a directional light by default.

* **File > Save Scene As** - To name and save your current scene to a folder in your project assets. The toolkit will use this scene name for exporting content. 

## Set Project Settings

* **Edit > Project Settings > Player** - To set the default color space setting to **Linear**. Unity will set color space to **Gamma** by default.

* **Lighting > Global Illumination** - To disable **Realtime Global Illumination** and set the **Baked Global Illumination** to the desired lighting mode.

## Add Scene Content

* **Global Startup Scripts** - If defined, the global startup script is the main entry point for every scene. You can use the global startup script to attach the SceneManager.ExecuteWhenReady handler that will get called first for each and every scene.

* **Default Scene Controllers** - Any scene options for your project can be set using any script components you see fit. You can optionally add an empty game object and attach a default scene controller script component to easily setup built in options for your scene.

* **Cameras, Lights And Meshes** - Add any supported camera, light and mesh content to your scene. You can attach script components, assign materials, create particle systems, setup animations, optimize geometry and utilize any unity editor tools to manage scene content.

## Build And Preview

To build and preview the current scene, press the **Play** button or the **Build And Preview** button on the Scene Exporter panel. Select the **Export Scene File** to simply export the current scene content without a full build and preview. This is very useful for creating **Import Mesh** only scenes. All project output will be saved to the **Export** folder of your unity game project folder.


## How To Get Started

Check out the [Getting Started Video](http://www.babylontoolkit.com/videos/GettingStarted.mp4) to get started with **Babylon Toolkit** style game development.

.


The [Babylon Unity Toolkit](http://www.babylontoolkit.com) host a set of tools designed to provide a small subset of the unity editor design time features to export Babylon.js content scene files. You can create your games using a design time component based architecture. Please refer to the [Unity Editor](https://docs.unity3d.com/Manual/index.html) documentation for details. 




CesiumJS is an open source JavaScript library for creating world-class 3D globes and maps with the best possible performance, precision, visual quality, and ease of use. Because both BabylonJS and CesiumJS show 3D scene with javascript, it is possible to integrate them together for a better visual effect.

Inspired by [Integrating Cesium with Three.js](https://cesium.com/blog/2017/10/23/integrating-cesium-with-threejs/), the base point of the solution is to render two libraries in two canvases, the canvas upper for BabylonJS. Set the upper canvas `pointer-events: none;`, CesiumJS will have the control and we make BabylonJS's camera to follow CesiumJS's.
## Setup CesiumJS
```javascript
const LNG = -122.4175, LAT = 37.655;

const viewer = new Cesium.Viewer('cesiumContainer', {
    terrainProvider: Cesium.createWorldTerrain(),
    useDefaultRenderLoop: false
});

viewer.camera.flyTo({
    destination : Cesium.Cartesian3.fromDegrees(LNG, LAT, 300),
    orientation : {
        heading : Cesium.Math.toRadians(0.0),
        pitch : Cesium.Math.toRadians(-90.0),
    }
});

// get these two points for later setup of BabylonJS root node.
const base_point = cart2vec(Cesium.Cartesian3.fromDegrees(LNG, LAT, 50));
const base_point_up = cart2vec(Cesium.Cartesian3.fromDegrees(LNG, LAT, 300));
```

## Setup BabylonJS
`Scene's clearColor` is important, we should make background transparent to see things renderer in CesiumJS.
```javascript
const engine = new BABYLON.Engine(canvas);
const scene = new BABYLON.Scene(engine);
scene.clearColor = BABYLON.Color4(0, 0, 0, 0);

const camera = new BABYLON.FreeCamera("camera", new BABYLON.Vector3(0, 0, -10), scene);
```

## Rendering Sequence
Before BabylonJS rendering, we should change BabylonJS's camera's position and rotation to make it absolutely the same with CesiumJS's.
```javascript
function cart2vec(cart) {
    return new BABYLON.Vector3(cart.x, cart.z, cart.y);
}

const fov = Cesium.Math.toDegrees(viewer.camera.frustum.fovy);
camera.fov = fov / 180 * Math.PI;

const civm = viewer.camera.inverseViewMatrix;
const camera_matrix = BABYLON.Matrix.FromValues(
    civm[0 ], civm[1 ], civm[2 ], civm[3 ],
    civm[4 ], civm[5 ], civm[6 ], civm[7 ],
    civm[8 ], civm[9 ], civm[10], civm[11],
    civm[12], civm[13], civm[14], civm[15]
);

// I'm sure it is able to get the result with the matrix directly, but I'm not familiar with matrixs, so you can do it yourselves.:)
const scaling = BABYLON.Vector3.Zero(), rotation = BABYLON.Vector3.Zero(), transform = BABYLON.Vector3.Zero();
camera_matrix.decompose(scaling, rotation, transform);
const camera_pos = cart2vec(transform),
    camera_direction = cart2vec(viewer.camera.direction),
    camera_up = cart2vec(viewer.camera.up);

const rotation_y = Math.atan(camera_direction.z / camera_direction.x);
if (camera_direction.x < 0) rotation_y += Math.PI;
rotation_y = Math.PI / 2 - rotation_y;
const rotation_x = Math.asin(-camera_direction.y);
const camera_up_before_rotatez = new BABYLON.Vector3(-Math.cos(rotation_y), 0, Math.sin(rotation_y));
const rotation_z = Math.acos(camera_up.x * camera_up_before_rotatez.x + camera_up.y * camera_up_before_rotatez.y + camera_up.z * camera_up_before_rotatez.z);
rotation_z = Math.PI / 2 - rotation_z;
if (camera_up.y < 0) rotation_z = Math.PI - rotation_z;

camera.position.x = camera_pos.x - base_point.x;
camera.position.y = camera_pos.y - base_point.y;
camera.position.z = camera_pos.z - base_point.z;
camera.rotation.x = rotation_x;
camera.rotation.y = rotation_y;
camera.rotation.z = rotation_z;
```
CesiumJs must render first as we need the parameters of its camera.
```javascript
engine.runRenderLoop(() => {
    viewer.render();
    moveBabylonCamera();
    scene.render();
});
```
## Setup root node
This step is actually not necessary, but it will make things easier.
```javascript
const root_node = new BABYLON.TransformNode("BaseNode", scene);
root_node.lookAt(base_point_up.subtract(base_point));
root_node.addRotation(Math.PI / 2, 0, 0);

// Then you can add your meshes to root_node.
const box = BABYLON.MeshBuilder.CreateBox("box", {size: 10}, scene);
const material = new BABYLON.StandardMaterial("Material", scene);
material.emissiveColor = new BABYLON.Color3(1, 0, 0);
material.alpha = 0.5;
box.material = material;
box.parent = root_node;

const ground = BABYLON.MeshBuilder.CreateGround("ground", {
    width: 100,
    height: 100
}, scene);
ground.material = material;
ground.parent = root_node;
```
## Example
An example can be found here: [cesium-babylonjs](https://github.com/Hypnosss/cesium-babylonjs).

Unity Toolkit

Coming next

Introduction to the Unity Toolkit

Introducing the features of the Unity Toolkit.

Scene Exporter

The features of the Unity Toolkit scene exporter.

Creating Projects

How to set up a project with the Unity Toolkit.

Script Components

The Unity Toolkit allows you to script your own components, allowing you to trigger game events, modify component properties over time and respond to user input in any way you like.

Scene Manager

The Unity Toolkit provides runtime life cycle management for game objects.

Shader Materials

Creating shader materials with the Unity Toolkit.

Physics Collider Components

Using colliders in the Unity Toolkit.

Terrain Builder

The Unity Toolkit terrain builder allows you to add vast landscapes to your games.

Animation System

The Unity Toolkit animation system includes features like retargetable animations, full control of animation weights at runtime, event calling from within the animation playback, sophisticated state machine hierarchies and transitions, blend shapes for facial animations, and much more.

Prefabs

The Unity Toolkit has a prefab asset type that allows you to store a game object complete with components and properties.

Static Batching

The Unity Toolkit static batching allows the engine to reduce draw calls for geometry of any size provided it shares the same material, and does not move.

Navigation Mesh

The Unity Toolkit navigation mesh approximates the walkable surfaces of the level.

Windows Platform

Using the Windows platform with the Unity Toolkit.

Art Tools

The Unity Toolkit art tools allow you to optimize your game assets for maximum performance using the WebGL platform.