
## Introduction

The Editor allows you to create and edit scenes without writing any code. However, each object in the scene can be customized by adding behaviors that developers can create using TypeScript. These behaviors can be attached to objects and will run when the game runs.

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 can be edited 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, a folder named `src` is available in the `Assets Browser` panel tree and contains all available scripts in the project starting from the `src` folder.

In the assets browser panel, browse the `src` folder, click `Add -> TypeScript File...`, and give it a name. Once done, a script is created from a template and is ready to be attached.

**Note: when no extension is provided, the `.ts` extension is automatically added.**

![AddingScript](/img/extensions/Editor/AttachingScripts/addingscript.webp)

## Attaching a script

We named our script `cube.ts`, and it will be attached to the cube in our scene for this tutorial. To attach a script, select the cube and go to the `Script` section in the Editor's inspector. We can now select the script to attach, so let us select `cube.ts`.

**Note: The inspector also supports dragging and 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.webp)

## Opening the project in VSCode and focusing on the script
To help locate the project and scripts in our workspace, we can open `Visual Studio Code` directly from the Editor. The Editor can also 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.webp)

## Understanding scripts

Scripts are used to specialize an object. This means they are attached to an existing object in the scene (for example, a mesh here). Each script will be notified:
* when it starts: this means when all assets are loaded and the 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 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 the `Node` class of Babylon.JS by default. Here, we attached the script to a cube, which is a mesh. Let us extend `Mesh` instead of `Node` so we will have auto-completion for `Mesh` when typing `this`:

![RenamingAndExtend](/img/extensions/Editor/AttachingScripts/renamingandextend.webp)

## Customizing scripts in the 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 make a property visible in the Editor, simply decorate it with `@visibleInInspector` in the script. More information about decorators is available 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` have been deprecated since v4.0.0-rc.2 and will be removed in v4.1.0.**

The `@visibleInInspector` decorator has the following 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

Once the property is decorated and the script is saved, the inspector is updated automatically and shows the newly
decorated property.

![UsingDecorators](/img/extensions/Editor/AttachingScripts/decorators.webp)

## Rotating the cube using the attached script

All TypeScript files are packed by default using 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 of 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 TypeScript files and repack the `dist` files.

Using the editor, simply open the preferences, go to the `Workspace` section, and enable automatic watch
(if not enabled):

![WatchingWebPack](/img/extensions/Editor/AttachingScripts/watchingwebpack.webp)

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 playing, each decorated property supports live updates. 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.webp)

## Managing scripts

It is **important** that script management be done using the `Assets Browser` panel:
- Moving
- Removing
- Renaming

Doing this in the Editor allows the Editor to automatically reconfigure objects that have attached scripts. For example,
when moving a script, all paths are updated internally.

**Note: once a script has been moved, etc., do not forget to update relative imports in the script to avoid compilation errors.**



## Introduction

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

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

**Note: the `KeyMap` type draws a button in the inspector that waits for the user to press a key on the keyboard**

Common configuration options for exposed properties are their type, name, and default value.
Example with a decorated property named `Speed`, of type `number`, and with a default value of `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 cannot be customized in
the editor.

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

## Understanding decorator options

As well as the 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 applied to the property when the user modifies it 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, each with 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 the script is saved and attached to at least one node, the inspector will show the exposed properties
according to their types and options. If the inspector is already focused on a node that has the edited script
attached to it, the inspector will be automatically updated.

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

As a full example, here is a script that uses the decorated `Speed` property to apply a rotation to 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 a scene can be done directly by decorating properties. The API provided by the editor
resolves the references automatically. This allows you to get component references directly when declaring properties
and avoids using functions such as `scene.getMeshByName(...)`, etc.

## Available decorators

### From Children

To get a reference to a child of the current node that has 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`, component references can be retrieved by traversing the entire scene using the
`@fromScene` decorator. This decorator works like `@fromChildren`, 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 Particle Systems

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

As with 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 with particle systems, animation groups are not nodes. To retrieve a reference to an animation group, simply decorate
the property with 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.

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

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

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

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

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

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, such as decorators, to help listen for events globally and on nodes. In other words, for
example with pointer events, the API can listen for events and pick the selected mesh in order to notify the decorated
method(s).

For example, here is how to listen for the `pointer tap` event on the current mesh that has 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 for 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 the 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 for
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 just as we get
using `scene.onPointerObservable.add((info) => { ... })`.

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

### On Keyboard Event

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

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

Example of listening for the `z` key being released:

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

Multiple keys can be listened to 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);
}
```



Learn how to create, edit, and attach scripts to nodes in a scene using the Babylon.js Editor.



## Applying Textures to Materials

Textures available in the assets browser can be applied to materials.
By default, textures available in the assets browser are not instantiated in the scene.

To instantiate textures in the scene and use them on materials, simply drag and drop the texture assets
into the appropriate list boxes in the inspector.

In the inspector, all list boxes related to textures (for example, `Environment Texture` in the scene inspector) support
drag and drop from the assets browser.

![ApplyTextureMaterialInspector](/img/extensions/Editor/AddingTextures/apply-material-inspector.webp)

## Cloning Textures

Multiple instances of the 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 the texture instance to create, and a new instance sharing the same texture file
is created and available in the assets panel.

As in the Assets Browser panel, textures from the assets panel can be dragged and dropped.

![CloningTexture](/img/extensions/Editor/AddingTextures/cloning-texture.webp)

## Editing A Texture

To edit a texture, simply click 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 so you can select the texture instance
to edit in the inspector.

![EditingTexture](/img/extensions/Editor/AddingTextures/editing-texture.webp)


Attaching scripts in Babylon.JS Editor

Coming next

Exposing properties

Understanding how to use the Babylon.JS Editor provided API to expose properties in the Inspector.

Attaching scripts

Understanding how to add and attach scripts on nodes in a Babylon.JS Editor project

Getting components

Understanding how to use the Babylon.JS Editor API to get component references.

Listening events

Understanding how to use the Babylon.JS Editor API to listen for events in an application.