
## Introduction

The Editor allows to create and edit scenes without any line of code. Anyway, each object in scene can be customized by adding behaviors that developers can create using TypeScript. These behaviors can be attached to objects and will wake up when the game is running.

As examples, a behavior can be:
* I have a camera and I'd like to launch a ball when I click, according to the camera's direction
* I have an object and I want it to scale up when the mouse is over
* etc. etc.

The Editor provides a way to create, manage and attach these scripts to all available objects in the scene. To customize scripts, the scripts can export properties (numbers, strings, booleans, vectors, keys, etc.) and these properties will be editable directly in the Editor.

Scripts can be attached to:
* Mesh
* Mesh Instance
* Light
* Camera
* Transform Node

**Note: all scripts are written using TypeScript**

**Note: the Editor is optimized to work with Visual Studio Code**

## Adding a new script

Once a workspace has been created, in the `Assets Browser` panel tree, a folder named `src` is available and browses all the available scripts in the project starting from the `src` folder.

In the assets browser panel, just browse the `src` folder click `Add -> TypeScript File...` and give it a name. Once done, a script has been created from a template and is now ready to be attached.

**Note: when no extension provided, the `.ts` extension is automatically added.**

![AddingScript](/img/extensions/Editor/AttachingScripts/addingscript.gif)

## Attaching a script

We named our script `cube.ts` and it'll be attached to the cube in our scene for this tutorial. To attach a script, just select the cube and go to the `Script` section in the Editor's inspector. We can now select the script to attach, let's select `cube.ts`.

**Note: The inspector also supports drag'n'dropping a script asset.**

**Note: only one script can be attached to an object but one script can be attached to multiple objects in the scene.**

![AttachingScript](/img/extensions/Editor/AttachingScripts/attachingscript.gif)

## Opening the project in VSCode and focus on the script
To help locating the project and scripts in our workspace, we can open `Visual Studio Code` directly from the Editor. Also, the Editor can open scripts directly.

* To open `Visual Studio Code`, just select `File -> Open Visual Studio Code` in the toolbar.
* To open a script, simply `double-click` the desired script in the assets browser panel.

![OpeningVSCodeAndScripts](/img/extensions/Editor/AttachingScripts/openingvscodeandscript.gif)

## Understanding scripts

Scripts are used to specialize an object. That means it'll be attached to an existing object in the scene (for example a mesh here). Each script will be notified:
* when it starts: means when all assets are loaded and game is ready. This is the function named `onStart` in the script.
* each frame: each time Babylon.JS renders a frame, the script is called immediately just before the frame is rendered? This is the function named `onUpdate` in the script.

By default, a script is named `MyScript` and it can be renamed. Also, a script extends, by default, the class `Node` of Babylon.JS. Here, we attached the script to a cube, which is a mesh. Let's extend `Mesh` instead of `Node` so we'll have auto-completion for `Mesh` when typing `this`:

![RenamingAndExtend](/img/extensions/Editor/AttachingScripts/renamingandextend.gif)

## Customizing scripts in editor

Scripts can be customized directly in the editor by setting custom properties. Available property types are:
* number
* string
* boolean
* vector (2d, 3d and 4d)
* key map

To set a property visible in the Editor, just decorate it `@visibleInInspector` in the script. More informations about decorators here: https://www.typescriptlang.org/docs/handbook/decorators.html#decorators

**These decorators are available in the file `src/scenes/decorators.ts`. Decorators in `src/scenes/tools.ts` are deprecated since v4.0.0-rc.2 and will be definitely removed in v4.1.0 version.**

The `@visibleInInspector` decorator has the given arguments:
* the property type (number, string, boolean, etc.)
* the name of the property to be shown in the Editor
* the default value of the property

On the property is decorated and the script saved, the inspector is updated automatically and shows the newly
decorated property.

![UsingDecorators](/img/extensions/Editor/AttachingScripts/decorators.gif)

## Rotating the cube using the attached script

All TypeScript files are packed using, by default, WebPack, including the scripts that are attached to objects. That means we have to watch (or build) the project to see the effect when running the game.

There are 2 ways to watch the project:
* Watch automatically with the Editor
* Watch using a command line that runs a script available in the package.json file or the project.

As a developer, using the command line, simply open a terminal at the root folder of the workspace and type:
```bash
npm run watch
```

This will watch ALL the TypeScript files and repack the dist files.

Using the editor, simply open the preferences, go to the `Workspace` section and enable the automatic watch
(if not enabled):

![WatchingWebPack](/img/extensions/Editor/AttachingScripts/watchingwebpack.gif)

Now, let's rotate the cube using our customized property `_speed` and run the game. In this tutorial, the `onStart` function is not used. When one of these functions is not used, it can be removed.

Once the scene is being played, each decorated property supports live update. In other words, each time a
decorated property value is modified in the inspector, the linked element in the scene being played has its
decorated property updated.

![RotatingCube](/img/extensions/Editor/AttachingScripts/rotatingcube.gif)

## Managing scripts

It is **important** that managing scripts must be done using the `Assets Browser` panel:
- Moving
- Removing
- Renaming

Doing this in the Editor allows to automatically re-configure objects that have the attached scripts. For example, 
when moving a script all paths will be updated internally.

**Note: once a script has been moved etc. don't forget to update relative imports in the script to suppress compilation errors.**



## Introduction

Script properties can be exposed and modified in the Editor. Using `@visibleInInspector` decorator, these
properties to expose can be customized and grouped in the `Inspector`.

Supported property types are:
- number
- string
- boolean
- Vector2
- Vector3
- Vector4
- Color3
- Color4
- Texture
- KeyMap

**Notes: the `KeyMap` type draws a button in the inspector waiting for the user to press a key in the keyboard**

Common configuration for exposed properties are its type, its name and its default value.
Example with a decorated property named `Speed` or type `number` and with default value `0.04`:

```typescript
@visibleInInspector("number", "Speed", 0.04)
private _speed: number;
```

The goal of these exposed properties is mainly to have one script attached to multiple nodes, where each node can
have its own script configuration. For example, using the `Speed` property, two nodes can have the same script
attached but will not rotate at the same speed.

## Importing decorators

Decorators are available in the `decorators.ts` file located at `src/scenes/`. Any attached script can import this
file and use the `@visibleInInspector` decorator. Scripts that are not attached to any node can't be customized in
the editor.

```typescript
import { visibleInInspector } from "../decorators";
```

## Understanding decorator options

As well as type, name and default value, the decorator has an `options` parameter used to customize the property
in the Editor. All fields are optional:
- **min**: defines the minimum value that can be set in the Editor field. Available only for numbers and vectors.
- **max**: defines the maximum value that can be set in the Editor field. Available only for numbers and vectors.
- **step**: defines the step to applied on the property when the user modifies the property in the Editor using the mouse.

**Note: If both `min` and `max` options are provided, the number field becomes a slider.**

In this example, 3 properties will be visible in the inspector having distinct options.

```typescript
@visibleInInspector("number", "Speed", 0.04, { min: 0, max: 1, step: 0.01 })
private _speed: number = 0.04;

@visibleInInspector("number", "Speed 2", 0.04, { min: 0, step: 0.01 })
private _speed2: number = 0.04;

@visibleInInspector("Vector3", "Gravity", Vector3.Zero(), { min: 0 })
private _gravity2: Vector3 = Vector3.Zero();
```

Once script is saved and attached to at least one node, the inspector will show the exposed properties
according to their properties and options. If the inspector is already focused on a node having the edited script
attached to it, the inspector will be automatically updated.

![example](/img/extensions/Editor/ExposingProperties/example.gif)

As a full example, a script that uses the `Speed` decorated property to apply a rotation on a mesh.

```typescript
import { Mesh } from "@babylonjs/core/Meshes/mesh";

import { visibleInInspector } from "../decorators";

export default class MyMeshComponent extends Mesh {
    @visibleInInspector("number", "Speed", 0.04, { min: 0, max: 1, step: 0.01 })
    private _speed: number = 1;

    /**
     * Called each frame.
     */
    public onUpdate(): void {
        this.rotation.y += 0.04 * this._speed;
    }
}
```



## Introduction

Getting references to components in scene can be done directly by decorating properties. The api provided by the editor
resolves the references automatically. This allows to get components references directly when declaring properties
and avoids to use functions such as `scene.getMeshByName(...)` etc.

## Available decorators

### From Children

To get the reference to a child of the current node having the script attached, properties in a script class can
be decorated using the `@fromChildren` decorator. The parameter of the decorator is the name of the child to get.

```typescript
@fromChildren("light")
private _light: PointLight;
```

This parameter is optional. If it is undefined, the name of the property is used. For example:

```typescript
@fromChildren()
private _light: PointLight; // the name of the child must be named "_light" in the Editor.
```

### From Scene

Compared to `@fromChildren`, components references can be retrieved by traversing the overall scene using the
`@fromScene` decorator. This decorator works like the `@fromChildren` one where the parameter is the name of the
node to retrieve. The parameter is also optional.

```typescript
import { Mesh } from "@babylonjs/core/Meshes/mesh";
import { DirectionalLight } from "@babylonjs/core/Lights/directionalLight";

import { fromScene } from "../decorators";

export default class MyMeshComponent extends Mesh {
    @fromScene("sun")
    private _sun: DirectionalLight;

    public onStart(): void {
        this._sun.intensity = 10;
    }
}
```

### From Particles Systems

In Babylon.JS, particle systems are not nodes. To retrieve particle systems, neither `@fromChildren` and `@fromScene`
decorators can be used. To retrieve particle systems, there is a specialized decorator named `@fromParticleSystems`.

As for other `@from{X}` decorators, the parameter of this decorator is the name of the particle system. If not provided,
the name of the property is used.

```typescript
import { Mesh } from "@babylonjs/core/Meshes/mesh";
import { ParticleSystem } from "@babylonjs/core/Particles/particleSystem";

import { fromParticleSystems } from "../decorators";

export default class MyMeshComponent extends Mesh {
    @fromParticleSystems("rain")
    private _rain: ParticleSystem;

    public onStart(): void {
        this._rain.start();
    }
}
```

### From Animation Groups

As for particle systems, animation groups are not nodes. To retrieve a reference to an animation group, simply decorate
the property using the `@fromAnimationGroups` decorator.

The parameter of this decorator is the name of the animation group. If not provided, the name of the property is used.

```typescript
import { Mesh } from "@babylonjs/core/Meshes/mesh";
import { AnimationGroup } from "@babylonjs/core/Animations/animationGroup";

import { fromAnimationGroups } from "../decorators";

export default class MyMeshComponent extends Mesh {
    @fromAnimationGroups("walk")
    private _walk: AnimationGroup;

    public onStart(): void {
        this._walk.play(true);
    }
}
```

### From Sounds

As for animation groups, sounds are not nodes. To retrieve a reference to a sound, simply decorate the property using
the `@fromSounds` decorator.

In order to retrieve the reference, the sound must be loaded in the project either attached to a node (spatialized)
or loaded as 2D sound.

![GetSoundPath](/img/extensions/Editor/GettingComponents/load-sound.png)

The parameter of this decorator is the name of the sound. In Babylon.JS, the name of a sound is its path provided
when the sound is being loaded. For example `assets/sounds/mySound.mp3`.

To get the name of a sound, the `Assets Browser` panel provides a helper by `right-clicking` the sound file. Simply
click on `Copy Path` in the context menu so the name of the sound is added to the clipboard and just paste it
in code editor on the parameter.

![GetSoundPath](/img/extensions/Editor/GettingComponents/sound-path.png)

Example:

```typescript
import { Mesh } from "@babylonjs/core/Meshes/mesh";
import { Sound } from "@babylonjs/core/Audio/sound";

import { fromSounds } from "../decorators";

export default class MyMeshComponent extends Mesh {
    @fromSounds("sounds/6sounds.mp3")
    private _sound: Sound;

    public onStart(): void {
        this._sound.play();
    }
}
```



## Introduction

The Editor api provides some tools, as decorators, to help listening events globally and on nodes. In other words, for
example on pointer events, the api can listen for events and pick the selected mesh in order to notify the decorated
method(s).

For example, listening for pointer event `pointer tap` on the current mesh having this script attached:

```typescript
import { Mesh } from "@babylonjs/core/Meshes/mesh";
import { Vector3 } from "@babylonjs/core/Maths/math.vector";
import { PointerEventTypes, PointerInfo } from "@babylonjs/core/Events/pointerEvents";

import { onPointerEvent } from "../decorators";

export default class MyMeshComponent extends Mesh {
    private _physicsEnabled: boolean = true;

    ...

    @onPointerEvent(PointerEventTypes.POINTERTAP, true)
    protected _tapped(info: PointerInfo): void {
        if (!this._physicsEnabled) {
            return;
        }

        const force = this.getDirection(new Vector3(0, 0, 1));
        this.applyImpulse(force, this.getAbsolutePosition());
    }

    ...
}
```

## Available Decorators

### On Pointer Event

To listen pointer events, the decorator `@onPointerEvent` can be used to decorate methods to call.
This decorator takes 2 arguments:
- the pointer event type (`PointerEventTypes` from `@babylonjs/core/Events/pointerEvents`).
- a boolean to indicate whether or not the method should be called only when, in case of a mesh, the mesh is picked.

The second boolean parameter is set to `true` by default. That means it must be set to `false` in order to listen
the pointer event globally.

```typescript
@onPointerEvent(PointerEventTypes.POINTERTAP, false)
protected _tapped(info: PointerInfo): void {
    // Called on the user clicks anywhere on the canvas.
}

@onPointerEvent(PointerEventTypes.POINTERTAP, true)
protected _tapped(info: PointerInfo): void {
    // Called on the user clicks on the mesh.
}
```

The method signature can define the `PointerInfo` reference which contains all the pointer event info such as we get
using `scene.onPointerObservable.add((info) => { ... })`.

**Note: the method will be called only and only if the scene containing the mesh is instantiated in the game/application**

### On Keyboard Event

As for `@onPointerEvent` decorator, the `@onKeyboardEvent` decorator can be used to decorate methods in a script.
This decorator takes 2 arguments:
- the key of keys to listen (as numbers or strings).
- the type of keyboard event to listen (key up or key down).

**Note: keyboard events are always listened globally**

Example listening for the `z` key being up:

```typescript
@onKeyboardEvent("z", KeyboardEventTypes.KEYUP)
protected _keyup(info: KeyboardInfo): void {
    console.log(info.event.key);
}
```

Multiple keys can be listened at the same time where the decorated method will be called when any of the specified
keys is triggered:

```typescript
@onKeyboardEvent(["z", "q", "s", "d"], KeyboardEventTypes.KEYUP)
protected _keyup(info: KeyboardInfo): void {
    console.log(info.event.key);
}
```

Using key codes instead of key values is deprecated but is still supported.

```typescript
@onKeyboardEvent(32 /* or [32, 53] for multiple keys */, KeyboardEventTypes.KEYUP)
protected _keyup(info: KeyboardInfo): void {
    console.log(info.event.keyCode);
}
```



Descriptions of how to create and edit physics on meshes in scene using the Babylon.js Editor.



## Applying Textures On Materials

Textures available in assets browser can be used and applied on materials.
By default, textures available in assets browser are not instantiated in scene.

In order to instantiate textures in the scene and use them on materials, simply drag'n'drop the texture assets
in the inspector on list boxes.

In the inspector, all list boxes related to textures (for example "Environment Texture" in scene inspector) support
drag'n'drop from assets browser.

![ApplyTextureMaterialInspector](/img/extensions/Editor/AddingTextures/apply-material-inspector.gif)

## Cloning Textures

Multiple instances of a same texture file can be created using the `Assets` panel.

Once a texture has been instantiated, it appears in the assets panel. Simply right-click the texture and select
`Clone...`. Enter the name of texture instance to create and finally a new instance sharing the same texture file
is created and available in the assets panel.

As for the assets browser panel, textures from the assets panel can be drag'n'dopped.

![CloningTexture](/img/extensions/Editor/AddingTextures/cloning-texture.gif)

## Editing A Texture

To edit a texture, simply click on it in the `Assets Browser` panel or `Assets` panel.
Once a texture has been clicked, the inspector is updated to show the editable properties of the clicked texture.

In the assets browser, if a texture file has multiple instances, a menu appears to select the texture instance
to edit in the inspector.

![EditingTexture](/img/extensions/Editor/AddingTextures/editing-texture.gif)
