> This is part 1 of 2 of the full documentation (pages 1–100 of 174).
> The content is paginated: fetch every part to see all of it.
> Next part: https://docs.hology.app/llms-full.txt/1
> Page index: https://docs.hology.app/llms.txt

# Welcome to Hology Docs

This site is designed to help new users get started with Hology as well as to be a resource for experienced users to learn about everything there is to know. New articles will be added over time.

## How to get support

If you have any questions about Hology or need help with something, please contact us at <hello@hology.app>. We would be happy to guide you via email or set up a call.

## How to start

1. Follow the [The first steps](https://docs.hology.app/getting-started/the-first-steps) guide for the basics of setting up Hology and running your application or game.
2. Get a grasp for how to use the editor with the [Editor basics](https://docs.hology.app/getting-started/editor-basics) guide.
3. Follow the gameplay tutorial [Rolling ball - Gameplay programming](https://docs.hology.app/tutorials/rolling-ball-gameplay-programming)
4. Download the [Starter project - Third person shooter](https://docs.hology.app/getting-started/starter-project-third-person-shooter) to see an example of how to set up character movement.


# Introduction to Hology

Hology is a game engine that allows users to create 3D games and experiences using web technologies such as Typescript, HTML and CSS. What you can create can be used in a website, mobile application or installed as a desktop application. It provides tooling that makes it easier to develop 3D experiences such as a 3D editor to create your scenes (game levels) and a game play framework.


# The first steps

## Installing the editor

The editor can be installed on Windows, Mac and Linux. Follow the link below.

[Download editor](https://hology.app/download)

#### Installing on Windows

If you download for windows, you may see a blue window saying that "Windows protected your PC". Simply click "More info" and then click "Run anyway".

## Prerequisites

### Software

In addition to the editor, you need to have both Node.js installed as well as a code editor. Any code editor should work. A popular one is Visual Studio Code.

[Download Node.js](https://nodejs.org/en/download)

[Download Visual Studio Code](https://code.visualstudio.com/download)

### Knowledge

In order to create something with Hology, some previous knowledge of web development and related technologies is necessary. This includes Typescript, HTML, CSS and how to use a terminal.

## Create a new project

To create a new project, open the Hology editor on your computer.

Click "Create a new project". Then set the name of the project, which could be the name of a game you will create. A template can be selected as a starting point. Select a UI framework such as React which will be set up for you in the project's code base that will be created that when creating the project.

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2Fgit-blob-64cf0d71920c418e05b3d76905609da6f40bf21b%2FScreenshot%202023-09-12%20at%2018.09.28.png?alt=media" alt=""><figcaption></figcaption></figure>

After clicking "Create", the project's code base will be setup and various dependencies necessary to build your project will be installed. After the installation has completed, your project should open in a new window.

A scene, which can represent the entire world of your game or a single game level, is created for you called demo. In order to use that scene in your game, you will refer to the name of the scene in your code.

## Running your game in a browser

The project is essentially just a website which means that during development, you can run the project game inside your browser.

To run you project, open a terminal and navigate to the project's folder and run the command`npm run dev`.

{% code fullWidth="false" %}

```
cd /path/to/my-project
npm run dev
```

{% endcode %}

A "localhost" address is logged (<http://localhost:5173/>). Open this address in your browser and you should now see your scene. Any changes you make to the scene in the Hology editor will be reflected in the browser window after refreshing.

### Using Powershell (Windows only)

If you are using windows, your default terminal is normally set to Powershell. You may get an error like below. This is expected if you have not previously configured Powershell to allow running scripts.&#x20;

```
npm : File C:\Program Files\nodejs\npm.ps1 cannot be loaded because running scripts is disabled on this system.
```

Run the following command in the Powershell terminal to enable running scripts.

```
Set-ExecutionPolicy Unrestricted -Scope CurrentUser
```

#### Recommended VS Code extensions

If you are using VS Code as your code editor, the following extensions can help improving your workflow.&#x20;

* **Copy with imports** - This automatically generates imports for you when you copy code. When following tutorials, you will be copying and pasting code a lot and this extensions helps to not having to specify the imports manually.&#x20;
* **Pretty Typescript Errors** - Improves formatting of errors in code
* **Move TS - Move TypeScript files and update relative imports** - When moving files, it can be tedious to update imports. This fixes this.&#x20;
* **Git Graph** - Git it the recommended version control solution and you definitely should have version control in any coding project including hology engine projects. This extension makes it easier to have an overview of the git history and branches in VS Code as it shows the entire history of commits and you can easily inspect the changes performed in a previous commit as well as to revert back to a previous state.&#x20;


# Editor basics

The Hology Editor enables you to design your game worlds and levels. It provides an interface to manage assets and various tools for placing and changing objects. This page will explain in more detail how to use the editor.

{% embed url="<https://youtu.be/dDrOy6PYHi0?si=YZFcmaWAVlfwWWiQ>" %}

## Panels

### Asset browser

The asset browser contains content that can be used in your scenes. It contains many built in assets such as simple shapes and actors as well as your own imported assets.

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2Fgit-blob-4ad2d03d4f24e5a966ac43e8b0f48f18da0cac65%2FScreenshot%202023-11-02%20090559.png?alt=media" alt=""><figcaption></figcaption></figure>

#### Categories

Assets are grouped by category. Select the category with this drop down selector.

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2Fgit-blob-592dbcc74eaad7d6c9a291bd7c3ebcf9e6b5a81a%2FScreenshot%202023-11-02%20090154.png?alt=media" alt=""><figcaption><p>Asset category selector</p></figcaption></figure>

### Outliner

The outliner presents a hierarchy of objects in your scene. It allows you to select objects as well as to perform various actions on the objects.

* Select a range of objects by first selecting an object, hold down **shift** and select another.
* Add additional objects your your selection by holding down **ctrl / ⌘**

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2Fgit-blob-f9df1ae4c5edadf09628ccadefa6dbd2dac85281%2FScreenshot%202023-11-02%20090440.png?alt=media" alt=""><figcaption><p>Outliner</p></figcaption></figure>

### Control bar

The control bar contains easily available setting for quickly changing how you view your scene in the editor and for how some tools work.

The buttons are explained in order:

* **Local transform**: Click to toggle the transform tool to work in local space. In local space, the axis for scale and move will be aligned with the object's rotation rather than the world.
* **Grid**: Enable snapping when moving or placing objects. Snapping can help more accurately placing objects either right next to each other or with an even space between. This enables you to work more effectively with modular assets such as building component that for example have a standard with and height so that they can be placed exactly next to each other.
* **2D**: Show the scene in a top down orthographic view. This can be helpful to align items more easily than when using a perspective camera.
* **Camera settings**: Control the flying camera movement, field of view, view distance and whether collision shapes should be rendered.

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2Fgit-blob-117bf1c89af10ae799104a0488eb2048fabc53d4%2FScreenshot%202023-11-02%20091355.png?alt=media" alt=""><figcaption></figcaption></figure>


# Flying in scenes

In order to move around the scene, you can use your keyboard and mouse to move and rotate. You need to hold down the right mouse button in order to move and rotate.

## Movement keys

* **W**: Forward
* **Q**: Down
* **E**: Up
* **A**: Left
* **D**: Right
* **S**: Backward

You can hold down multiple keys to move diagonally.

### Speed boost

Hold down the shift key when moving

## Rotate camera

To rotate the camera, hold down the right mouse button and move the mouse.


# Placing objects

When you first create a scene, it is empty. To add something to it, use the asset browser at the bottom. In the asset browser you can find not only your own imported assets but also some assets that exist by default such as shapes. Select shapes in the asset type selection box on the top to the left in the asset browser. Then click on one of the shapes and then click "Add to scene". Move your mouse to the scene and click your left mouse button to place the shape in your scene.


# Select objects

To edit an object in your scene, click on the objects in the scene or in the outliner to select an object.

## Selecting multiple objects

It can sometimes be convenient to select multiple objects at once. This allows some features to act on all objects that are selected to be more effective.

Some things you can do while selecting multiple objects:

* Move, rotate and scale all object in your selection. For rotation and scaling, the objects will be transformed around a point in the middle of the selected objects.
* Create a group of the selected objects. Read more about [Grouping objects](https://docs.hology.app/getting-started/editor-basics/grouping-objects)
* Move all selected object inside another group by dragging them in the outliner.
* Delete all objects in your selection at once by clicking Backspace (←) on your keyboard.

### How to select and deselect multiple objects

* **Select additional in scene:** Hold down Shift on your keyboard as you click on another object in the scene with your left mouse button.
* **Select additional in outliner:** Hold down Ctrl or Cmd (⌘) on your keyboard as you click on an object in the outliner to add it to your selection.
* **Select a range in outliner:** With another object already selected, hold down Shift on your keyboard and click on another object in the outliner to add the object you clicked on and all object in-between to your selection.
* **Remove object from selection in outliner:** Hold down Alt or Option (⌥) on your keyboard as you click on one of your selected objects in the outliner to remove the object from your selection.


# Transform

Selected objects can be moved, rotated and scaled. With your objects selected, use one of the transform tools. These tools can be used by either clicking on the respective tool in the toolbar on the left or more conveniently by using the keyboard shortcuts.

### Transform keyboard shortcuts

* **W:** Move (also known as translate)
* **E:** Rotate
* **R:** Scale

### Exit the transform

When you are done transforming the objects, you can exist the transform in a few ways.

* Click somewhere on the scene that is not one of your selected objects
* Click on the selection tool in the toolbar (the top most one).
* Click Escape or Enter on your keyboard.


# Grouping objects

Groups enable you to organize objects in your scene. In the outliner, groups appear as an object that can be expanded to contain all objects inside it.

Objects inside groups also have a relative transform to their group. This enables you to move, rotate and scale and entire group of objects easily.

Use Ctrl+G or ⌘+G to create a group of the selected objects. You need to select at least two objects to create a group.

### Re-organizing groups

You can add more objects to groups as well as remove objects from a group. This can be done in the outliner by clicking and dragging objects that you want to move into our out of your group.


# Duplicate

Adding more of the same objects is a fast way to add more content to your scenes.

### Duplicate and place

When you have one or more objects selected, click Ctrl+D or Cmd+D (⌘+D). You should now see a yellow sphere which indicates where your duplicate objects will be placed. Click with your left mouse button to place the duplicate objects. The selected objects relative location to each other will remain.

### Duplicate during transform

When you have one or more objects selected and you have a transform tool active such as Move, Rotate or Scale, click Ctrl+D or Cmd+D (⌘+D) to directly duplicate the objects in place. Your transform will not transfer over to the new, duplicated objects so that you can instead transform them. This can be convenient when you want to quickly duplicate and move or rotate objects.


# Starter project - Third person shooter

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2Fgit-blob-c706b5e192c2ace76f6979e4c385b2c2278c2d42%2FScreenshot%202024-05-05%20at%2011.45.29.png?alt=media" alt=""><figcaption></figcaption></figure>

To jumpstart your development, a small project has been created. This project can be used as a starting point for a game of your own or just a way to learn how a project can be structured.

{% embed url="<https://github.com/hologyengine/starter-third-person-shooter>" %}

The following sections will explain how to get setup with the project.

## Download the project

Provided that you have Git installed, you can run the following commands in your terminal to download the project. If you don't have Git installed, you can download it from <https://git-scm.com/download/>.

```
git clone https://github.com/hologyengine/starter-third-person-shooter.git
cd starter-third-person-shooter
npm ci
```

## Run the project

Once the project is downloaded, run the following command from within the project's directory. This should run the game as a website that you can view by opening <http://localhost:5173/> in your browser.

```
npm run dev
```

## Opening the project in the editor

In the editor's launcher, click on "Open an existing project". Navigate to the project's folder.

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2Fgit-blob-97c72838715409c7e54f963455a92b6c44ad513c%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

To make sure you select the correct folder. The folder you see should have the following folders in it:

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2Fgit-blob-e082c65b5d576604244bdd2bb896bcc308b6dd9f%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

## Where to go from here

Take a look around the code base to see how actors and components are implemented. When reading about other subjects in the docs, you can refer back to this project to see how features are being used in practice.

### Continue building on the project

You now have the basic building blocks to start creating games. The only limit is your imagination.

Here are some ideas of things you could try to build

* **Limited ammunition system**: Keep track of how much ammo the player has. Display this in the user interface and prevent the player from shooting when it has no more ammo. Create an ammo box actor with a trigger volume to let the player pick up ammo by running over them.
* **Add your own models:** Replace the character model and others in the scene.
* **Enemies:** Spawn enemy characters that are controlled by AI that will shoot the player. Implement a health component to keep track of each character's health.


# Rolling ball - Gameplay programming

**Level:** Beginner

In this tutorial, we will create a small game as a way to learn the basics of Hology Engine. The game we will create is about moving a ball from a spawn point to a target. The player will be able to apply forces to the ball to make it move.

You will learn the basics of implementing game play mechanisms in Hology such as how to connect player input to an object controlled by the player, how to apply physical forces, using spawn points and handling events with trigger volumes.

{% hint style="info" %}
**Prerequisites**

Before continuing, you need to create a new project and familiarise yourself with the basics of the editor. Go through the article [The first steps](https://docs.hology.app/getting-started/the-first-steps) to learn how to set up a project. Then learn how to navigate in the editor using the articles in [Editor basics](https://docs.hology.app/getting-started/editor-basics).

While some coding skills are useful, all the code needed will be provided in this tutorial.

Concepts are explained in the tutorials and just briefly explained. Other articles will go into depth to explain these concepts.
{% endhint %}

{% embed url="<https://youtu.be/lYxItVMsY-8?si=7RUbOZwB0bWmev7x>" %}

### **Setup a scene**

To create our initial scene, we need 3 things.

1. Create a **box** that will act as a platform for our ball to roll on. To add a box, select shapes in the asset browser, click and drag the box into the scene. Use the scale tool by selecting the box and clicking R on your keyboard or use the toolbar on the left. Make the size of the box about 2 meters wide (X), 1 meter thick (Y), 5 meters long (Z),
2. Add a **spawn point** on one end of the box. Spawn points are actors which can be found in the asset browser. Click and drag it into the scene.
3. Add a **trigger volume** and place it on the opposite side of the box.

This is all we need to start developing the game. We can come back later to create a more interesting and challenging game level.

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2Fgit-blob-3c3c3f523725733ce7003adfb138bdbde531c282%2FScreenshot%202024-03-09%20at%2016.58.13.png?alt=media" alt=""><figcaption></figcaption></figure>

### Coding the game

Now that we have a basic scene setup, we can get into the code. In summary, we will need to code the following:

* **Ball actor**
  * The visual and physical representation of the ball
  * Spawning the ball actor
  * Adding forces to the ball using player input
* **Player camera**
  * Make the camera follow the ball to create a third person view.
* **Player controller**
  * Setup player input handling so the ball actor can apply forces based on what keys the player is pressing.
* **Respawning**
  * When the ball reaches the goal or falls of the map, it should reset its position to the spawn point.

### Create the ball actor

Let’s start by creating the most important character in our game, the ball. Create a new file in your code editor with the path `src/actors/ball-actor.ts` in the project. Add the following code to the file to start and save the file. We will go over this in detail to understand what goes on.

```tsx
import { PhysicalShapeMesh, SphereCollisionShape } from "@hology/core";
import { Actor, BaseActor, PhysicsBodyType, attach } from "@hology/core/gameplay";
import { MeshComponent } from "@hology/core/gameplay/actors";
import { NodeShaderMaterial, rgba, select, varyingAttributes } from "@hology/core/shader-nodes";
import { SphereGeometry } from "three";

const ballMaterial = new NodeShaderMaterial({
  color: select(varyingAttributes.position.y.lt(0), rgba(0xffff00, 1), rgba(0x00ffff, 1))
})

@Actor()
class BallActor extends BaseActor {
  private mesh = attach(MeshComponent<PhysicalShapeMesh>, {
    object: new PhysicalShapeMesh(
      new SphereGeometry(.2, 50, 50), 
      ballMaterial, 
      new SphereCollisionShape(0.2)),
    bodyType: PhysicsBodyType.dynamic,
    mass: 2,
    friction: 1
  })
}

export default BallActor
```

<details>

<summary>Code explanation</summary>

At first, we create a material to use for the ball. If we were to simply use a single color, it wouldn’t be possible to see that the ball is in fact rolling. While we could use a texture for this, another easier approach can be to use a custom shader as we do here. To assign a color to each half of the sphere, we can use the varying position attribute. If the position’s y value is less than 0, we can use one color and otherwise another.

```tsx
const ballMaterial = new NodeShaderMaterial({
  color: select(varyingAttributes.position.y().lt(0), rgba(0xffff00, 1), rgba(0x00ffff, 1))
})
```

Next we define the actor class and export it so that we can use it elsewhere in our code.

```tsx
@Actor()
class BallActor extends BaseActor {
}

export default BallActor
```

Inside the actor we define a property as we attach the `MeshComponent`. This component provides both the visual representation and how physics should work. We use a SphereCollisionShape with the same radius as the SphereGeometry to make the ball behave as expected. The body type is set to dynamic so that we can use forces to affect the ball’s movement. We also set the mass and friction to some values to start with. Later on, when you have the game is running, feel free to change these to see how it affects the gameplay.

```tsx
  private mesh = attach(MeshComponent<PhysicalShapeMesh>, {
    object: new PhysicalShapeMesh(
      new SphereGeometry(.2, 50, 50), 
      ballMaterial, 
      new SphereCollisionShape(0.2)),
    bodyType: PhysicsBodyType.dynamic,
    mass: 2,
    friction: 1
  })
```

</details>

### Adding the ball to the world

Instead of adding the ball to the scene in the editor, we will use the spawn point we created earlier. In the file `src/services/game.ts`, replace its content with the following code.

```tsx
import { GameInstance, Service, World, inject } from '@hology/core/gameplay';
import { SpawnPoint } from '@hology/core/gameplay/actors';
import BallActor from '../actors/ball-actor';

@Service()
class Game extends GameInstance {
  private world = inject(World)

  async onStart() {
    const spawnPoint = this.world.findActorByType(SpawnPoint)
    const ball = await spawnPoint.spawnActor(BallActor)
  }
}

export default Game
```

This is the main class from which we setup the game. We will add more to this class later on in the tutorial.

<details>

<summary>Code explanation</summary>

To find something in the world and to add something to it, we need to inject the World class where we want to use it. We create a new property on the `Game` class and use the inject function with the World class.

```tsx
private world = inject(World)
```

Inside the onStart method, which will be called automatically by the engine as the game starts, we can put our code to setup the gameplay. The first line here is used to find the spawn point that we placed in the scene. We can find an actor by its class. The function findActorByType will return the first actor it finds with the actor class we pass in. As we only have one spawn point in the scene, this works for us.

```tsx
const spawnPoint = this.world.findActorByType(SpawnPoint)
```

On the second line we use use the spawn point to spawn the actor.

```tsx
const ball = await spawnPoint.spawnActor(BallActor)
```

It could be good to know that you don’t necessarily need spawn points to spawn actors. This is just a shorthand for using the `world.spawnActo`r function to which you can pass in any position and rotation. You can achieve the same thing with the following code.

```tsx
const ball = await this.world.spawnActor(BallActor, spawnPoint.position, spawnPoint.rotation)
```

</details>

### Applying forces

Next up, we will add the code for controlling the ball with physics. While the ball is controlled by the physics simulation, we want to be able to apply a force forward or backward in the direction the player is rotated towards.

Replace the code in the ball-actor.ts file created earlier with the following code.

```tsx
import { PhysicalShapeMesh, SphereCollisionShape } from "@hology/core";
import { Actor, BaseActor, PhysicsBodyType, PhysicsSystem, attach, inject } from "@hology/core/gameplay";
import { MeshComponent } from "@hology/core/gameplay/actors";
import { AxisInput } from "@hology/core/gameplay/input";
import { NodeShaderMaterial, rgba, select, varyingAttributes } from "@hology/core/shader-nodes";
import { Euler, SphereGeometry, Vector3 } from "three";

const ballMaterial = new NodeShaderMaterial({
  color: select(varyingAttributes.position.y.lt(0), rgba(0xffff00, 1), rgba(0x00ffff, 1))
})

@Actor()
class BallActor extends BaseActor {  
  private mesh = attach(MeshComponent<PhysicalShapeMesh>, {
    object: new PhysicalShapeMesh(
      new SphereGeometry(.2, 50, 50), 
      ballMaterial, 
      new SphereCollisionShape(0.2)),
    bodyType: PhysicsBodyType.dynamic,
    mass: 2,
    friction: 1
  })
  
  private physicsSystem = inject(PhysicsSystem)
  public readonly axisInput = new AxisInput()
  public readonly direction = new Vector3() 

  onInit() {
    this.physicsSystem.setLinearDamping(this, .2)
    this.physicsSystem.setAngularDamping(this, 5)

    const rotation = new Euler().set(0, this.rotation.y, 0)
    const impulse = new Vector3()

    const inputForce = 100
    const sensitivity = 1.8
    
    this.physicsSystem.beforeStep.subscribe(deltaTime => {
      rotation.y += deltaTime * -this.axisInput.horizontal * sensitivity
  
      this.direction
        .set(0,0,1)
        .applyEuler(rotation)

      impulse
        .copy(this.direction)
        .multiplyScalar(inputForce * deltaTime * this.axisInput.vertical)

      this.physicsSystem.applyImpulse(this, impulse)
    })
  }
}

export default BallActor
```

<details>

<summary>Code explanation</summary>

First, we added some new properties to the class.

The physics system is injected to be available to our actor. This service is used later to hook into the physics processing and apply forces.

```tsx
private physicsSystem = inject(PhysicsSystem)
```

We create an axisInput property which we later will use to connect the player’s input. We can use the state of the axis input to know how the player wants to move without having to worry about key presses or key binds in this context.

```tsx
public readonly axisInput = new AxisInput()
```

A direction vector is set up and made public. This will be used later to position the camera. Note that this is the direction that the player rotated to, not the direction vector of the ball as that will be spinning as the ball is rolling around.

```tsx
public readonly direction = new Vector3() 
```

Inside the onInit method, the first thing we do is to apply damping. Although not always necessary, damping helps simulate air resistance. This will slow down its movement and rotation to prevent it from spinning out of control or going hypersonic. If these values are too high however, it can make it feel sluggish.

```tsx
this.physicsSystem.setLinearDamping(this, .2)
this.physicsSystem.setAngularDamping(this, 5)
```

A rotation variable is defined which should represent the rotation of the direction the player want to face. We use the initial rotation around the y axis of the actor here so that we can face towards the direction of the spawn point.

```tsx
const rotation = new Euler().set(0, this.rotation.y, 0)
```

When we later apply forces as an impulse we need to do some vector math. Creating new vectors every physics step is something we want to avoid as it creates more work for the garbage collector. A common pattern is therefore to create the vectors you need upfront and then perform operations that change the vector.

```tsx
const impulse = new Vector3()
```

To execute before each physics step, the physics system exposes a beforeStep observable to which we can subscribe and get access to the time since the last update, which is referred to as deltaTime. In the subscription callback, we will place the code that should update before the physics step which will be described below.

```tsx
this.physicsSystem.beforeStep.subscribe(deltaTime => {
})
```

At first, modify the rotation around the y axis using the axis input’s horizontal value. Because this is called on each physics step, we want to use the deltaTime to make sure that updates are consistent even if updates were to happen more or less frequently. Also, a sensitivity constant is applied to be able to control how much the rotation is changed.

```tsx
rotation.y += deltaTime * -this.axisInput.horizontal * sensitivity
```

Then, the rotation is applied to the vector. Note how we first initialize the vector to point forward down the Z axis and then apply the rotation.

```tsx
this.direction
    .set(0,0,1)
    .applyEuler(rotation)
```

The impulse is a vector for how much force to apply at this step. We calculate the impulse by multiplying the direction vector which represents how much force to apply. The axis input’s vertical property will be either 1 or -1 depending on if the player presses the key to go forward or backward. Notice again how we use the deltaTime value to ensure the force is applied consistently and not dependent on how frequent the physics step is.

```tsx
impulse
    .copy(this.direction)
    .multiplyScalar(inputForce * deltaTime * this.axisInput.vertical)

this.physicsSystem.applyImpulse(this, impulse)
```

</details>

If you were to open the game in your browser now, you would likely not see much of the scene you created or the spawned ball because the camera is positioned at the world’s origin point 0,0,0. In the next section we will program the player’s camera to follow the ball.

{% hint style="info" %}
**Using physics for controlling a player character**

In many games that has a character, you would likely not use a dynamic physics body as we do here as it would make it hard to control. However, in this game, the idea is that being hard to control is the main challenge and is something that the player will learn to master the more they play. If you are creating a game with a character, look into using the built in character controller which is using a kinematic physics body or create your own with a similar approach.
{% endhint %}

### Player camera

Start by creating a file at src/services/player-camera.ts and add the following code.

```tsx
import { Service, ViewController, inject } from "@hology/core/gameplay";
import { Vector3 } from "three";
import BallActor from "../actors/ball-actor";

@Service()
class PlayerCamera {
  private view = inject(ViewController)
  private cameraOffset = new Vector3(0, .5, 0)

  public setup(target: BallActor) {
    const camera = this.view.getCamera()

    this.view.onLateUpdate(target).subscribe(() => {
      camera.position
        .copy(target.position)
        .addScaledVector(target.direction, -2)
        .add(this.cameraOffset)
      camera.lookAt(target.position)
    })
  }
}

export default PlayerCamera
```

Before going into details of what happens in this code, we can start using it from the Game class. In the file `src/services/game.ts`, replace the code with the following. Note that we only added a couple of lines. We added the import of the `PlayerCamera` class, injected the `PlayerCamera`, and in the onStart method, called the setup method.

```tsx
import { GameInstance, Service, World, inject } from '@hology/core/gameplay';
import { SpawnPoint } from '@hology/core/gameplay/actors';
import BallActor from '../actors/ball-actor';
import PlayerCamera from './player-camera';

@Service()
class Game extends GameInstance {
  private world = inject(World)
  private playerCamera = inject(PlayerCamera)

  async onStart() {
    const spawnPoint = this.world.findActorByType(SpawnPoint)
    const ball = await spawnPoint.spawnActor(BallActor)
    this.playerCamera.setup(ball)
  }
}

export default Game
```

If you now open the game in your browser by going to <http://localhost:5173>, you should be able to see the ball. Make sure you also run the game in development mode by running `npm run dev` in the terminal in the game project’s directory.

<details>

<summary>Code explanation</summary>

Let’s go over the PlayerCamera. First, we define a new service. There will only be one instance of a service in a game. As we only will have one camera for the player, we can use a service to contain this code. We use the `@Service()` decorator on top of the class to denote that this is a service which we need for dependency injection. Other than that, it is just a regular TypeScript class.

```tsx
@Service()
class PlayerCamera {

}

export default PlayerCamera
```

To access the default camera and to execute code every frame, we can use the `ViewController` service. This is injected like any other service as a property in our `PlayerCamera` class.

```tsx
 private view = inject(ViewController)
```

An offset property for the camera is created. We will use this later to slightly offset the camera’s position upwards in the Y axis so we more easily can see what is in front of the ball.

```tsx
private cameraOffset = new Vector3(0, .5, 0)
```

We define a method called setup which takes a BallActor. The point of this method is to setup the view controller to follow a specific BallActor instance.

```tsx
public setup(target: BallActor) {
}
```

We access the currently active camera of the view. By default, there is always one camera available. Note that it is possible to have multiple cameras in your game and you can switch between them by setting the active camera in the `ViewContoller`.

```tsx
const camera = this.view.getCamera()
```

Then, we want to execute some code every frame to update the position of the camera. This can be done using the onLateUpdate method which returns an observable. This method can also optionally take an actor instance as an argument. If this actor is removed from the world and disposed, the observable will stop generating events every frame. We are using a late update here which is the event that gets triggered after all other per frame updates and the physics step. This enables us to update the position of the camera after the physics system has updated the position of the ball.

```tsx
this.view.onLateUpdate(target).subscribe(() => {
})
```

To position the camera, we first copy the position of the ball so the camera is at the center of the ball. Then we adjust the position in the negative direction of the player’s direction. The value 2 here means that we position the camera 2 meters behind the center of the ball. To also move the camera slightly above the ball, we add the camera offset vector we defined before.

Finally, we call the `lookAt` method on the camera to rotate towards the center of the ball.

```tsx
camera.position
    .copy(target.position)
    .addScaledVector(target.direction, -2)
    .add(this.cameraOffset)
camera.lookAt(target.position)
```

</details>

While we now can see the ball in the game, the only force applied to the ball is gravity. In the next section we will set up player input to change that.

### Player controller

Create a file at `src/services/player-controller.ts` and add the following code.

```tsx
import { Service, inject } from "@hology/core/gameplay";
import { InputService, Keybind } from "@hology/core/gameplay/input";
import BallActor from "../actors/ball-actor";

enum InputAction {
  moveForward,
  moveBackward,
  rotateLeft,
  rotateRight,
}

@Service()
class PlayerController {
  private inputService = inject(InputService)

  public setup(ballActor: BallActor) {
    this.inputService.bindToggle(InputAction.moveForward, ballActor.axisInput.togglePositiveY)
    this.inputService.bindToggle(InputAction.moveBackward, ballActor.axisInput.toggleNegativeY)
    this.inputService.bindToggle(InputAction.rotateLeft, ballActor.axisInput.toggleNegativeX)
    this.inputService.bindToggle(InputAction.rotateRight, ballActor.axisInput.togglePositiveX)

    this.inputService.setKeybind(InputAction.moveForward, new Keybind('w'))
    this.inputService.setKeybind(InputAction.moveBackward, new Keybind('s'))
    this.inputService.setKeybind(InputAction.rotateLeft, new Keybind('a'))
    this.inputService.setKeybind(InputAction.rotateRight, new Keybind('d'))

    this.inputService.start()
  }
}

export default PlayerController
```

<details>

<summary>Code explanation</summary>

Again, we use a service to separate out the code for setting up player input.

At first we define the actions a player can do as an enum.

```tsx
enum InputAction {
  moveForward,
  moveBackward,
  rotateLeft,
  rotateRight,
}
```

In the setup method of the `PlayerController`, we bind functions to call with either true or false when an action is used.

```tsx
this.inputService.bindToggle(InputAction.moveForward, ballActor.axisInput.togglePositiveY)
this.inputService.bindToggle(InputAction.moveBackward, ballActor.axisInput.toggleNegativeY)
this.inputService.bindToggle(InputAction.rotateLeft, ballActor.axisInput.toggleNegativeX)
this.inputService.bindToggle(InputAction.rotateRight, ballActor.axisInput.togglePositiveX)
```

Then, we add keybinds for these actions. By separating the keybinds from the rest of our code like this, we can easily reconfigure keybinds even while the game is running. This could enable the player to change keybind settings which could be stored on the device and loaded to replace the defaults.

```tsx
this.inputService.setKeybind(InputAction.moveForward, new Keybind('w'))
this.inputService.setKeybind(InputAction.moveBackward, new Keybind('s'))
this.inputService.setKeybind(InputAction.rotateLeft, new Keybind('a'))
this.inputService.setKeybind(InputAction.rotateRight, new Keybind('d'))
```

Finally, we must call start on the input service so that the game engine will start monitoring key presses.

```tsx
this.inputService.start()
```

</details>

To setup the player controller, we need to take the same steps we did with the player camera.

Replace the `game.ts` file with the following code. We import the `PlayerController` class, inject it, and call the setup method.

```tsx
import { GameInstance, Service, World, inject } from '@hology/core/gameplay';
import { SpawnPoint } from '@hology/core/gameplay/actors';
import BallActor from '../actors/ball-actor';
import PlayerCamera from './player-camera';
import PlayerController from './player-controller';

@Service()
class Game extends GameInstance {
  private world = inject(World)
  private playerCamera = inject(PlayerCamera)
  private playerController = inject(PlayerController)

  async onStart() {
    const spawnPoint = this.world.findActorByType(SpawnPoint)
    const ball = await spawnPoint.spawnActor(BallActor)
    this.playerCamera.setup(ball)
    this.playerController.setup(ball)
  }
}

export default Game

```

Now when you try the game in your browser at <http://localhost:5173/>, you should be able to move the ball by pressing W,A,S,D on your keyboard. When you fall off the platform, reload the browser tab to respawn. In the next section, we will go into how to automatically respawn.

### Respawning

When the ball rolls of the platform it will just continue to fall forever, which is not very fun. Instead, we can reset the ball’s position. One way to do this is to check every frame if the ball’s position in the y axis is below a certain value.

Replace the contents of the file `src/services/game.ts` with this the following code.

```tsx
import { GameInstance, Service, ViewController, World, inject } from '@hology/core/gameplay';
import { SpawnPoint } from '@hology/core/gameplay/actors';
import BallActor from '../actors/ball-actor';
import PlayerCamera from './player-camera';
import PlayerController from './player-controller';

@Service()
class Game extends GameInstance {
  private world = inject(World)
  private playerCamera = inject(PlayerCamera)
  private playerController = inject(PlayerController)
  private view = inject(ViewController)

  async onStart() {
    const spawnPoint = this.world.findActorByType(SpawnPoint)
    const ball = await spawnPoint.spawnActor(BallActor)
    this.playerCamera.setup(ball)
    this.playerController.setup(ball)

    this.view.onLateUpdate().subscribe(() => {
      if (ball.position.y < -10) {
        ball.moveTo(spawnPoint.position)
      }
    })
  }
}

export default Game
```

We injected the view controller and use it to subscribe to the onLateUpdate event. In this, we check if the ball’s position in the y axis is less than the hard coded value -10. If that is the case, we call a new method on the ball called moveTo which we will define up next.

In the ball actor’s class (ball-actor.ts), add the following method within the class definition (before the last "}").

```tsx
public moveTo(position: Vector3) {
  this.position.copy(position)
  this.physicsSystem.updateActorTransform(this)
  this.physicsSystem.setLinearVelocity(this, new Vector3())
}
```

This code will first set the actor’s position using the given position vector. The physics system is normally in control of the ball’s position so we have to tell it to use the actor’s new transform which contains the position. If we only change the position of the ball, the ball will still continue moving at the same velocity it did whenever it was reset. Instead, we want to cancel any existing movement which we can do by setting the linear velocity to 0 in all axis which can be done with a new vector as it defaults to all zeroes.

Now when you play the game and the ball falls of, it should reset to the spawn point. Depending on how your scene is designed, you may need to increase or decrease the value we set to -10 here.

### Reaching the goal

The challenge of the game is not to just roll around aimlessly but to reach a goal. To understand that the ball has reached the goal, we can use the trigger volume that we created in the scene initially.

Add the following code to the Game class at the end of the `onStart` method in the file `src/services/game.ts`.

```tsx
const triggerVolume = this.world.findActorByType(TriggerVolume)
triggerVolume.trigger.onBeginOverlapWithActor(ball).subscribe(() => {
  ball.moveTo(spawnPoint.position)
})
```

Here we subscribe to the begin overlap with actor event which is triggered as soon as the ball intersects with the trigger volume. At this point, we could do many things like informing the player that it has won the game, moving to a new level, registering the total time it took to complete, etc. However, that is out of scope of this tutorial. For now we can just reset the ball’s position to the spawn point for the purpose of this exercise.

### You’ve made it!

This is a very basic game but it contains the basic building blocks that you can use to build much more.

### Next steps

#### Give us your feedback

Did you get stuck somewhere, was something difficult to understand, or is there something else you would see explained? Then we would love to hear about it so we can improve.

#### Creating a more interesting map

Go back to the editor and change your scene to make the game more fun and challenging. You can add obstacles such as ramps or gaps between sections to jump over.

#### Add more features

You could make the game more interesting by adding new game play mechanisms. For example moving platforms or puzzles where the ball has to collide with certain objects,

#### Deploy your game

While the game may not be enough just yet to hit the front page of the App Store, you can launch it is a website and share it. See our documentation of distributing your game. [Distribution](https://docs.hology.app/release/distribution)

#### Continue learning

We only touched on the most important concepts in this tutorial. You may want to dive in deeper to learn all about actors and other game player features.

If you are new to game math like vectors and physics, you may want to read up on these.

#### Get started on your own game

This was just an introduction to game development with Hology Engine and you may feel unsure how to continue from here to build the game you want to build. Please feel free to contact us and tell us about what you want to create and we can help guide you with how to approach it.


# Character movement programming

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2Fgit-blob-4828f611b780f189892ce0b76bd70c7b04c5e985%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

**Level:** Beginner

In this tutorial we will explain how to setup a playable human-like character with keyboard controls and animations that are synced to the movement. This is similar to the [Starter project - Third person shooter](https://docs.hology.app/getting-started/starter-project-third-person-shooter) and we will go into details of how to set these up so that you can understand what is happening and how to extend it.

The complete code for this project can be cloned from GitHub.

<https://github.com/hologyengine/movement-tutorial>

{% hint style="info" %}
**Prerequisites**

Before continuing, you need to create a new project and familiarise yourself with the basics of the editor. Go through the article [The first steps](https://docs.hology.app/getting-started/the-first-steps) to learn how to set up a project. Then learn how to navigate in the editor using the articles in [Editor basics](https://docs.hology.app/getting-started/editor-basics).

While some coding skills are useful, all the code needed will be provided in this tutorial.
{% endhint %}

## Set up the scene

After creating the project, you have an empty scene that you can use for this tutorial. We will just create a couple of objects in this scene to illustrate how to make a character. In order for our character to have something to walk on, we will add a landscape shape. We will also add a spawn point actor so that we can spawn the playable character in the scene from game code.

In the Asset browser, select Shapes and scroll down to find the Landscape item.

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2Fgit-blob-d78a4f802951e0def54e56eab0abbba554627ddd%2FScreenshot%202024-05-26%20160253.png?alt=media" alt=""><figcaption></figcaption></figure>

Right click the Landscape item click "Add to scene". You will be prompted with some options for creating the landscape. For the purpose of this tutorial, you can leave the defaults as they are and click "Create".

Next, we need to create a spawn point. In the Asset browser, select Actors and then right click Spawn Point and add it to the scene. Click anywhere on the landscape you created earlier to place the spawn point.

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2Fgit-blob-9ffc64afdb3651e011be9b037817b72feed05f33%2Fimage%20(1)%20(1)%20(1)%20(1)%20(1)%20(1)%20(1)%20(1).png?alt=media" alt=""><figcaption></figcaption></figure>

## Import the character asset

We need a 3D models for our character that has animations that we can play. For this tutorial, we will use a character from an asset pack made by Kenney.

{% embed url="<https://kenney.nl/assets/mini-dungeon>" %}

Once you have downloaded the asset pack, unzip the file, find one of the character models such as **Models/GLB format/character-human.glb** and drag it into the editor to import it. We will later refer to this asset from game code.

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2Fgit-blob-02f4c4b30c9ff24d3a3d3f0e33862b23e8cb304b%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

## Programming a character actor

We will now create an actor class to represent the playable character. Create a file in src/actors/character.ts. Add the code below to the file.

```typescript

import { Actor, AnimationState, AnimationStateMachine, AssetLoader, BaseActor, attach, inject } from "@hology/core/gameplay";
import { CharacterAnimationComponent, CharacterMovementComponent, CharacterMovementMode, ThirdPersonCameraComponent } from "@hology/core/gameplay/actors";

@Actor()
class Character extends BaseActor {
  private animation = attach(CharacterAnimationComponent)
  public readonly movement = attach(CharacterMovementComponent, {
    maxSpeed: 1.5,
    maxSpeedSprint: 4,
    maxSpeedBackwards: 1,
    snapToGround: 0.1,
    autoStepMinWidth: 0,
    autoStepMaxHeight: 0.1,
    fallingReorientation: true,
    fallingMovementControl: 0.2,
    colliderHeight: .4,
    colliderRadius: 0.2,
    jumpVelocity: 3.5
  })
  public readonly thirdPersonCamera = attach(ThirdPersonCameraComponent, {
    height: .7,
    offsetX: -0.3,
    offsetZ: 0.2,
    minDistance: 3,
    maxDistance: 3,
    distance: 3,
    autoActivate: false
  })

  private assetLoader = inject(AssetLoader)
  protected modelName = 'character-human'

  async onInit(): Promise<void> {
    const { scene, animations } = await this.assetLoader.getModelByAssetName(this.modelName)

    this.object.add(scene)

    const clips = Object.fromEntries(animations.map(clip => [clip.name, clip]))
  
    const idle = new AnimationState(clips.idle)
    const walk = new AnimationState(clips.walk)
    const sit = new AnimationState(clips.sit)
    const jump = new AnimationState(clips.jump)
    const sprint = new AnimationState(clips.sprint)

    idle.transitionsBetween(walk, () => this.movement.horizontalSpeed > 0)
    walk.transitionsBetween(sprint, () => this.movement.isSprinting)
    idle.transitionsTo(sit, elapsedTime => elapsedTime > 1)
    sit.transitionsTo(walk, () => this.movement.horizontalSpeed > 0)
  
    for (const state of [idle, walk, sit, sprint]) {
      state.transitionsBetween(jump, () => this.movement.mode === CharacterMovementMode.falling)
    }

    const sm = new AnimationStateMachine(idle)

    this.animation.setup(scene)
    this.animation.playStateMachine(sm)
  }

}

export default Character

```

First we attach a few components to quickly add a lot of functionality to our actor.

* **CharacterAnimationComponent** allows us to play animations using a state machine. Read more about [Character Animation](https://docs.hology.app/gameplay/animation/character-animation)
* **CharacterMovementComponent** can take player input and move the character with common modes such as standing idle, walking, running and jumping. Read more about [Character movement](https://docs.hology.app/gameplay/character-movement)
* **ThirdPersonCameraComponent** moves the camera to behind the character. It provides options to offset the camera in various ways.

We load an asset using the injected AssetLoader using the name of the asset as can be found in the editor. This gives us a model's scene which is the character mesh and an array of animations.

In the rest of the code we set up the animation state machine. Read the guide on [Animation State Machine](https://docs.hology.app/gameplay/animation/animation-state-machine) to get a better understanding of how these work.

## Set up player input

To be able to control the character's movement, we will create a player controller service that takes the player's input and forwards it to the character's movement component.

Create a file at src/services/player-controller.ts with the following code.

```typescript
import { inject, Service } from "@hology/core/gameplay"
import {
  InputService,
  Keybind,
  Mousebind,
  Wheelbind,
} from "@hology/core/gameplay/input"
import Character from "../actors/character"

enum InputAction {
  moveForward,
  moveBackward,
  moveLeft,
  moveRight,
  jump,
  sprint,
  rotate,
  rotateCamera,
  zoomCamera
}

@Service()
class PlayerController {
  private inputService = inject(InputService)
  private character?: Character

  constructor() {
    this.inputService.setKeybind(InputAction.jump, new Keybind(" "))
    this.inputService.setKeybind(InputAction.sprint, new Keybind("Shift"))
    this.inputService.setKeybind(InputAction.moveForward, new Keybind("w"))
    this.inputService.setKeybind(InputAction.moveBackward, new Keybind("s"))
    this.inputService.setKeybind(InputAction.moveLeft, new Keybind("a"))
    this.inputService.setKeybind(InputAction.moveRight, new Keybind("d"))
    this.inputService.setMousebind(
      InputAction.rotate,
      new Mousebind(0.01, true, "x")
    )
    this.inputService.setMousebind(
      InputAction.rotateCamera,
      new Mousebind(0.003, false, "y")
    )
    this.inputService.setWheelbind(
      InputAction.zoomCamera,
      new Wheelbind(0.0003, false)
    )
  }

  public setup(character: Character) {
    this.inputService.stop()
    this.character = character
    this.bindCharacterInput()
    this.inputService.start()
  }

  private bindCharacterInput() {
    if (this.character == null) return

    const playerMove = this.character.movement.directionInput
    const playerJump = this.character.movement.jumpInput
    const playerSprint = this.character.movement.sprintInput

    this.inputService.bindToggle(InputAction.jump, playerJump.toggle)
    this.inputService.bindToggle(InputAction.sprint, playerSprint.toggle)
    this.inputService.bindToggle(InputAction.moveForward, playerMove.togglePositiveY)
    this.inputService.bindToggle(InputAction.moveBackward, playerMove.toggleNegativeY)
    this.inputService.bindToggle(InputAction.moveLeft, playerMove.toggleNegativeX)
    this.inputService.bindToggle(InputAction.moveRight, playerMove.togglePositiveX)
    this.inputService.bindDelta(
      InputAction.rotate,
      this.character.movement.rotationInput.rotateY
    )
    this.inputService.bindDelta(
      InputAction.rotateCamera,
      this.character.thirdPersonCamera.rotationInput.rotateX
    )
    this.inputService.bindDelta(
      InputAction.zoomCamera,
      this.character.thirdPersonCamera.zoomInput.increment
    )

  }
}

export default PlayerController

```

This code uses the InputService. To get a better understanding of how this works, read the [Player input](https://docs.hology.app/gameplay/player-input) guide.

## Spawning and setup

Now we just need to spawn the character and setup the player controller which we can do from the game class found in src/services/game.ts. Replace the contents of this file with the following.

```typescript

import { GameInstance, Service, World, inject } from '@hology/core/gameplay';
import { SpawnPoint } from '@hology/core/gameplay/actors';
import Character from '../actors/character';
import PlayerController from './player-controller';

@Service()
class Game extends GameInstance {
  private world = inject(World)
  private playerController = inject(PlayerController)

  async onStart() {
    const spawnPoint = this.world.findActorByType(SpawnPoint)
    const character = await spawnPoint.spawnActor(Character)
    character.thirdPersonCamera.activate()
    this.playerController.setup(character)
  }
}

export default Game

```

In this code we do a few things in the onStart function which gets called after the game has loaded and is ready to start.

1. We find a spawn point actor in the world.
2. Spawn the character using the spawn point and the Character actor class created earlier to get a new character that is placed in the scene with the position and rotation of the spawn point.
3. Call the setup function on the player controller with the character to bind the input events to this character's movement component.

This is everything necessary to have a playable character with animations.

## Testing the game

Run the following command in the terminal to run the game.

```
npm run dev
```

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2Fgit-blob-4c83d561bc301eedea201561839a3a49e918325d%2Fimage.png?alt=media" alt="" width="326"><figcaption></figcaption></figure>

This should give you a link such as <http://localhost:5173> that you can open in your browser to see the game.

You should now see the game running like in the picture at the start of this tutorial. Try pressing W,A,S,D on your keybaord. Click somewhere in the scene with your mouse first to be able to rotate the character and camera by moving your mouse.

## Wrapping up

You now have a starting point of what could be a super fun game.

* Read more about the features covered in this tutorial by following the links.
* Design a more interesting world by importing more assets and place them in your scene
* Create a more interesting game. For example, add some game play mechanisms such as [Trigger volumes](https://docs.hology.app/gameplay/trigger-volumes) that could trigger various things as you walk into them them or place other actors that does something when you are nearby and press a button.


# Character AI behavior

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2Fgit-blob-e0228e9bf5449313da664f0f53273b0117857694%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

In this tutorial, we will introduce AI as a way to control non-player characters in games using standard techniques such as navigation meshes and behavior trees. This tutorial is built on top of the tutorial [Character movement programming](https://docs.hology.app/tutorials/character-movement-programming). We will have one AI controlled character that can detect when the player gets close and start chasing the player.

The complete code for this tutorial can be found on GitHub using the link below.

{% embed url="<https://github.com/hologyengine/ai-tutorial>" %}

You can also play the finished demo with this link.

<https://hologyengine.github.io/ai-tutorial/>

## Setting up our project

You can download the code from the project above and go through the tutorial to understand how it is set up and how everything is working.

You can also build on top of what you created in the [Character movement programming](https://docs.hology.app/tutorials/character-movement-programming) tutorial.

## Concepts

### Behavior trees

In this tutorial, we will use something called a **behavior tree.** This is a hierarchical structure used to model the decision-making process of AI entities. It consists of nodes representing tasks or behaviors, organized in a tree-like structure.

* **Root Node**: The starting point of the tree.
* **Composite Nodes**: Manage child nodes and determine their execution order (e.g., *Sequence* or *Selector*).
* **Decorator Nodes**: Modify the behavior of child nodes (e.g., add conditions or loops).
* **Leaf Nodes**: Represent individual actions or checks, such as moving to a location or detecting an enemy.

Behavior trees are flexible and modular, making them popular for creating complex, dynamic AI behaviors in games.

### Navigation mesh

For our AI controlled character to be able to know what path to walk to reach a certain point, we will use a navigation mesh.

A navigation mesh (nav mesh) is a simplified 3D representation of a game environment used for pathfinding and AI movement. It consists of interconnected polygons that define areas where characters can walk, avoiding obstacles and inaccessible terrain.

You can read more about navigation meshes and how to use them in [Navigation](https://docs.hology.app/gameplay/navigation).

## Creating the AI character actor

To start, we will create a new Actor class which extends the Character actor class. Create a new file called **ai-character.ts** in the folder src/actors/. By extending the Character actor, we inherit all existing functionality such as setting up the character model and animations.

The first thing we do in the code below is to override the property modelName and change it to another model asset that we have imported to be able to more easily tell the characters apart.

Next, we inject a couple of services that will be used for navigating and querying the world for the player character. We declare a property that will hold our behavior tree that we will implement in the next steps. The behavior tree is created in the onBeginPlay method which is only called when the game is playing and not in the editor as we don't want the character running around while we try to edit our scene. To ensure smooth behavior, we update the behavior tree every frame with the time since last update using the tick function on the root behavior tree node.

```typescript
import {
  Actor,
  CharacterMoveToNode,
  inject,
  LeafNode,
  Navigation,
  Node,
  NodeState,
  RepeatNode,
  RepeatUntilNode,
  SelectorNode,
  SequenceNode,
  WaitNode,
  World,
} from "@hology/core/gameplay"
import { Vector3 } from "three"
import Character from "./character"

@Actor()
class AICharacter extends Character {
  protected override modelName = "character-orc"
  private navigation = inject(Navigation)
  private world = inject(World)
  private behaviorTree?: Node

  async onInit(): Promise<void> {
    await super.onInit()
  }

  onBeginPlay(): void {
    this.behaviorTree = this.createBehaviorTree()
  }

  onUpdate(deltaTime: number): void {
    this.behaviorTree?.tick(deltaTime)
  }

  private createBehaviorTree() {
    // This function is not yet finished. We will add to this in steps below 
    const selector = new SelectorNode()
    return new RepeatNode(selector)
  }
}

export default AICharacter

```

You also need to export this class in the file **src/actors/index.ts** so that it will be available to add in the editor.

```typescript
import AICharacter from './ai-character';

export default {
  AICharacter
}

```

## Implementing the behavior

Now, we will build on the code from before to add our behavior which consists of patrolling and if a player is near, start to chase it until it runs too far away, at which point it should return to patrolling.

The design choices in this tutorial is just made for illustrating how it could be implemented. For your own game, you can change parameters and logic to better fit the game play you want to create.

### Patrolling

The first thing we need for patrolling is finding the location to which the character should move towards. We will accomplish this with a custom leaf node.

Add the following code at the bottom of the file ai-character.ts.

```typescript
class FindPatrolPositionNode extends LeafNode {
  public foundPosition: Vector3|null = null
  public distance = 5
  public maxDistanceFromStart = 10

  private startPostition: Vector3

  constructor(
    private navigation: Navigation,
    private currentPosition: Vector3,
    startPosition: Vector3
  ) {
    super()
    this.startPostition = startPosition.clone()
  }

  tick(): NodeState {
    if (
      this.currentPosition.distanceTo(this.startPostition) >
      this.maxDistanceFromStart
    ) {
      this.foundPosition = this.startPostition
      return NodeState.SUCCESS
    }

    const randomDirection = new Vector3(
      Math.random() * 2 - 1,
      0,
      Math.random() * 2 - 1
    )
    const randomPoint = this.currentPosition
      .clone()
      .addScaledVector(randomDirection, this.distance)
    this.foundPosition = this.navigation.findClosestPoint(randomPoint)
    if (this.foundPosition == null) {
      return NodeState.FAILURE
    }
    return NodeState.SUCCESS
  }
}
```

In the constructor of this code, we define 3 things.

* **`private navigation: Navigation`**
  * This is a service that will need to pass from the actor and is used by the node to query the navigation mesh we created before.
* **`private currentPosition: Vector3`**
  * This is a reference to the current position of the character that will be used for knowing if we are too far away from our initial spawn point and to select a new random around the character.
* **`startPosition: Vector3`**
  * We pass in the start position which is going to be the initial location at which the character was spawned. We clone this position to ensure that it is not being updated as we are just passing in a reference.

We define the property `foundPosition` which is an output of this node that will be used in another node of our behavior tree.

Inside the tick function, we have our logic for finding the position to which we should move.

First, we have the following code which simply checks if we are further from than start position than a specific distance defined as another property on the node. Because we later will just pick a point at random around the character to walk from, this help us ensure that we don't wander too far away from the initial spawn point.

```typescript
    if (
      this.currentPosition.distanceTo(this.startPostition) >
      this.maxDistanceFromStart
    ) {
      this.foundPosition = this.startPostition
      return NodeState.SUCCESS
    }
```

Then, we have the code for finding a direction at random around the character and adding it to the current position with a configurable distance to get a new random point.

```typescript
    const randomDirection = new Vector3(
      Math.random() * 2 - 1,
      0,
      Math.random() * 2 - 1
    )
    const randomPoint = this.currentPosition
      .clone()
      .addScaledVector(randomDirection, this.distance)
```

Using the navigation service, we find the closest point on the navigation mesh to this random point. It is possible that no such point can be found such as when the navigation mesh is is still being generated. In this case, we return the node state FAILURE to prevent running the next step in our sequence of actions.

```typescript
    this.foundPosition = this.navigation.findClosestPoint(randomPoint)
    if (this.foundPosition == null) {
      return NodeState.FAILURE
    }
    return NodeState.SUCCESS
```

With our new custom node defined for finding the patrol position, we can update the `createBehaviorTree` function with the code below.

```typescript
private createBehaviorTree() {
    const findPatrolPosition = new FindPatrolPositionNode(
      this.navigation,
      this.position,
      this.position
    )
    findPatrolPosition.distance = 3

    const moveToPatrolTarget = new CharacterMoveToNode(
      this.navigation,
      this.movement
    )
    moveToPatrolTarget.target = () => findPatrolPosition.foundPosition

    const patrol = new SequenceNode()
    patrol.addChild(findPatrolPosition)
    patrol.addChild(moveToPatrolTarget)
    patrol.addChild(new WaitNode(300, 3000))

    const selector = new SelectorNode()
    selector.addChild(patrol)

    return new RepeatNode(selector)
  }
```

An instance of the class is created and the distance is configured to 3 meters. Then, we use a built in node that can be used with the built in character movement controller to move the character toward a specific position by setting its target property to a function that returns a position vector.

After creating these nodes, we create a sequence node which is a built in composite node that lets us define multiple nodes that should run after each other as long as the previous node in the sequence was successful. After the sequence we add a `WaitNode` to not do anything for a random duration (expressed in milliseconds) between 0.3 seconds and 3 seconds.

The next node we create is a `SelectorNode` with our patrol node as it only child. The selector node will run any of its child node for as long as they are running or successful. If a child node fails, it will try the next one. For now, we only have one node which is our patrol node but later on, we will have another node to chase the player.

The last node is the `RepeatNode` which will run the provided node in a loop forever. This will be the root node of the behavior tree. We normally want the root node to be repeating so that it can retry other nodes in case they fail.

### Chasing the player

To chase the player, we need to find the position of the player which can be done with a new custom node. Add the following code at the bottom of to the file ai-character.ts.

```typescript
class FindPlayerNode extends LeafNode {
  foundPlayer?: Character|null
  constructor(private world: World, private self: Character) {
    super()
  }

  tick(): NodeState {
    this.foundPlayer = this.world
      .findActorsByType(Character)
      .filter((c) => !(c instanceof AICharacter))
      .filter((c) => c.position.distanceTo(this.self.position) < 5)
      .at(0)
    if (this.foundPlayer != null) {
      return NodeState.SUCCESS
    }
    return NodeState.FAILURE
  }
}
```

The property foundPlayer will be our output that can be used by other nodes. In the constructor, we have a reference to the world and to the AI controlled character itself.

In the tick function, we first try to find the player character by filtering actors of the specific type Character. To ensure that we don't find the AI controlled character itself or another AI controlled character. We then filter character to only find one if it is within 5 meters from the AI controlled character. If we find the player, we return SUCCESS, otherwise FAILURE. By returning FAILURE, we ensure that the sequence will implement next does not continue and also tell the selector node in the behaviour tree to try another child node.

Next, we will add the following code to the function `createBehaviorTree` in the file ai-character.ts just before the line where we create the `SequenceNode`.

```typescript
const findPlayer = new FindPlayerNode(this.world, this)
const moveToPlayer = new CharacterMoveToNode(this.navigation, this.movement)
moveToPlayer.target = () => findPlayer.foundPlayer?.position

const chasePlayer = new SequenceNode()
chasePlayer.addChild(findPlayer)
chasePlayer.addChild(
  new RepeatUntilNode(
    moveToPlayer,
    // Stop chasing the player if the player is too far away
    () =>
      findPlayer.foundPlayer == null ||
      findPlayer.foundPlayer.position.distanceTo(this.position) > 5
  )
)
chasePlayer.addChild(new WaitNode(500))
```

First, we create an instance of the FindPlayerNode class we created previously to which we pass in the injected World instance and a reference to the actor itself. We then create another instance of the built in `CharacterMoveToNode` and give it a target of the found player's position.

In our sequence node, we first add the findPlayer node as our character needs to know where to go to if there is a player nearby that was found. If no player is found, the sequence itself will fail.

The next node we add is the moveToPlayer node. However, for some added functionality, we use a built in decorator node (`RepeatUntilNode`) to stop moving toward the player in case the player is farther away than 5 meters. This decorator node takes a function as a second argument in which we have our logic for when the character to stop.

Lastly, we add a wait node to the sequence so that the character briefly stops when it reaches the character. This adds a bit of realism such as when the player is starts moving after the character reaches the player, the AI controlled character doesn't immediately start moving also but instead takes a moment to react.

Now that we have our chasePlayer node, we need to add it to our selector. Do this by adding a line to where we created the SelectorNode previously. The order in which we add the child nodes is important. The nodes will be selected in the order in which they were added. If we were to switch the positions of these nodes, the selector node will prioritize the patrol node which will go on forever even if a player is nearby. By adding the chasePlayer node first, the behaviour tree will always attempt to run the node on each tick, checking if there is a player nearby. If no player is nearby, the chasePlayer node fails and it then resumes patrolling.

```typescript
const selector = new SelectorNode()
selector.addChild(chasePlayer) // Add this line
selector.addChild(patrol)
```

## Set up the scene

Now that we have our new AI controlled character, we are ready to setup the scene. The scene created in the previous tutorial contained a landscape and a spawn point. In addition to this, we need to add a navigation mesh and and our new AI Character actor.

### Navigation mesh

The first thing we need is a navigation mesh which can be added by selectin Actors in the Asset Browser and dragging NavMesh into the scene.

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2Fgit-blob-ad3251ae2cac5fdb8833a60230fdc93e53be7a81%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

The NavMesh is a bounding volume that is used to determine where the walkable area should be. When you add this to the scene, it is just a small cube. Scale and move the NavMesh box in such a way that it covers the landscape area where the player's spawn point is. Deselect the NavMesh (or press Q to use the select tool) and the generation of the navmesh will start.

After a few seconds, you should see a yellow grid in top of your landscape like below which displays the walkable area. This is useful for ensuring that your AI controlled characters are able to move where you want them to be able to move and vice versa. You can disable this by selecting the NavMesh object in the outliner and set "Debug" to "No"

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2Fgit-blob-90ec12cae1bbc143848b95f7689464ac2d0f44fb%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

### Adding the AI controller actor

Select Actors in the asset browser where you now should find the AICharacter actor. Click and drag this into the scene to place it. Ideally, place it somewhat nearby the spawn point so that when playtesting, you will be able to find it. In case you don't find the AICharacter, ensure that it is exported in the file src/actors/index.ts. Also, ensure there are no compilation errors in your actor code.

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2Fgit-blob-c0bfa70d8ea8aca06431056b2e694fbea586c9da%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

That's it! You have now implemented an AI controlled character that will start chasing you when you play the game.

To playtest the game, click the play button on the top right which should open the game in your browser.

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2Fgit-blob-c23d2fcac8a6d5d4bc5027e4b876f6f3b01c6964%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>


# Distribution

Deliver your game to players

Games created with Hology Engine can be run wherever you can run a web browser. This makes it very simple to deliver a game to your users as it can just run in a website. However, a website is not the only option. Many things can run a web browser. You can package your web application as a mobile app or desktop program which can be distributed on other platforms such as Steam, Apple's App Store, Google Play Store and many more.


# Discord Activities

Games built with Hology Engine work perfectly as discord activities as they are real web applications.

All you need to distribute your Hology Engine game as a Discord activity is to integration the Discord Embedded App SDK as explained in their own guide.

{% embed url="<https://discord.com/developers/docs/activities/overview#discord-activities>" %}

If you need help with with with distributing your application, feel free to contact us on the Discord server and we will happily assist.


# Facebook Instant Games

Games built with Hology Engine an be packed as a static web application and be distributed easily on platforms like Facebook Instant games.

## **Step by step**

### **Step 1: Prepare Your Game**

Before you can upload your game to Facebook Instant Games, you need to package it up in a .ZIP file.

First, build your project with the following command in your project's directory.

```
npm run build
```

This should have created a folder called **dist**. Compress the **dist** directory into a .ZIP file.

### Step 2: Set Up a Facebook Developer Account

1. **Join the Facebook Developer Program:**
   * Visit the Facebook for Developers website (<https://developers.facebook.com/>) and sign up for a developer account.
2. **Create a New App:**
   * In the Developer Dashboard, create a new app. This app will represent your Instant Game on Facebook.

### Step 3: Customize launching a game on Facebook

1. **Fill in details:**
   * Fill in the basic details for your app, including the display name, description, category, and images.
2. **Upload game:**
   * Go to Web hosting. Click "Upload version". Upload the .zip file you created in step 1.

### Step 3: Review and publish

Go through the rest of the steps as explained in the [official guide ](https://developers.facebook.com/docs/games/build/instant-games)to submit your game for review and publish it.


# Upload to Itch.io

itch.io is an online platform that serves as a hub for indie game developers, artists, and creators to publish, share, and sell their digital content. It offers a diverse marketplace for games, game assets, interactive fiction, and other digital creations, making it a popular destination for both creators and players seeking unique and innovative experiences. Users can discover, download, and support independent projects while creators can easily distribute and monetize their work through the platform.

## **Step by step**

### **Step 1: Prepare Your Game**

Before you can upload your game to Itch.io, you need to package it up in a .ZIP file.

First, build your project with the following commands in your project's directory.

```
npx tsc
npx vite build --base=./
```

This should have created a folder called **dist**.

If you are one window, open the project in the File Expolorer, right click the folder called "dist" and click "Compress to ZIP file".

If you are using Bash, you can run the following command to compress the **dist** directory into a .ZIP file.

```
zip -r dist.zip dist
```

### **Step 2: Create an Itch.io account**

If you don't already have an itch.io account, sign up for one. You'll need an account to publish and manage your games on the platform. It is completely free.

{% embed url="<https://itch.io/register>" %}

### Step 3: Upload your game

Once logged in, follow these steps to upload your game:

1. Click your username in the top right corner and select "Dashboard."
2. On your dashboard, click the "New Project" button.
3. Fill out the necessary information for your game project, including the title, URL, and any additional details.
4. Click "Create Project."
5. On the project page, you'll find an option to "Upload Files." Use this to upload the .ZIP file you created earlier. Check the checkbox for "This file will be played in the browser"
6. Once the upload is complete, you can set the visibility of your game. You can choose to keep it private, make it public, or restrict it to specific users.

You can read more about distributing HTML5 games on the official Itch.io documentation.

{% embed url="<https://itch.io/docs/creators/html5>" %}


# Host with GitHub Pages

You can deploy your game as a website using GitHub Pages. GitHub Pages allows you to host your HTML, CSS, and JavaScript files for free. Also, GitHub actions enable you to automatically update your game whenever you push changes to your GitHub repo.

Here's a step-by-step guide for how to set up deployment to GitHub Pages with automatic deployment using GitHub Actions. \\

## Steps

### Step 1: Setup GitHub Actions

Create a file with the following contents in your repository with the path `.github/workflows/deploy.yaml`\\

```yaml
name: GitHub Pages Deploy
on: 
  push:
    branches:
      - main
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Use Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20.x'
      - name: Install dependencies
        working-directory: ./
        run: |
          npm ci
      - name: Compile
        working-directory: ./
        run: |
          npx tsc && npx vite build --base=./
      - uses: actions/upload-artifact@main
        with:
          name: page
          path: dist
          if-no-files-found: error
  deploy:
    runs-on: ubuntu-latest
    # Add a dependency to the build job
    needs: build

    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
    permissions:
      pages: write      # to deploy to Pages
      id-token: write   # to verify the deployment originates from an appropriate source

    # Deploy to the github-pages environment
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - uses: actions/download-artifact@main
        with:
          name: page
          path: .
      - uses: actions/configure-pages@v5
      - uses: actions/upload-pages-artifact@v3
        with:
          path: .
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4
```

### Step 2: Enable GitHub Pages

Before pushing your changes, you need to enable GitHub pages. On your repository in GitHub, go to settings, pages, and select GitHub Actions as a source under Build and deployment.

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2Fgit-blob-1f42ae34f4302438a7a88223b2187754856e5e13%2FScreenshot%202023-09-27%20at%2019.10.05.png?alt=media" alt=""><figcaption></figcaption></figure>

### Step 3: Push your code

Next time you now push any commit in the branch called `main`, the GitHub Action will run, build your project and deploy to GitHub Pages.

### Step 4: Setup a domain

While not necessary, you can setup a custom domain name for your game. You can read more about this at this link.

{% embed url="<https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site/about-custom-domains-and-github-pages>" %}


# Publishing to Steam

Steam is a digital distribution platform for PC gaming that offers game developers access to a vast global audience, revenue opportunities through various pricing models, integration with Steamworks for feature-rich gameplay experiences, community engagement tools, early access and beta testing options, promotional opportunities, protection against piracy, analytics and data insights, and a revenue-sharing model. It's a comprehensive ecosystem that can significantly enhance a game's reach and success.

Publishing a game made with Hology is like publishing any HTML5 game to Steam. You first need to package it into an executable application that can be installed on a PC. A popular choice for this is Electron.js. Please refer to the Electron.js docs for how to package your application.

{% embed url="<https://www.electronjs.org/docs/latest/>" %}

After you have your game packaged, you need to integrate Steamworks. You can read more about how that can be done in this guide.

{% embed url="<https://liana.one/integrate-electron-steam-api-steamworks>" %}


# iOS and Android

Publish to mobile platforms

Games built with Hology Engine are platform independent. This means that you can use the same code for both iOS and Android. If you wish, you can still integrate native functionalities that exist on both. Apps you build can be published both to App Store and Google Play Store.

Your application needs to be packaged as iOS and Android apps. An easy way to do this is to use Capacitor.js. From your project's directory, you can apply the steps explained in this linked guide.

{% embed url="<https://capacitorjs.com/docs/getting-started>" %}


# 3D Models

One of the most critical pieces to designing your game levels is 3D models. You can import 3D models from various file formats which will then be created as assets that can be placed in your game.

## Importing models

Models can be imported by dragging files of supported file formats into the editor. You can also select multiple files at once.

<div align="center" data-full-width="false"><figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2Fgit-blob-c4a7e674e2cda5bcd14505fafe4742be315006a0%2FScreenshot%202023-09-30%20at%2010.14.44.png?alt=media" alt="" width="375"><figcaption><p>Drag and drop files</p></figcaption></figure></div>

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2Fgit-blob-20e069508484f5957e830430f6a8ad6637bc0e6a%2FScreenshot%202023-09-30%20at%2010.16.31.png?alt=media" alt="" width="375"><figcaption><p>An imported 3D model</p></figcaption></figure>

### Supported formats

* **glb, gltf** - This is the preferred format for 3D models. If the files are referring to textures located in separate files, those texture files will automatically be embedded during the import process so you don't have to import those as well.
* **fbx** - Another popular format. As FBX is normally using a scale of 1 unit = 1cm, a rescale factor will be applied to these assets to scale them to 1 unit = 1m.
* **obj** - A text based file format often accompanied with MTL files containing materials. The MTL files will automatically be imported.

### Names

The name of the imported file will be used to create the name of the imported asset.

## Settings

From the asset browser, you can open the edit dialog for your assets.

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2Fgit-blob-3088ab58c3369fb26c035fa6b660266929ec69d3%2FScreenshot%202023-09-30%20at%2010.21.27.png?alt=media" alt="3D Model asset settings" width="375"><figcaption><p>3D model asset settings</p></figcaption></figure>

* **Name -** The name of the asset
* **Collision detection** - Toggle on or off collision detection. This is by default enabled. If you don't want characters and other physical objects to be blocked by this model, toggle this off.
* **Rescale** - Change the default scale of the model. Hology Engine uses meters. If you for example modelled your object in cm, you would want to set this value to 0.01 to convert it to meters. If the modle is imported from an FBX file, it will by default be set to 0.01.
* **Cast shadow** - Whether or not this object should create shadows. This is by default disabled. Calculating shadows can affect performance if it has to take a lot of object into account. Therefore, Try to only enable shadows for object that it has a significant visual impact.
* **Receive shadow** - Whether or not this object should display shadows that are cast onto it.


# Custom collision shapes

Being able to control the exact shape of the shapes used for detecting collision is important for a good experience. The auto-generated collision shapes may also not be sufficient for some more complex 3D models. For better performance, it can sometimes be better to use multiple simple shapes rather than one complex one. All of this can be accomplished by defining your own shapes as part of the 3D model before exporting it in your 3D modeling tool.

## Defining collision shapes

In your 3D modeling tool, you can create meshes and give them a name with a special prefix which Hology Engine can use to understand that this mesh is meant for defining the object's collision shape and will also not be visible. You can have multiple collision shapes and they will be combined into a single composite collision shape in Hology.

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2Fgit-blob-dee5820c1375516689ba845f43f693ef5a21b829%2FScreenshot%202023-10-31%20163045.png?alt=media" alt=""><figcaption></figcaption></figure>

### Shape types

The different shapes supported are listed below with their object name prefix in brackets.

* **Sphere (USP\_):** A spherical shape. For collision detection is is the least computationally expensive shape.
* **Box (UBX\_):** A shape with 6 sides and 90 degree corners.
* **Convex hull (UCX\_):** A shape with no indents similar to a box or a sphere but can accommodate geometries that are a bit more complex.
* **Trimesh (UTM\_):** A shape that is made up of all the triangles in the mesh. This is suitable if you have complex geometry and it is important that the collisions are very precise. This is less performant compared to other shapes so if possible, try using multiple simpler shapes instead of a trimesh.


# Material slots

While imported models can use the materials that was included in the exported model from your 3D modelling program, there can be benefits in defining materials in the editor and assigning them to parts of your 3D model assets in the Hology editor.

* **Reusability** - Reuse the same 3D model but with different materials.
* **Custom shaders** - Create special effects or appearances with shaders you make in Hology Engine.
  * **Special effects, transforms and animation** - While some 3D modelling programs support creating advanced shaders, the file format used to export the models may not support all these effects. Instead, you need to create these materials in Hology Engine with custom shaders.
* **Consistency** - Defining your palette of materials in the editor can make it easier to ensure consistency in materials which can greatly help achieving a higher quality looking result. if you for example want to change how a certain material looks, you don't have to export all meshes with that material from your modelling program and importing them again into Hology Engine.
* **Better control of the final appearence** - The way a material is rendered inside your 3D modelling tools will always differ to some degree from Hology Engine based on factors like lighting and tone mapping. It can therefore be better to work on the apperences of materials directly in the Hology Engine editor so that you can ensure they look the way you want them to in-game.

## Defining material slots

Material slots in Hology Engine are generated based on the materials included in the imported 3D model. A large model could be contain many objects that reuse a smaller set of materials. Slots are created based on the model's materials unique name and color. If you for example have a model with multiple pieces that should represent wood and some objects that are metal, you can name the material you assign to these objects in your 3D modelling tool with names like "wood" and "metal" which then will be visible in Hology Engine as material slots. In the Hology Engine editor, you can then assign your own custom material to all objects in the model with for example the wood material.


# Exporting scenes

You can export your shole scene or part of a scene as a 3d model (GLB). This can be useful when creating assets to ensure that it fits in with a scene. Level design usually start with gray boxing where you just use simple shapes which are later replaced with other assets. To make sure that the asset you design in another 3D modeling software will fit in the scene, exporting parts of your scene to then import it into your modeling program is a useful workflow.

To export, select a set of object in your scene that you want to be included and then click Ctrl+Shift+E or using the Export selection button in the menu.

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2Fgit-blob-453ba98c4542b7434c2c544c2316fe7b9f704d5c%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>


# Materials

Materials determines the color of objects. The base color is usually determined by a configured color or sampled from a texture file. In addition to the color, the material will give the impression of light reflecting of the surface and shadows when light is blocked by other objects.

## Creating materials

Materials are created as assets so that they can be reused. In the asset browser you can click Add new and then Material to create one.

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2Fgit-blob-745005f7dd6d7c22d72c5d171792e52e00de07bd%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

### Naming materials

When creating a new material asset, you will be prompted to provide a name. The name should ideally describe the material in such a way that you can later find an appropriate material for the object on which you want to use it. For example, if the material is supposed to represent wood and you know you will have different types of wood materials, you could call it something like "Wood Oak" so you later easily can search for it.

### Material types

After creating a material you can select the type of material. The default standard material may be sufficient for most use cases.

* **Standard** - A material with many options to display a color, texture with physically based rendering (PBR), capable of rendering lighting with high quality. This will internally create the material [MeshStandardMaterial](https://threejs.org/docs/#api/en/materials/MeshStandardMaterial) that comes with the rendering library Three.js. Follow the link to read more about its options.
* **Lambert** - Similar to the standard material but uses a simpler light calculation which may result in a worse appearance but uses less GPU resources. Some objects, especially small objects and objects with flat surfaces may look equally as well with the Lambert material, in that case it can be much more performant to use it compared to the standard material. This will create the material [MeshLambertMaterial ](https://threejs.org/docs/#api/en/materials/MeshLambertMaterial)in Three.js.
* **Custom shader** - With the type Custom shader, you can select a shader you have created yourself. This can be useful to create various special effects. Read more about creating shaders at [Introduction to shaders](https://docs.hology.app/shaders/introduction-to-shaders)

### Duplicate a material

If you want to create a variation of a material, it can be easiest to just duplicate an existing material and then add the changes. By right clicking the material you you get a menu in which you can click "Duplicate" to create a copy of the asset.

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2Fgit-blob-389e8f2a219fad42069c7dd2652c2d9d7ecf5ad3%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

## Using materials

Materials can be added to imported 3D models, shapes, actors, and the sky sphere.


# Reflective materials

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2Fgit-blob-57365992a15310a0c9ef607ca34ef5ec9a03b331%2FScreenshot%202025-08-26%20151154.png?alt=media" alt=""><figcaption></figcaption></figure>

Hology Engine supports reflections on materials through **Screen Space Reflections (SSR)**. This technique approximates reflective surfaces by tracing rays against the contents of the current screen, allowing for real-time reflections without the heavy performance cost of traditional ray tracing.

Materials’ **normal**, **roughness**, and **opacity** values are taken into account when calculating reflections, allowing for realistic variation across different surfaces.

## Enable reflections

Open the material asset from the asset browser and toggle reflective to Yes. It is by default set to No.

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2Fgit-blob-be8da7b04cf015e9714c7e61eabc9a709ba1b2d5%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>


# Transparency

Transparent materials allow you to see through a mesh. Transparency can be **partial** (e.g. glass) or **binary** (fully visible or fully invisible per pixel). Choosing the correct method is important for both visual quality and performance.

There are two main approaches:

### Transparent Blending

Enable transparency by setting the material’s **Transparent** toggle to *Yes*. The final pixel color is blended with what has already been rendered behind it, using a blend mode (e.g. alpha blending).

**Pros**

* Supports **partial transparency** (smooth transitions between opaque and transparent)
* Ideal for materials like glass, water, smoke, and UI elements

**Cons**

* **Requires correct rendering order** (back-to-front sorting). Incorrect order can cause visible artifacts
* **Performance cost**: Objects behind must still be rendered even if fully covered
* Can produce **visual errors** when transparent objects overlap or intersect

**Use when**

* You need smooth, semi-transparent effects
* Visual accuracy is more important than performance

### Alpha Testing (Cutout)

Alpha testing uses a threshold to decide whether a pixel is rendered or discarded.

Example:\
If the alpha threshold is **0.1**, pixels with alpha < 0.1 are discarded; others are fully opaque.

**Pros**

* No sorting issues (renders like opaque objects)
* **Better performance** than blending in many cases
* Works well with depth testing and shadows

**Cons**

* No partial transparency (hard cut between visible/invisible)
* Can produce **jagged or pixelated edges**

**Tips**

* Adjust the threshold to minimize harsh edges
* Use higher-resolution textures or dithering techniques to improve appearance

**Use when**

* You need sharp cutouts (foliage, fences, grates)
* Performance and stability are important

### Quick Comparison

| Feature              | Transparent Blending | Alpha Test    |
| -------------------- | -------------------- | ------------- |
| Partial transparency | ✅ Yes                | ❌ No          |
| Sorting required     | ⚠️ Yes               | ❌ No          |
| Performance          | ❌ Higher cost        | ✅ Lower cost  |
| Edge quality         | ✅ Smooth             | ⚠️ Hard edges |

### Rule of Thumb

* Use **Transparent Blending** for *glass, liquids, effects*
* Use **Alpha Test** for *foliage, cutout textures, thin geometry*


# Textures

Textures can be imported into the editor from various file formats. Drag and drop texture files in the formats PNG or JPEG onto the editor window and texture assets will be created.

The textures can be used as parameters on materials.


# Prefabs

A "prefab," short for "prefabricated object," refers to a reusable and preconfigured object that encapsulates a combination of inner objects, components, configurations. Prefabs are designed to simplify and streamline the process of creating and managing game content. Instead of recreating the same objects with the same attributes multiple times, you can create prefabs as templates for commonly used elements, such as characters, items, or environmental objects.

## Creating prefabs

You can either create a prefab from an already existing set of objects or create a new.

### From selection

If you already have one or more objects in the scene that you want to make into a reusable prefab, you can group them together (shift+G) and then in the outliner, right click the group and click "Convert to a prefab". The name of the group will be the name of the prefab asset. The group in your scene will be replaced by the prefab object.

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2Fgit-blob-714db52d386576ba1233b979bdbb46d77ea6045d%2FScreenshot%202023-10-04%20101907.png?alt=media" alt="Convert to a prefab"><figcaption><p>Convert to a prefab from outliner</p></figcaption></figure>

### From the asset browser

You can also create a new empty prefab from the asset browser by clicking "Add new". You will be prompted to enter a name for the prefab asset.

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2Fgit-blob-22975eba39e7a40c2718480a09aa002b97eabab5%2FScreenshot%202023-10-04%20102119.png?alt=media" alt=""><figcaption><p>Create a new empty prefab</p></figcaption></figure>

## Editing prefabs

A prefab can be edited by opening the prefab editor either by selecting a prefab instance in your outliner or from the asset browser. This will open the prefab editor in a new tab. In the prefab editor, you can make any changes you want to any of the objects inside the prefab as well as to add additional objects. After saving the prefab (ctrl+S), the changes to the prefab will automatically update in any scene where it is being used.

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2Fgit-blob-d50fde1a61f4d497769aa6303579d993aac55024%2FScreenshot%202023-10-04%20102323.png?alt=media" alt=""><figcaption><p>Open prefab editor</p></figcaption></figure>


# Actors

Actors are fundamental objects that can be placed in your game world and interact with other actors. An object that has a physical presence or in some way could be represented by an actor which you as a programmer has full control over. This could be the player's character or objects with which the player can interact.

You can write code for your own actors using a Typescript class. These actor classes will then be available as assets that you can instantiate and put in your scene in the editor. You can also spawn actors dynamically during gameplay.


# Creating actor classes

Actors are implemented as classes in you project's code.

### Creating a new actor class

The actor class is defined in a `.ts` file in your code. A convention is to place these in the folder `src/actors`. In the code below, we have a basic starting point for an actor.

```typescript

// src/actors/example-actor.ts
import { Actor, BaseActor } from "@hology/core/gameplay";

@Actor()
class ExampleActor extends BaseActor {

  onInit() {
    
  }
  
  onBeginPlay() {
  
  }
  
  onEndPlay() {
  
  }
  
  onUpdate(deltaTime: number) {
    
  }
  
}

export default ExampleActor 

```

This is all you need if you only intend to spawn the actor through you game.

#### Making actors available in the Hology Editor

In addition to defining your class, you need to export it. This is done in the `index.ts` file. If this is not done, the editor will not be able to find your actor class.

```typescript

// src/actors/index.ts
import ExampleActor from "./example-actor";

export default {
  ExampleActor,
  // add other actors here
}

```

### Creating an actor class from the editor

An easier way to create the starting code for an actor is to do it through the editor. It will generate code for you with a given actor class name. Click the Add new button in the asset browser and select Actor class.

<img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2Fgit-blob-0d1f3a4771d344d28dab0ebda962428e3e2fb32b%2FScreenshot%202023-09-17%20092605.png?alt=media" alt="Create actor classes from editor" data-size="original">

### Hot reloading

The editor will monitor your code to find any new actor classes that can be instantiated as actor instance in your scenes. Also, if the actor code changes, actors in in your scene will be refreshed to reflect any visual changes.


# Actor parameters

Actor parameters are properties on actors that you can set in the editor for each instance of an actor. This allows you to control the functionality of an actor without having to change code.

Parameters can be created by adding the `@Parameter()` decorator on a property in your actor class. The type of the parameter will be inferred by your property's type annotation.

### Supported Types

The example below shows all currently supported types.

```typescript
@Actor()
class ActorWithParameters extends BaseActor {
    @Parameter() aNumber: number
    @Parameter() aBoolen: boolean
    @Parameter() aString: string
    @Parameter() vec2: THREE.Vector2
    @Parameter() vec3: THREE.Vector3
    @Parameter() color: THREE.Color
    @Parameter() rotation: THREE.Euler
    
    // An instance of a 3D model asset
    @Parameter() mesh: THREE.Object3D
    
    // An instance of a material
    @Parameter() material: THREE.Material
    
    // An audio buffer from an audio asset
    @Parameter() audio: AudioBuffer
    
    @Parameter() clip: THREE.AnimationClip
    
    // Refer to another actor in the scene. 
    // You can also use your own actor class to only be 
    // able to select actors of that type
    @Parameter() actor: BaseActor
    
    @Parameter() prefab: Prefab
    @Parameter() specificPrefab: PrefabOf<WeaponActor>
}
```

#### Parameter Definitions

Use `@ParameterDefinition()` when a parameter should be a structured object instead of a single value. This is useful when several values belong together, or when you want designers to choose between different kinds of configuration that share a common base type.

The string passed to `@ParameterDefinition()` is the stable id stored in scene and prefab data. Choose an id that will not change when you rename or move the TypeScript class.

For example, an ability can contain several values that should be edited together:

```typescript
@ParameterDefinition('combat.damage')
class DamageDefinition {
  @Parameter() amount: number = 10
  @Parameter() damageType: string = 'physical'
}

@Actor()
class DamageZoneActor extends BaseActor {
  @Parameter()
  damage: DamageDefinition = new DamageDefinition()
}
```

In the editor, `damage` appears as a nested parameter group with `amount` and `damageType` inside it. At runtime, the actor receives an instance of `DamageDefinition`, so you can also add methods to the class if that makes the gameplay code clearer.

**Polymorphic Definitions**

Parameter definitions can extend other parameter definitions. If an actor parameter is typed as a base definition, the editor lets the designer select any registered subclass.

```typescript
@ParameterDefinition('combat.attack')
class AttackDefinition {
  @Parameter() damage: number = 10

  apply(target: BaseActor) {
    // Shared attack behavior
  }
}

@ParameterDefinition('combat.magicAttack')
class MagicAttackDefinition extends AttackDefinition {
  @Parameter() manaCost: number = 5

  override apply(target: BaseActor) {
    // Magic-specific behavior
  }
}

@Actor()
class WeaponActor extends BaseActor {
  @Parameter()
  attack: AttackDefinition = new AttackDefinition()
}
```

The designer can keep the base `AttackDefinition` or switch the parameter to `MagicAttackDefinition`. When a subclass is selected, its extra parameters are shown in the editor and the runtime value is an instance of that subclass.

Class names are converted into readable labels in the editor. For example, `MagicAttackDefinition` is shown as `Magic Attack`. The `Definition` suffix is optional, but using it is a good convention for these data classes.

**Abstract Base Definitions**

Sometimes the base type exists only to define a shared shape or API, and should not be selectable by itself. Mark it as abstract with the second argument to `@ParameterDefinition()`.

```typescript
@ParameterDefinition('combat.ability', { abstract: true })
abstract class AbilityDefinition {
  @Parameter() cooldown: number = 1

  abstract activate(owner: BaseActor): void
}

@ParameterDefinition('combat.fireball')
class FireballDefinition extends AbilityDefinition {
  @Parameter() radius: number = 3

  activate(owner: BaseActor) {
    // Fireball behavior
  }
}

@Actor()
class AbilityActor extends BaseActor {
  @Parameter()
  ability: AbilityDefinition
}
```

The editor will show a type selector for `ability`, but the designer must choose a concrete subclass such as `FireballDefinition` before nested fields are shown. This is useful for things like abilities, attacks, loot rules, AI actions, or other gameplay definitions where the base class is not meaningful on its own.

**Arrays of Definitions**

Parameter definitions can also be used in arrays.

```typescript
@Actor()
class AbilityBarActor extends BaseActor {
  @Parameter({ type: () => AbilityDefinition, array: true })
  abilities: AbilityDefinition[] = []
}
```

If the array element type has subclasses, each array item can use a different concrete definition. This makes it possible to build lists such as ability bars, attack combos, spawn tables, or status effects while keeping each item strongly typed in gameplay code.

### Parameter Options

You can pass a configuration object to the `@Parameter()` decorator to customize how the parameter behaves and appears in the editor.

```typescript
interface ParameterOptions {
  label?: string      // Custom display name in the editor
  help?: string       // Tooltip text shown on hover
  
  // Number configuration
  range?: [min, max]  // Slider with minimum and maximum values
  stepSize?: number   // Increment size for the input
  precision?: number  // Number of decimal places
  
  // Logic
  optional?: boolean  // Adds a checkbox to enable/disable the parameter (override mode)
  requires?: Record<string, unknown> // Only show this parameter if another property matches a value
}
```

#### Examples

**Numeric Sliders**

Use `range` to create a slider constraint, which is helpful for values like percentage or intensity.

```typescript
@Parameter({
  label: 'Movement Speed',
  range: [0, 100],
  stepSize: 1
})
speed: number = 10;
```

**Optional Overrides**

Use `optional` to allow a value to be null or undefined by default, unless explicitly enabled by the level designer. This is useful for overriding default behaviors.

```typescript
@Parameter({
  optional: true,
  help: 'If enabled, this color will override the default color'
})
customTint: THREE.Color = new THREE.Color('blue')
```

**Conditional Visibility**

Use `requires` to declutter the editor UI by hiding parameters that aren't relevant based on other settings.

```typescript
@Parameter()
canJump: boolean = false;

@Parameter({
  requires: { canJump: true } // Only visible when canJump is checked
})
jumpHeight: number = 2.0;
```

#### Prefab Types

Hology supports parameters that refer to prefab assets. While the generic `Prefab` type allows any prefab to be selected, the `PrefabOf<T>` type provides additional safety by restricting choices to prefabs that have a specific **Main Actor** [Prefab main actor](https://docs.hology.app/gameplay/actors/prefab-main-actor)

For more details, see the [PrefabOf actor](https://docs.hology.app/gameplay/actors/prefabof-actor) documentation.


# Actor components

Actor components play a crucial role in Hology by enabling you to modularise and extend the functionality of your game objects (actors) in a clean and organised manner. They allow you to break down complex actors into smaller, reusable, and manageable pieces, making your game development process more efficient and maintainable.

1. **Modularity and Reusability**:
   * Actor components are self-contained units of functionality that can be attached to one or more actors. This modularity allows you to create reusable pieces of functionality that can be used across multiple actors or projects.
2. **Organization**:
   * Actor components help you organise your actors' functionality by separating different aspects of an actor's behaviour into distinct components. For example, you can have separate components for character movement, health, inventory, and more.
3. **Code Encapsulation**:
   * Each actor component can encapsulate its own logic and data, making it easier to manage and maintain your code. This separation of concerns helps prevent code duplication and keeps your codebase cleaner.
4. **Customisation and Extensibility**:
   * You can easily add or remove actor components from an actor to customise its behaviour without having to modify the core actor class. This makes it simpler to iterate on your game's design and mechanics.
5. **Editor Friendliness**:
   * Hology's editor provides a user-friendly interface for configuring actor components, making it accessible to designers and artists without requiring programming knowledge.

## Example component

In the example below, we have a component used to hold the state of an object's health. The max health is a parameter so that can be adjusted in the editor but it is also assigned a default value.

The current health is set to the max health on initialisation. This is because the max health value is set after the class is instantiated so it is not available at the time the `currentHealth` property is defined

```typescript
@Component()
class HealthComponent extends ActorComponent {
    @Parameter() maxHealth: number = 100
    currentHealth: number
    
    onInit() {
        this.currentHealth = this.maxHealth
    }
    
    update(change: number) {
        this.currentHealth = Math.max(0, this.currentHealth + change)
    }
}
```

## Attaching components

Actors can add components to themselves as properties by using the `attach(Type<ActorComponent>)` function to which you pass in the class you wish to attach.

```typescript
@Actor()
class CharacterActor extends BaseActor {
    health = attach(HealthComponent)
    
    takeHit(damage: number) {
        this.health.update(-damage)
    }
}
```

## Component options

With the `@Component()` decorator, you can pass additional options.

```typescript
@Component({ inEditor: false, editorOnly: false })
class HealthComponent extends ActorComponent {

}
```

* **inEditor** (type: boolean, default: false) - Whether or not the component should be used in the editor. In the editor, is only important to give visual feedback as to what the actor looks like. Any other functionality should be disabled. Note that some functionality that works in your game, may not work in the editor.
* **editorOnly** (type: boolean, default: false) - Whether the component should only be used in the editor. If true, then it will not be in your game. This is useful for displaying 3D meshes that you want to provide some visual representation in your editor.


# Actor lifecycle

An actor will go through a series of phases during its lifetime. It is important to know which phases exist and what you can and can not do during these phases.

The phases applies both to the actor and components within actors. Each phase applies to all components before the next phase starts.

1. **Construction**
   * The class is instantiated and the constructor is called.
   * Services are injected and components are attached using the functions `inject` and `attach`.
   * Don’t use properties on the class that are parameters as their values will be undefined.
2. **Deserialisation**
   * Properties set using the attach function or Attach decorator are set.
   * Parameters configured in the editor are set on the actor and components.
3. **Initialisation**
   * The `onInit` method is called on the actor and then on components.
   * OnInit methods can be asynchronous and will run at the same time. Therefore, avoid being dependent on any logic to have happened in another component’s onInit method as the order in which they complete may not be reliable.
   * Do use parameter properties on the class as they are now defined.
   * Do set up subscriptions and start performing game logic.
   * Do dynamically attach components if they can’t be attached during the construction phase. Use `this.attach`
   * Don’t use the functions `inject` or `attach`.
4. **Begin play**
   * This happens when an actor is spawned in the world.
   * The `onBeginPlay` method is called on the actor and then on components. This does not happen inside the editor.
   * Use this phase to start game play functionality.
5. **Update**
   * The `onUpdate` method is called before every frame is rendered and is commonly used for logic.
   * Do perform functionality that may need to transform rendered objects or other visual effect.
   * Avoid creating creating new objects that are only used within this function. Because this function is run with such high frequency, memory allocation and its garbage collection can end up having a significant performance impact.
   * Avoid using the update phase for functionality that can run with a different frequency than the render loop frequency. Synchronising functionality between different actors can be difficult as the order in which the `onUpdate` method is called is not guaranteed to be consistent between actors. Instead, rely on events emitted from other actors, components or systems.
6. **Late update**
   1. The `onLateUpdate` method is also called once per frame but is called after all `onUpdate` methods have been called.
   2. It can be useful when you want to ensure that all `onUpdate` functions have finished before executing certain code.
   3. Common use cases for `onLateUpdate` include camera manipulation or following, especially when the camera is following a moving object that has been updated in the `onUpdate` method.
7. **End play**
   * This happens when the game shuts down or the actor is removed.
   * The `onEndPlay` method is called on the actor and then on components. This does not happen inside the editor.
8. **Removal**
   1. The actor is removed from the world and is disposed.
   2. Unsubscribe on all subscriptions created. If you are using RxJs to create subscriptions, use `.pipe(takeUntil(this.disposed))` to automatically unsubscribe when the actor is removed.


# Spawning actors

To create a new instance of an actor class within the game world at runtime is referred to as a spawning an actor.

An actor can be spawned from anywhere in your code by injecting the World service. The spawnActor function takes 3 parameters.

* **type** (type: `Type<BaseActor>)` - The actor class from which a new instance should be created.
* **position** (type: `THREE.Vector3`) - Where in the scene the actor should initially be positioned. Defaults to {x: 0, y: 0, z: 0}.
* **rotation** (type: `THREE.Euler`) - How the actor should initially be rotated around each axis. Defaults to {x: 0, y: 0, z: 0}.

The code below illustrates how an actor is created and returned.

```typescript
import { Service, GameInstance, inject, World } from "@hology/core/gameplay"
import ExampleActor from "./actors/example-actor"

@Service()
class Game extends GameInstance {
  private world = inject(World)
  
  async onStart() {
    const actor = await this.world.spawnActor(ExampleActor)
  }
}
```


# Moving actors

After an actor is added to your scene, either by placing it in the editor or by spawning it at runtime, you may want to move it to a different location or to rotate it. There are two approaches to this:

* Directly set the new position and rotation on the actor
* Simulate physics by adding the actor to the physics system with a dynamic or kinematic physics body.

## Setting the transform on an actor

If your object should not neceserilly adhere to laws of physics, you can simply set the position and rotation using the actor's position and rotation properties. This will update the rendered transform of the object but it will not update it in the physics world. For that to happen, you also have to apply the actor's transform through the physics system.

In the example below, we have an actor with a rendered and physical representation given by the collision shape. On each frame, we update the actors position according to a speed and direction.

```typescript
@Actor()
class BallActor extends BaseActor {
    private physics = inject(PhysicsSystem)

    public speed = 0.4
    public direction = new THREE.Vector3(0,0,1)

    private mesh = attach(MeshComponent, {
      mass: 1,
      bodyType: PhysicsBodyType.static,
      object: new PhysicalShapeMesh(
          new SphereGeometry(.2, 20, 10),
          new MeshStandardMaterial({ color: 0xeff542 }),
          new SphereCollisionShape(.2))
    })
    
    onUpdate(deltaTime: number) {
        this.position.addScaledVector(this.direction, this.speed * deltaTime)  
        
        // Also update the physics system so that the physics body is updated
        this.physics.updateActorTransform(this)       
    }
    
}
```


# Prefab main actor

In Hology Engine, a **Main Actor** allows you to define the primary identity of a prefab. By designating a specific actor within a prefab as the "Main Actor", the prefab itself effectively adopts that actor's type.

This concept creates an "is-a" relationship between the prefab and its main actor. For instance, a complex `SciFiSlidingDoor` prefab containing meshes, sounds, and particle effects can be designated to *be* a `DoorActor`.

### Why use a Main Actor?

Setting a main actor provides two major benefits for gameplay engineering and level design:

#### 1. Referencing in the Editor

When a prefab has a main actor, instances of that prefab can be assigned to component parameters that expect the main actor's type.

**Example:** Imagine you have a `PressurePlate` actor in your scene that has a property `target` of type `DoorActor`.

* **Without Main Actor**: You cannot reference the `SciFiSlidingDoor` prefab instance in the `target` parameter because the engine sees it merely as a generic prefab or group.
* **With Main Actor**: If the `SciFiSlidingDoor` prefab has its internal `DoorActor` actor set as the Main Actor, you can reference the `SciFiSlidingDoor` instance directly into the `PressurePlate`'s `target` parameter. The engine resolves this reference to the internal `DoorActor` actor automatically.

#### 2. Parameter Overrides

Parameters on the Main Actor become exposed on the prefab instance in the scene editor.

This allows level designers to tweak gameplay values (like `OpenSpeed` or `Locked`) directly on the prefab instance without needing to dig into the prefab hierarchy to find the specific logic actor.

### How to set a Main Actor

1. Open the prefab you want to edit.
2. In the **Outliner**, find the actor that represents the core logic or identity of the prefab.
3. Right-click the actor and select **Set as Main Actor**.

#### Unsetting

To remove the association, right-click the current Main Actor in the Outliner and select **Unset Main Actor**.


# PrefabOf actor

The `PrefabOf<T>` type is a specialized parameter type that allows game designers to select a prefab asset in the editor while ensuring it contains a specific type of actor.

### The Problem

When using the generic `Prefab` type for a parameter, a level designer can pick *any* prefab asset from the project.

```typescript
@Parameter()
spawnPrefab: Prefab
```

If your gameplay logic expects the prefab to contain a specific actor (e.g., a `WeaponActor` or a `HealthPackActor`), picking the wrong prefab will lead to runtime errors or broken behavior. This requires constant communication between programmers and designers to ensure the right assets are used.

### The Solution: `PrefabOf<T>`

By using `PrefabOf<T extends BaseActor>`, you can restrict the selection in the editor to only those prefabs that have a [Prefab main actor](https://docs.hology.app/gameplay/actors/prefab-main-actor) of type `T` (or a subclass of `T`).

#### Benefits

1. **Editor Safety**: The editor's asset picker will filter out any prefabs that don't match the required main actor type.
2. **Type Safety**: When you spawn an actor using a `PrefabOf<T>` parameter, the engine automatically returns an instance typed as `T`.
3. **Subclass Support**: It works with any prefab whose main actor is a subclass of `T`, allowing for polymorphic behavior.

***

### Use Case Example

Imagine a **Weapon Box** that spawns a weapon when opened. You want to ensure that only prefabs representing weapons can be assigned to the box.

#### 1. Define the Parameters

In your actor class, use `PrefabOf<WeaponActor>` for the parameter.

```typescript
import { Actor, BaseActor, Parameter, PrefabOf } from '@hology/core'
import { WeaponActor } from './weapon-actor'

@Actor()
class WeaponBox extends BaseActor {
  @Parameter()
  weaponPrefab: PrefabOf<WeaponActor>

  async open() {
    // Spawning from a PrefabOf<WeaponActor> returns a WeaponActor instance
    const weapon = await this.world.spawnActor(this.weaponPrefab, this.object.position)
    
    // You can now safely call weapon-specific methods
    weapon.equip()
  }
}
```

#### 2. Editor Interaction

When a level designer selects the `WeaponBox` in the editor:

* They will see the `weaponPrefab` parameter.
* The asset picker will **only show prefabs** that have an actor of type `WeaponActor` (or its subclasses like `SwordActor` or `GunActor`) set as their **Main Actor**.

***

### Comparison: `Prefab` vs `PrefabOf<T>`

| Feature               | `Prefab`              | `PrefabOf<T>`                                          |
| --------------------- | --------------------- | ------------------------------------------------------ |
| **Editor Selection**  | Any prefab asset      | Only prefabs with Main Actor of type `T`               |
| **Spawn Return Type** | `PrefabInstance`      | The actor instance itself as `T` (automatically typed) |
| **Intent**            | Generic instantiation | Specific gameplay requirements                         |
| **Spawn method**      | `world.spawnPrefab`   | `world.spawnActor`                                     |
| **Remove method**     | `world.removePrefab`  | `world.removeActor`                                    |

***

### Technical Note: Main Actor Required

For a prefab to be selectable by a `PrefabOf<T>` parameter, it **must** have a [Prefab main actor](https://docs.hology.app/gameplay/actors/prefab-main-actor) defined. If a prefab does not have a Main Actor, it will not appear in the filtered list, even if it contains an actor of type `T` somewhere in its hierarchy.


# Services

It is sometimes suitable to have a class that can be accessed from all your actors and components. This is can be done with Services which are classes that can be injected in your actors and components. There will only be one instance of the service. This is similar to the Singleton design pattern. It can serve many purposes:

1. **Global access:** Services provide a convenient way to access a specific object or functionality from anywhere in your game's codebase. This can be helpful for managing and sharing resources, game state, or services such as audio managers, input handlers, or configuration settings.
2. **Game state management:** Services can be used to manage the overall state of the game, including aspects like score, level progression, or the current game mode. This helps in maintaining a consistent game state across various parts of the code.
3. **Configuration settings:** Storing and accessing global configuration settings or variables is a common use case.
4. **Cross-actor communication**: Services can facilitate communication between different actors or systems by providing a shared interface. For example, event emitters can be placed on a service to inform every actor throughout your game when an event occurs.

## Creating services

To create a service, all you need to do is to add the `@Service()` decorator on your class.

<pre class="language-typescript"><code class="lang-typescript"><strong>// src/services/game-state.ts
</strong><strong>import { Service } from "@hology/core/gameplay";
</strong>
@Service()
class GameState {
  score: number
}

export default GameState
</code></pre>

## Injecting services

A service can be used from any actor or component by using the inject function and pass in the service's class.

```typescript
// src/actors/goal.ts
import { Actor, BaseActor, inject, } from "@hology/core/gameplay";
import Service from "../services/game-state.ts"

@Actor()
class Goal extends BaseActor {
  private gameState = inject(GameState)
}
```

## Built in services

Here are some services that may be useful to you that also provide example use cases for services.

* **World**: The world service can be used to spawn actors.
* **PhysicsSystem**: Manages all physics in your game. Can be used to setup physics for an actor, apply forces to actors, and subscribe to collision events.
* **ViewController**: An interface towards the engine's rendering. Can be used for setting the active camera or pausing/resuming rendering.


# Load assets

The `AssetLoader` service allows you to dynamically load assets such as models, textures, audio, and materials at runtime. You can retrieve assets either by their unique ID, their name (as defined in the editor), or by their file path.

### Basic Usage

Inject the `AssetLoader` into your actor or service to start loading assets.

```typescript
import { Actor, AssetLoader, BaseActor, inject } from "@hology/core/gameplay";

@Actor()
class TestActor extends BaseActor {
  private assets = inject(AssetLoader)

  async onInit() {    
    // Load a model by name
    const model = await this.assets.getModelByAssetName('MyCharacter')
    this.object.add(model.scene)
    
    // Play a sound
    const audioBuffer = await this.assets.getAudioByAssetName('JumpSound')
    // ... use audioBuffer
  }
}
```

### Loading Methods

#### Models

Models are returned as a `LoadedMesh` object, which contains the `scene` (THREE.Group) and `animations` (THREE.AnimationClip\[]).

* **`getModelByAssetName(name: string): Promise<LoadedMesh>`**
  * Finds an asset by its name in the project.
* **`getModelByAssetId(id: string): Promise<LoadedMesh>`**
  * Finds an asset by its unique ID.
* **`getModelAtPath(filePath: string): Promise<THREE.Object3D>`**
  * Loads a model directly from a file path relative to the project root. Supports `.glb`, `.gltf`, `.fbx`, and `.obj`.
* **`getGltfAtPath(filePath: string): Promise<GLTF>`**
  * Loads a GLTF/GLB file and returns the full GLTF object (including scenes, cameras, animations, etc.).

#### Textures

Textures are returned as `THREE.Texture` objects.

* **`getTextureByAssetName(name: string): Promise<THREE.Texture>`**
* **`getTextureByAssetId(id: string): Promise<THREE.Texture>`**

#### Audio

Audio is returned as an `AudioBuffer`, ready to be used with `THREE.Audio` or `THREE.PositionalAudio`.

* **`getAudioByAssetName(name: string): Promise<AudioBuffer>`**
* **`getAudioByAssetId(id: string): Promise<AudioBuffer>`**
* **`getAudioAtPath(filePath: string): Promise<AudioBuffer>`**

#### Materials

Materials are returned as `THREE.Material` objects.

* **`getMaterialByAssetId(id: string): Promise<THREE.Material>`**

#### Prefabs

Prefabs allow you to spawn pre-configured actors or objects.

* **`getPrefabByName(name: string): Promise<Prefab>`**
* **`getPrefabById(id: string): Promise<Prefab>`**

### Generic Asset Access

If you need access to the raw `Asset` data structure:

* **`getAsset(id: string): Promise<Asset>`**


# View Controller

One central service is the View Controller service which is an interface towards certain rendering functionality

## Pausing a game

You can pause a game using the View controller which will pause the rendering loop that runs every frame. It will also pause the processing of player input.

To pause, you simply have to set the paused property to true. To resume the game, you would similarly just set it to false. You can do this from a service, actor or in the UI.

```typescript
@Service()
class PlayerController {

  private view = inject(ViewController)

  pause() {
    this.view.paused = true
  }
  
  resume() {
    this.view.paused = false
  }

}

```


# Player input

Player input in Hology can be handled by a built-in system for managing keybinds and propagating events to functions to react to input events. This system separates the configuraiton of keybinds from the effects of the player's action to be more flexible.

## Configuring actions

### Action identifiers

Your players intent is identified with an action identifier. This is key to later configure keybinds and triggering effects in your game as those actions are triggered by the player for example pressing keys or moving a mouse.

Action identifiers can be defined using a custom enum but also any number of string works. In the example below, we can see various actions be defined.

```typescript
enum InputAction {
  moveForward,
  moveBackward,
  moveLeft,
  moveRight,
  jump,
  sprint,
  rotate
}
```

### Configuring keybinds

Keybinds can be set for your actions on the `InputService`. This enables you to dynamically configure what keys trigger what action.

#### Keyboard and mouse presses

Pressing a key on a keyboard or a mouse can trigger actions by using the `setKeybind` method.

```typescript
this.inputService.setKeybind(InputAction.moveForward, new Keybind("w"))
```

Keybind arguments

* **Key:** The key pressed expressed as a string. Valid values can be found in [KeyboardEvent.key](https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_key_values)
* **Shift:** True if the shift key has to be pressed while pressing the main key.
* **Ctrl:** True if the ctrl key has to be pressed while pressing the main key.

#### Mouse movement

Moving the mouse can be used to trigger an action.

```typescript
this.inputService.setMousebind(InputAction.rotate, new Mousebind(0.01, true, "x"))
```

The mousebind takes 3 arguments.

* **Sensitivity:** A multiplier for the mouse movement's difference in position (delta)
* **Flipped:** If the movement of the mouse should be interpreted in a flipped axis.
* **Axis:** The axis of mouse movement connected to this action. Either 'x' or 'y'.

#### Mouse wheel movement

The input used for scrolling such as a mouse wheel or some gesture on a touch pad can be configured using the `setWheelbind` method.

```typescript
this.inputService.setWheelbind(InputAction.zoomCamera, new Wheelbind(0.0003, false))
```

The wheelbind takes 2 arguments.

* **Sensitivity:** A multiplier for the wheel's movement in either direction.
* **Flipped:** If the movement of the wheel should be interpreted in a flipped axis.

### Binding actions to callbacks

Now that actions can be triggered by player input, they also need to somehow affect the game. This can be done by using methods on the InputService for to bind various callback methods to actions.

#### Toggle

Some behaviour can be triggered by a boolean for either being true or false. This is appropriate for for example a character's movement direction or if the character is sprinting as opposed to walking.

```typescript
this.inputService.bindToggle(InputAction.sprint, player.toggleSprint)
```

#### Delta

Some behaviour is better represented by the difference in a value. For example, as you move your mouse you may want to the player's character to rotate in the direction of the mouse movement. This can be done by using the `bindDelta` method which takes a callback which receives a number.

```typescript
this.inputService.bindDelta(InputAction.rotate, player.rotateY)
```

## Player controllers

To organize your code, it is suitable to put the code related to your actions inside a player controller service. In the example below, we can see the implementation of a player controller.

The inputs are set up in the constructor. These may instead be read from some persistent storage of the player's configuration to enable the player to reconfigure these. Remember to also start the input service to start capturing the player's input using the `start` method.

The player controller has a method to possess a character. This gives the controller a reference to a character which in this example is an actor.

```typescript
enum InputAction {
  moveForward,
  moveBackward,
  moveLeft,
  moveRight,
  jump,
  sprint,
  crouch,
  rotate,
  rotateCamera,
  zoomCamera
}


@Service()
class PlayerController {
  private inputService = inject(InputService)
  private character: Character
  
  constructor() {
    this.inputService.setKeybind(InputAction.jump, new Keybind(" "))
    this.inputService.setKeybind(InputAction.sprint, new Keybind("Shift"))
    this.inputService.setKeybind(InputAction.moveForward, new Keybind("w"))
    this.inputService.setKeybind(InputAction.moveBackward, new Keybind("s"))
    this.inputService.setKeybind(InputAction.moveLeft, new Keybind("a"))
    this.inputService.setKeybind(InputAction.moveRight, new Keybind("d"))
    this.inputService.setMousebind(
      InputAction.rotate,
      new Mousebind(0.01, true, "x")
    )
    this.inputService.setMousebind(
      InputAction.rotateCamera,
      new Mousebind(0.003, false, "y")
    )
    this.inputService.setWheelbind(
      InputAction.zoomCamera,
      new Wheelbind(0.0003, false)
    )
    
    this.inputService.start()
  }

  public possess(character: Character) {
    this.character = character
    this.bindCharacterInput()
  }

  private bindCharacterInput() {
    const playerMove = this.character.movement.directionInput
    const playerJump = this.character.movement.jumpInput
    const playerSprint = this.character.movement.sprintInput

    this.inputService.bindToggle(InputAction.jump, playerJump.toggle)
    this.inputService.bindToggle(InputAction.sprint, playerSprint.toggle)
    this.inputService.bindToggle(InputAction.moveForward, playerMove.togglePositiveY)
    this.inputService.bindToggle(InputAction.moveBackward, playerMove.toggleNegativeY)
    this.inputService.bindToggle(InputAction.moveLeft, playerMove.toggleNegativeX)
    this.inputService.bindToggle(InputAction.moveRight, playerMove.togglePositiveX)
    this.inputService.bindDelta(
      InputAction.rotate,
      this.character.movement.rotationInput.rotateY
    )
    this.inputService.bindDelta(
      InputAction.rotateCamera,
      this.character.thirdPartyCamera.rotationInput.rotateX
    )
    this.inputService.bindDelta(
      InputAction.zoomCamera,
      this.character.thirdPartyCamera.zoomInput.increment
    )
  }
}
```


# Collision detection

Collision detection serves the essential purpose of determining when and how objects within the game world interact with each other. It plays a crucial role in creating realistic and engaging gameplay experiences.

1. **Prevent moving through objects:** Collision detection is necessary to ensure that the player or other objects don't move through other objects, walls or the ground. If any object is given a collision shape, it will by prevent other objects with a collision object from intersecting with it.
2. **Physics simulation:** In some games, physics simulations are used to create realistic movement and interactions. Collision detection is a key component of these simulations, allowing objects to bounce, slide, or respond to forces naturally.
3. **Triggers and Events:** Collision detection can be used to trigger events or scripts when specific conditions are met. For example, walking into a specific area might trigger a cutscene or the activation of a hidden pathway.

## Creating collision shapes

For the physics engine to know the shape of objects, the shape of the object needs to be provided using specific primitives. The graphical representation of an object that is rendered is often not the same as the physical representation.

As almost all objects in a scene will have need to have some physical shape defined, configuring these manually via code or in the editor could be very time consuming. Instead, this should be integrated in the asset creation pipeline. Any imported 3D model will have a collision shape generated automatically that best fits the 3D model. However, this may not be appropriate for your game play. In this case you can design the collision shapes in your 3D modeling tool and export these together with your model using specific naming conventions.

A physical shape can be supplied when creating a mesh programmatically using the MeshComponent. Instead of providing just a THREE.Mesh object, you can instead pass in a `PhysicalShapeMesh` which in addition to taking a geometry and material can take a shape object that describes the physical shape.

The following collision shapes can be used

* BoxCollisionShape
* PlaneCollisionShape
* SphereCollisionShape
* CylinderCollisionShape
* ConvexPolyhedronCollisionShape
* TrimeshCollisionShape
* MeshCollisionShape
* CapsuleCollisionShape

## Detecting actor collisions

In the example code below, we are creating two actors both with a mesh component to give them a visible geometry and a collision shape. Using the physics system, we can create a subscription on collisions with actors of a specific type. Every time the ball actor hits a target actor, the collision event will happen. When this even happen you could for example increase a player's score or trigger some other action in your game.

```typescript
@Actor()
class Ball extends BaseActor {
    private physicsSystem = inject(PhysicsSystem)
    private mesh = attach(MeshComponent, {
      mass: 1,
      bodyType: PhysicsBodyType.dynamic,
      object: new PhysicalShapeMesh(
          new SphereGeometry(.2, 20, 10),
          new MeshStandardMaterial({ color: 0xeff542 }),
          new SphereCollisionShape(.2))
    })
    
    onInit() {
      this.physicsSystem.onCollisionWithActorType(this, Target)
        .subscribe(other => {
          console.log('Hit target actor', other)
        })
    }
}

@Actor()
class Target extends BaseActor {
    private mesh = attach(MeshComponent, {
      bodyType: PhysicsBodyType.static,
      continousCollisionDetection: true,
      object: new PhysicalShapeMesh(
        new BoxGeometry(1, 1, 0.1),
        new MeshStandardMaterial({ color: 0xeff542 }),
        new BoxCollisionShape(new Vector3(1, 1, 0.1)))
    })
}
```

### Collision events

You can subscribe to collision events on the physics system.

* **onBeginContact** - When the actor starts getting contact with any surface
* **onEndContact** - When the actor stops having contact with a surface
* **onHasContactChanged** - When the actor either has contact with any surface or not in contact with anything changes.
* **onCollisionWithActor** - When the actor collides with another specific actor.
* **onCollisionWithActorType** - When the actor collides with any actor of a specific class.
* **onBeginOverlapWithActorType** - When the actor starts overlapping with another actor for a specific class. This is useful for trigger volumes.
* **onEndOverlapWithActorType** - When the actor stop overlapping with another actor for a specific class. This is useful for trigger volumes.
* **onBeginOverlapWithActor** - When the actor starts overlapping with another specific actor. This is useful for trigger volumes.
* **onEndOverlapWithActor** - When the actor stops overlapping with another specific actor. This is useful for trigger volumes.


# Physics

Hology Engine allows you to simulate physics with both dynamic and kinematic physics bodies. Beyond just collision detection, you can use physics to apply forces, control velocities, and dampening.

## Physics System

Most of the physics functionality is accessed using the Physics System service. You can access this service by injecting it in your actor or actor component class.

```typescript
import { Actor, BaseActor, PhysicsBodyType, PhysicsSystem, attach, inject } from "@hology/core/gameplay";

@Actor()
class ExampleActor extends BaseActor {
    private physics = inject(PhysicsSystem)
}
```

## Physical actors

In order for actors to represent physical objects that can be moved using physics simulation or collide with other physical objects, they need to be added to the physics system. While this can be done automatically when using existing components such as `MeshComponent` and `CharacterMovementComponent`, you can also add the actor to the physics system yourself. You would normally do this if you are not using the previously mentioned component that does this for you.

```typescript
import { Actor, BaseActor, PhysicsBodyType, PhysicsSystem, attach, inject } from "@hology/core/gameplay";

@Actor()
class ExampleActor extends BaseActor {
    private physics = inject(PhysicsSystem)
    
    onInit() {
        this.physics.addActor(this, [new BoxCollisionShape(1,1,1)], { 
            isTrigger: false,
            mass: 1,
            friction: 1,
            continousCollisionDetection: false,
            type: PhysicsBodyType.dynamic
          })
    }
}
```

When you add an actor you add a reference to the actor itself, followed by an array of at least one collision shape and some additional options. You can have multiple collision shapes to represent a more complex shape.

* **isTrigger** - Whether it should just detect overlapping events
* **mass** - The mass of the actor which affects how its velocity will change when colliding with other objects.
* **friction** - A lower value will make other objects slide more easily.
* **continousCollisionDetection** - Whether to enable continuous collision detection which is a bit more computationally expensive but can lead to better collision detection with fast objects.
* **type** - Which type of physics body. Read more about [Physics body types](https://docs.hology.app/gameplay/physics/physics-body-types)


# Physics body types

The physics system needs to understand how to simulate physics for an object and how these objects will interact with others. The physics body type has great effect on this so it is important to select an appropriate type.

## Static Bodies

**Description:** Static bodies are objects that do not move. They are unaffected by forces or collisions, and they do not have a velocity. Static bodies are typically used for objects that are part of the environment or scene and should remain stationary, such as the ground, walls, or other immovable objects.

**Characteristics:**

* **Immovable:** Static bodies remain in a fixed position.
* **Unaffected by Forces:** They do not respond to forces, impulses, or collisions.
* **No Dynamics:** They do not have linear or angular velocity.

**Usage Example:** Static bodies are used for objects like floors, platforms, or boundaries in a game or simulation, where these objects should not move but can interact with dynamic bodies.

## Kinematic Bodies

**Description:** Kinematic bodies are objects that can move but are not influenced by physics forces. Their movement is controlled by setting their velocity or position directly. Kinematic bodies are useful for objects that need to follow a specific path or animation, such as moving platforms or characters with scripted movements.

**Characteristics:**

* **Controlled Motion:** Kinematic bodies are moved explicitly by setting their position or velocity.
* **Unaffected by Forces:** They do not respond to forces, impulses, or collisions, but they can affect dynamic bodies through collisions.
* **Predictable Movement:** Their motion is defined by the programmer or simulation logic.

**Usage Example:** Kinematic bodies are used for objects that need to move in a controlled manner, such as elevators, moving platforms, or NPCs following a path.

## Dynamic Bodies

**Description:** Dynamic bodies are objects that are fully simulated by the physics engine. They respond to forces, impulses, and collisions, and their motion is determined by the laws of physics. Dynamic bodies are used for objects that need realistic physical behavior, such as characters, vehicles, and objects that can be thrown or pushed.

**Characteristics:**

* **Fully Simulated:** Dynamic bodies are affected by forces, impulses, collisions, and gravity.
* **Realistic Motion:** Their movement is determined by physics calculations, making them behave naturally.
* **Interactive:** They can interact with other bodies (static, kinematic, and dynamic).

**Usage Example:** Dynamic bodies are used for objects that need to behave realistically in a physical simulation, such as balls and crates


# Applying forces

For actors that are added to the physics system with a dynamic physics body type, you can apply force in various ways to make it move.

* **applyTorque** - Applies a continuous rotational force (torque) to an object. This method is used to change the angular velocity of the object over time. The torque is specified in the global coordinate system.
  * `torque`: A vector representing the torque to be applied. This vector determines the direction and magnitude of the rotational force.
* **applyTorqueImpulse** - Applies an instantaneous torque impulse to an object. This method is used to change the angular velocity of the object immediately. The impulse is specified in the global coordinate system.
  * `torqueImpulse`: A vector representing the torque impulse to be applied. This vector determines the direction and magnitude of the instantaneous rotational force.
* **applyForce** - Applies a continuous force to an object. This method is used to change the linear velocity of the object over time. The force is specified in the global coordinate system and can be applied at a specific point on the object.
  * `force`: A vector representing the force to be applied. This vector determines the direction and magnitude of the force.
* **applyImpulse** - Applies an instantaneous force impulse to an object. This method is used to change the linear velocity of the object immediately. The impulse is specified in the global coordinate system and can be applied at a specific point on the object.
  * `force`: A vector representing the force impulse to be applied. This vector determines the direction and magnitude of the instantaneous force.
* **applyLocalForce** - Applies a continuous force to an object. This method is used to change the linear velocity of the object over time.
  * `force`: A vector representing the force to be applied in the object's local coordinate system.
  * `localPoint`: A vector representing the point of application of the force in the global coordinate system.
* **applyLocalImpulse** - Applies an instantaneous force impulse to an object. This method is used to change the linear velocity of the object immediately.
  * `force`: A vector representing the force impulse to be applied in the object's local coordinate system.
  * `localPoint` : A vector representing the point of application of the impulse in the object's global coordinate system.


# Ray casting

Ray casting is a technique to identify collisions of a ray from one point to another in 3D space. This can be useful to for example test if a character is in line of sight of another character or get the hit point of a bullet shot from a gun.

## Ray test

The physics system has a method called rayTest which allows you to calculate collisions of a ray between two points.

```typescript
import { Service, inject, PhysicsSystem, RayTestResult } from "@hology/core/gameplay"
import { Vector3 } from "three"

@Service()
class ExampleService {
    private physics = inject(PhysicsSystem)
    
    checkCollisions() {
        const result = new RayTestResult()
        const from = new Vector3(0,0,0)
        const to = new Vector3(0,0,100)
        this.physics.rayTest(from, to, result)
        
        console.log(result)
    }
}

export default ExampleService


```

### Parameters

* **from**: Vector3 - The starting point of the ray
* **to**: Vector3 - The ending point of the ray.
* **result**: RayTestResult - An object in which to store the result of the ray. If you are doing a lot of ray casting, it is often best to reuse the RayTestResult object to avoid garbage collection and improving the performance of your code.
* **options**: RayTestOptions - Options to change the behaviour or debug of the ray testing.

### RayTestResult

* **hasHit**: boolean - Whether the ray hit an object.
* **hitPoint**: Vector3 - The point in global space in which the ray hit
* **hitNormal**: Vector3 - The normal of the surface hit
* **distance**: number - The distance to the hit point from the start of the ray.
* **actor**: BaseActor - If the hit object is an actor, this field will reference the actor instance.

### RayTestOptions

* **debugColor**: ColorRepresentation - If you have enabled the debug mode of the physics system, it will show an arrow for the ray. Use this option to change the color of the arrow to more easily distinguish it from others.
* **debugLifetime**: number - How many milliseconds the arrow should be visible. If you are doing a lot of raytesting.
* **excludeActor**: BaseActor - It is sometimes necessary to exclude some actor from collisions. Often it could be the actor from which the ray should be starting from to avoid colliding with the actor itself.


# Trigger volumes

Trigger volumes is a type of volume that you can place within your game world to detect when other objects or characters enter or exit it. Trigger volumes are commonly used in games for various purposes, such as triggering events or activating gameplay mechanics.

## Creating trigger volumes

### TriggerVolumeActor

A trigger volume actor can be placed as an object in your scene. You can find it in the asset browser under actors. You can then refer to the trigger volume actor by adding it as a parameter to another actor.

### TriggerVolumeComponent

A trigger volume can be created by attaching a TriggerVolumeComponent to an actor. The trigger volume is a box so you need to provide the dimensions of it.

## Handling trigger volume events

Whenever an actor enters or exists a trigger volume, you can trigger some functionality. In the example below, every time the Character actor overlaps with a Coin actor, it increases the number of collected coins bye one and then removes the coin actor from the world.

```typescript
@Actor()
class Character extends BaseActor {
    private physicsSystem = inject(PhysicsSystem)
    private world = inject(World)
    
    collectedCoins: number = 0

    onInit() {
        this.physicsSystem.onBeginOverlapWithActorType(this, Coin)
            .subscribe(coin => {
                this.collectedCoins++
                world.remove(coin)                
            })
    }
}

@Actor()
class Coin extends BaseActor {
    private triggerVolume = attach(TriggerVolumeComponent, { 
        dimensions: new Vector3(1, 1, 1) 
    })
}
```


# Character movement

For a game where you have a character that can walk, run, jump, etc, you will need some generic character movement functionality. If you want to have complete control, you could implement this yourself, but there is also a built in character movement component that you can attach to your character actor.

## Example

The actor implementation below illustrates how you can attach the `CharacterMovementComponent` to an actor and pass in various properties to configure its behaviours. In the example we are also attaching a mesh component to give the character a visual representation. Also, the third person camera component is attached to have a camera following the character.

```typescript
@Actor()
class CharacterActor extends BaseActor {
  private physicsSystem = inject(PhysicsSystem)
  private viewController = inject(ViewController)

  private mesh = attach(MeshComponent, {
    object: new Mesh(
      new CylinderBufferGeometry(.5, .5, 2),
      new MeshStandardMaterial({color: 0xffffff})
    ) 
  })
  private thirdPersonCamera = attach(ThirdPersonCameraComponent)
  public movement = attach(CharacterMovementComponent, {
    autoStepMaxHeight: 0,
    colliderHeight: 2,
    colliderRadius: .5,
    maxWalkingSlopeAngle: 70,
    maxSpeed: 3,
    maxSpeedBackwards: 3,
    maxSpeedSprint: 7,
  })
}

```

You likely want to tweak the parameters of the character movement component a lot to find something that works well for your game.

In this example, we make the movement component instance public because it provides an interface to control movement which we want to be accessible from a player controller.

### Controlling the movement

With the above code, the character will simply fall to the ground where it is spawned and not move. To control the character you need to bind various action inputs that are exposed on the movement component.

* **directionInput** - For controlling the movement of the character forward, backward, left and right
* **jumpInput** - Toggle when you want the character to jump
* **sprintInput** - Toggle to change the movement speed to the configured sprinting speed
* **rotationInput** - Rotate the character around the y-axis to turn left and right.

The code example below illustrates how code could look inside a player controller using an injected `InputService` and a referenced character actor with a movement component.

```typescript
const playerMove = this.character.movement.directionInput
const playerJump = this.character.movement.jumpInput
const playerSprint = this.character.movement.sprintInput

this.inputService.bindToggle(InputAction.jump, playerJump.toggle)
this.inputService.bindToggle(InputAction.sprint, playerSprint.toggle)
this.inputService.bindToggle(InputAction.moveForward, playerMove.togglePositiveY)
this.inputService.bindToggle(InputAction.moveBackward, playerMove.toggleNegativeY)
this.inputService.bindToggle(InputAction.moveLeft, playerMove.toggleNegativeX)
this.inputService.bindToggle(InputAction.moveRight, playerMove.togglePositiveX)
this.inputService.bindDelta(
  InputAction.rotate,
  this.character.movement.rotationInput.rotateY
)
```

Read more about how to handle player input in the [Player input](https://docs.hology.app/gameplay/player-input) guide.

## Rotate to movement direction

The default settings for the character movement and the third person camera is that the camera is behind the character at all times and the character is also facing in the forward direction. This is appropriate for some games when you want the character to always face the direction the camera is looking such as third person shooters. In some other games, it is more fitting to be able to quickly change movement direction while running at full speed as opposed to strafing or walking backwards.

This can be accomplished by setting the option `rotateToMovementDirection` to true in the movement component.

In this case, you often also want the camera to be able to rotate more freely so that the direction you run toward doesn't have to be the same direction that the camera is facing. To configure this, set `fixedBehind` on the `ThirdPersonCameraComponent` to false.

```typescript
@Actor()
class CharacterActor extends BaseActor {  
  private thirdPersonCamera = attach(ThirdPersonCameraComponent, {
    fixedBehind: false
  })
  public movement = attach(CharacterMovementComponent, {
    rotateToMovementDirection: true
  })
}
```

In the original input configuration, we only set up the character to be rotated when moving the mouse. However, in order to be able to spin the camera around more freely, we need to also update the third person camera component. See the code below for how bind a function that updates two rotation inputs simultaneously.

```typescript
this.inputService.bindDelta(
    InputAction.rotate,
    (delta) => {
      this.character.movement.rotationInput.rotateY(delta)
      this.character.thirdPersonCamera.rotationInput.rotateY(delta)
    }
  )
```

It is also possible to change these parameters while the game is running. For example, you might rotate to movement direction for normal movement but when the character aims a ranged weapon, you may want to not rotate to movement direction, allowing you to strafe and walk backward while still facing in the same direction. Also, you set the camera to be fixed behind so that you can control where you are aiming.

See the code below for how you could toggle these parameters. You would likely also show a crosshair in the UI to help the player aim and update some state for character animation to play the a dedicated animation while aiming.

```typescript
@Actor()
class CharacterActor extends BaseActor {  
  private thirdPersonCamera = attach(ThirdPersonCameraComponent, {
    fixedBehind: false
  })
  public movement = attach(CharacterMovementComponent, {
    rotateToMovementDirection: true
  })
  
  startAiming() {
     this.thirdPersonCamera.fixedBehind = true
     this.movement.rotateToMovementDirection = false
  }
  
  stopAiming() {
     this.thirdPersonCamera.fixedBehind = false
     this.movement.rotateToMovementDirection = true
  }
}
```


# Pointer events

You can capture pointer events from the mouse or touch to interact with 3D objects in your world. This can be done with the `PointerEvents` service which can be injected in other services, actors or components.

## Using the PointerEvents service

To use the PointerEvents service, inject it in in your game code. In the following example we do it in the game service, but you may use it in any other service or actor. The PointerEvents service has many methods to subscribe to different types of events. In the example we are simply passing in the entire scene to detect clicking on any object. However, the methods support passing in specific objects, actors or actor types.

```typescript
import { GameInstance, Service, PointerEvents, inject, World } from '@hology/core/gameplay';

@Service()
class Game extends GameInstance {
  private pointerEvents = inject(PointerEvents)
  private world = inject(World)

  onStart() {
    this.pointerEvents.onClickObject3D(this.world.scene).subscribe((event) => {
      console.log("Clicked at point: ", event.intersection.point)
    })
  }
}
```

## Events

The following events can be subscribed to.

* **click** - The object was clicked, meaning that the touch or mouse down event started and ended on the same object.
* **pointer down** - The touch or mouse down event started on the object.
* **pointer up** - The touch or mouse up event event ended on the object.
* **pointer enter** - The touch or mouse pointer was moved onto the object. This event is only emitted once until the pointer leaves the object.
* **pointer leave** - The touch or mouse pointer moved away from the object.
* **pointer move** - The touch or mouse pointer is moving over the object. The event is emitted whenever the pointer moves.

## Targets

When subscribing to events you can use different targets

* **Object3D** - Any 3D object in the scene can be used for events.
* **Actor** - A specific actor instance.
* **Actor type** - An actor class to capture events from any instance of that type.

## Methods

The following methods exist on the PointerEvents service for different types of events and targets.

* onPointerEnterObject3D
* onPointerEnterActor
* onPointerEnterActorType
* onPointerLeaveObject3D
* onPointerLeaveActor
* onPointerLeaveActorType
* onClickObject3D
* onClickActor
* onClickActorType
* onPointerDownActor
* onPointerDownActorType
* onPointerDownObject3D
* onPointerUpActor
* onPointerUpActorType
* onPointerUpObject3D
* onPointerMoveActor
* onPointerMoveActorType
* onPointerMoveObject3D

## Event object

When an event happens, your callback function will receive an object containing information about the event.

* **object / actor** - Depending on if you are using the Object3D or Actor variant, you will receive either the object or actor that was interacted with.
* **intersection** - Information about the intersection of the raycast with the object.
  * **distance**: number - distance between the origin of the ray and the intersection
  * **point**: Vector3 - point of intersection, in world coordinates
  * **face**: Face - intersected face
  * **object**: Object3D - the intersected object
  * **uv**: Vector2 - U,V coordinates at point of intersection
  * **uv2**: Vector2 - Second set of U,V coordinates at point of intersection


# Animation

To get 3D models to move, you can utilize animation clips that can be loaded from 3D model files. Hology Engine also provides functionality to help transition between animations based on state transitions as well as a character animation component to mask animations to only affect lower or upper body.


# Animation system

The rendering library Three.js used in Hology Engine provides an animation system that you can you on its own. Take a look at the [official Three.js documentation](https://threejs.org/docs/#manual/en/introduction/Animation-system) to get a better understanding of how to directly use animation clips, mixer, actions and more.

Below we can see how an Animation Mixer can be used to play animations.

```typescript
import { Actor, AssetLoader, BaseActor, inject } from '@hology/core/gameplay';
import * as THREE from 'three';

@Actor()
class Character extends BaseActor {
  private assetLoader = inject(AssetLoader)
  private mixer: THREE.AnimationMixer

  async onInit(): Promise<void> {
    // We load a model by name that has previously been 
    // imported to the project in the editor.
    const model = await this.assetLoader.getModelByAssetName('character-human')
    const mesh = model.scene
    // Adding the model to the actor's object to be rendered. 
    this.object.add(mesh)    

    // Each object to be animated needs its own animation mixer
    const mixer = new THREE.AnimationMixer(mesh)
    // Find a clip from loaded animations by name
    const clip = THREE.AnimationClip.findByName(model.animations, 'idle')
    const action = mixer.clipAction(clip)
    action.play()

    this.mixer = mixer
  }

  onUpdate(deltaTime: number): void {
    this.mixer.update(deltaTime)
  }

}

export default Character
```

You can download this example project to see the code in action.

{% embed url="<https://github.com/hologyengine/animation-tutorial/tree/main>" %}

The above example illustrates how to use the constructs provided by the rendering library ThreeJS for playing animations. If you want to animate something like a character, it can be better to use Hology Engine's `CharacterAnimationComponent` which provides easier ways of transitioning between animations and playing different animations for upper and lower body.


# Character Animation

Animating a character requires seamlesslly blending between different animation based on what the character is doing. The `CharacterAnimationComponent` makes this easy allowing you to declaratively define how to transition between animation clips using state machines.

## Playing a single animation

First, we will use the character animation component to simply play a single animation similarly to the example in the [Animation system](https://docs.hology.app/gameplay/animation/animation-system) article.

```typescript
import { Actor, AssetLoader, BaseActor, attach, inject } from '@hology/core/gameplay';
import { CharacterAnimationComponent } from '@hology/core/gameplay/actors';
import * as THREE from 'three';

@Actor()
class Character2 extends BaseActor {
  private assetLoader = inject(AssetLoader)
  private characterAnimation = attach(CharacterAnimationComponent)

  async onInit(): Promise<void> {
    const model = await this.assetLoader.getModelByAssetName('character-human')
    const mesh = model.scene
    this.object.add(mesh)    

    const clip = THREE.AnimationClip.findByName(model.animations, 'idle')
    
    this.characterAnimation.setup(mesh)
    this.characterAnimation.play(clip)
  }

}

export default Character2
```

## Using animation state machines

To visualize what the character is doing we likely want to play different clips. This is easily done with an animation state machine which can transition between different animation clips based on state and defined transition rules.

The example below is a bit more involved to better illustrate how animation state machines can be used.

1. First, we load the model and extract the animation clips we intend to use.
2. Then we set up the character animation component with the mesh we intend to animate.
3. To play different animation based on state changes, we set up some way for the player to provide input. We use an `ActionInput` to represent the state of the player wanting to walk. After that we configure the input service. You can read more about how this works in [Player input](https://docs.hology.app/gameplay/player-input). Note that this code may ideally belong somewhere outside the character actor so that the character actor also can be used without being affected by the player's input.
4. Create animation states for each clip. These allow us to build up the state machine for how to transition between them.
5. We use the transitionsBetween method with a predicate to transition to the *walk* state when walk input is activated. If the provided function later returns false, such as when the player no longer presses walk, the animation will return back to the idle animation.
6. Create an animation state machine and pass in the initial state.
7. Finally, instruct the character animation component to play the state machine.

```typescript
import { Actor, AnimationState, AnimationStateMachine, AssetLoader, BaseActor, attach, inject } from '@hology/core/gameplay';
import { CharacterAnimationComponent } from '@hology/core/gameplay/actors';
import { ActionInput, InputService, Keybind } from '@hology/core/gameplay/input';
import * as THREE from 'three';

enum InputAction {
  walk
}

@Actor()
class Character3 extends BaseActor {
  private assetLoader = inject(AssetLoader)
  private characterAnimation = attach(CharacterAnimationComponent)
  private input = inject(InputService)

  async onInit(): Promise<void> {
    // 1
    const model = await this.assetLoader.getModelByAssetName('character-human')
    const mesh = model.scene
    this.object.add(mesh)    

    const idleClip = THREE.AnimationClip.findByName(model.animations, 'idle')
    const walkClip = THREE.AnimationClip.findByName(model.animations, 'walk')
    
    // 2
    this.characterAnimation.setup(mesh)

    // 3
    const pressingWalk = new ActionInput() 

    this.input.setKeybind(InputAction.walk, new Keybind('w'))
    this.input.bindToggle(InputAction.walk, pressingWalk.toggle)
    this.input.start()

    // 4
    const idle = new AnimationState(idleClip)
    const walk = new AnimationState(walkClip)

    // 5
    idle.transitionsBetween(walk, () => pressingWalk.activated)
    
    // 6 
    const asm = new AnimationStateMachine(idle)

    // 7
    this.characterAnimation.playStateMachine(asm)
  }

}

export default Character3
```

In the next article, we will explain animation state machines more in depth and how they can be used to represent various transitions.


# Animation State Machine

In the previous article on Character Animation, we saw a simple example of transitioning to and from another animation. The animations state machine is able to do much more than that to handle various use cases which will be explained in this article.

## State graph

The animation state machine can be thought of as a directed graph linking different states with a predicate function that determines if it is possible to transition to the other state. Some transitions may be bi-directional, meaning that you can transition back and forth if the predicate is true or false. However, in some cases it may be more appropriate to not be able to go back in which case you can have uni-directional transitions.

## Transitions

Transitions are defined using functions on the animation states to link to other states.

* **transitionsTo(state, predicate)** - If the predicate returns true, the state machine will transition to the given state.
* **transitionsBetween(state, predicate)** - Similar to `transitionsTo` but also defines the opposite transition rule to allow for going back and forth between the states.
* **transitionsOnComplete(state, predicate?)** - For states that naturally ends such as performing a jump that should transition to a falling state after the jump animation finishes. The predicate is optional but can be useful when you have multiple possible states that you can transition to and you need to select one for which the predicate is true.

## Child states

A child state represents a more specific version of another state. For example, you may have a walking state and then different states for strafing left and right that are children of the walking state. If you then want to have a possible transition to a jump state, you can define the transition from the root walking state to the jump state without having to also define transitions from all the different versions of walking states.

For a character with a complex movement system and lots of different animations, the amount of states can be large and the amount of possible transitions between all these states can becomes hard to manage. In these cases child states may help.

In the following example we see how child states can be created using the `createChild` function. We use some variables in the example to represent state such as what direction the player is moving in and whether the character is falling or not. We can define a transition from any walking state by using the parent `walk` state and using the `transitionsBetween` function to the `fall` state.

```typescript
let movementDirection = 0
let falling = false

const walk = new AnimationState(walkClip)
const walkLeft = walk.createChild(walkLeftClip, () => movementDirection < 0)
const walkRight = walk.createChild(walkRightClip, () => movementDirection > 0)

const fall = new AnimationState(fallClip)
walk.transitionsBetween(fall, () => falling)
```

For a more complex example, see the code for the third person starter project.

{% embed url="<https://github.com/hologyengine/starter-third-person-shooter/blob/main/src/actors/character-actor.ts#L119-L149>" %}


# Character Root Motion

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2Fgit-blob-4a6f200450aa7ecf26aec92602e0b0299afe7fe2%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

Root motion is a technique to let an animation control the movement of a character, usually used temporarily when performing an ability that involves movement such as an attack where the character steps forward.

This is done by having a bone in the character's armature that has a translation track that moves the whole armature. The character movement component can use this translation to move the character. This will move the entire character actor including any physics collider so that it is able to detect collisions, move up and down slopes. When the animation is over, the player can continue controlling the character from its new position.

## Using root motion

In order to setup a root motion animation we first need to do 2 things

1. Setup the animation component with a root bone. The root bone is the bone that should have the translation animation and usually has no or very minor rotation.
2. Wrap an AnimationClip with a RootMotionClip. This will provide information to the animation system for how to treat this animation.

```typescript

// 1
const bone = this.characterMesh.getObjectByName("mixamorigSpine2") as Bone 
this.animation.setup(this.characterMesh, [], bone)
// 2
const rootMotionSlash = RootMotionClip.fromClip(attackClips.spinSlash, false)
```

To then play the animation when the character performs an ability such as an attack, roll, etc., you need to perform 2 things.

1. Play the root motion clip created earlier.
   1. **In Place** - We also specify that this animation is not be be played "inPlace" as we want it to have full control of the character's animation.
   2. **Loop -** Set loop to false as the animation should automatically end after having been played once.
   3. **Priority -** This animation will override any existing animation playing such as animation controlled with an animation state machine by passing in a higher priority value.
2. Set the root motion action on the character movement component by retrieving it from the character animation component. The movement will now let the animation control the desired movement and ignore any direction input from the player.

```typescript
// 1
this.animation.play(rootMotionSlash, {
  inPlace: false, loop: false, priority: 1
})
// 2
this.movement.setRootMotionAction(this.animation.getRootMotionAction())
```


# Sound

Playing sound is supported in Hology Engine using ThreeJS. See their documentation for more detail on how to use [Audio](https://threejs.org/docs/#api/en/audio/Audio) and [Positional Audio](https://threejs.org/docs/#api/en/audio/PositionalAudio).

## Playing sound

In the code below we can see how we can utilize Audio instances, load audio files and play sound.

The following numbered points refer to different parts of the code below.

1. Each sound that needs to be played needs its own instance of Audio. You can reuse audio instances but to play multiple sounds at the same time, you will need separate instances.
2. Load an audio file directly from the public directory. These don't have to be imported in the editor before.
3. To use the loaded audio, use the `setBuffer` function. You can also adjust the volume and other settings which you can read more about in the [ThreeJS docs](https://threejs.org/docs/#api/en/audio/Audio).
4. Play the sound. If the sound is already playing however, you need to stop it first.

```typescript
import { inject, Service, World, GameInstance, ViewController, AssetLoader } from '@hology/core/gameplay';
import * as THREE from 'three';

@Service()
class Game extends GameInstance {
  private world = inject(World)
  private view = inject(ViewController)
  private assetLoader = inject(AssetLoader)

  // 1
  private sound = new THREE.Audio(this.view.audioListener);

  async onStart() {    
    // 2
    const buffer = await this.assetLoader.getAudioAtPath('data/asset-resources/impactWood_heavy_001.ogg')
    // 3
    this.sound.setBuffer(buffer).setVolume(0.5)
  }

  playSound() {
    if (this.sound.isPlaying) {
      this.sound.stop()
    }
    // 4
    this.sound.play();
  }
}

export default Game
```

You can see a complete example for playing sound and run it locally to it out yourself here.

{% embed url="<https://github.com/hologyengine/audio-tutorial/tree/main>" %}


# Audio parameter

It is possible to pass in an audio asset to an actor as a parameter in the editor. This makes it possible to easily change the sound that an actor plays from the editor.

The code below illustrates how to define an audio parameter.

1. First define the parameter. Read more about parameters in [Actor parameters](https://docs.hology.app/gameplay/actors/actor-parameters)
2. Inject the View controller to access the global audio listener.
3. Create the instance of a new sound instance to be able to play the audio clip.
4. Set the sound buffer using the value of the audio parameter in the `onInit` function. At this point the parameters are set. Read more about actors lifecycle functions in [Actor lifecycle](https://docs.hology.app/gameplay/actors/actor-lifecycle)
5. Finally, we define a function that can be called on the actor to play the sound which could be called whenever the sound should play.

```typescript
import { Actor, BaseActor, ViewController, inject } from "@hology/core/gameplay";
import { Parameter } from "@hology/core/shader/parameter";
import * as THREE from 'three'

@Actor()
class ExampleActor extends BaseActor {
  @Parameter() audio: AudioBuffer;
  private view = inject(ViewController)
  private sound = new THREE.Audio(this.view.audioListener)

  onInit() {
    this.sound.setBuffer(this.audio)
  }
  
  playSound() {
    this.sound.play()
  }

}

export default ExampleActor

```


# World

The World service is used for code that needs to interact with the world like spawning actors, finding actors or controlling directional light.

Access the world by injecting it in your services, actors and component classes.

```typescript

@Service()
class Game extends GameInstance {
    private world = inject(World)
    
    onStart() {
        
    }
    
}
```

## Directional Light

By default, every scene has directional light which produces shadows. You may want to access this to update the direction or intensity at runtime.

```typescript
@Service()
class Game extends GameInstance {
    private world = inject(World)
    
    onStart() {
        this.world.directionalLight.intensity = 0.2 
        this.world.directionalLight.direction.applyAxisAngle(new THREE.Vector3(0,0,1), Math.PI / 2)

    }
    
}
```

The directional light exposes the following fields

* **direction**: Vector3 - The direction vector can be updated to change the direction of the light. This can be used to emulate a sun.
* **intensity**: number - How bright the light should be.
* **position:** Vector3 - The position of the directional light instance. This can not be changed; instead, change the direction.


# Spawn prefabs

You can spawn prefabs at runtime while the game is being played. This can be useful to for procedurally adding more complex objects to the scene. For example, if you have a house created in a prefab made up of many different meshes and even actors that reference other actors within the prefab, you can spawn all of this together.

To spawn a prefab, you first need to get the prefab asset from the AssetLoader service. With the prefab, you can call the `spawnPrefab` function with optional parameters for world position and rotation. This method is asynchronous and returns a promise as it loads any resources necessary to create the prefab and calls any actors `onInit` method. The returned promise contains a PrefabInstance which later can be used to remove the prefab, removing any objects included in the prefab from the scene and removing actors.

```typescript
import { Service, GameInstance, inject, World, AssetLoader } from '@hology/core/gameplay';
import { Vector3 } from 'three';

@Service()
class Game extends GameInstance {
  private world = inject(World)
  private assetLoader = inject(AssetLoader)

  async onStart() {
    const prefab = await this.assetLoader.getPrefabByName('test prefab')
    const instance = await this.world.spawnPrefab(prefab, new Vector3(0,0,0))

    setTimeout(() => {
      this.world.removePrefab(instance)
    }, 1000)
  }
}

export default Game

```


# Navigation

AI navigation enables non-player characters (NPCs) to move intelligently and interact with the game world. This involves creating systems that allow NPCs to traverse complex environments, avoid obstacles, and reach their goals in a realistic and efficient manner.

## Core concepts

**Pathfinding**: Pathfinding is the process of determining the optimal path for an NPC from its current position to a target destination. This involves algorithms such as A\* (A-star), Dijkstra's, and others, which calculate the shortest or most efficient route while considering various factors like terrain, obstacles, and NPC capabilities.

**Navigation Meshes (Navmeshes)**: A navigation mesh (navmesh) is a simplified representation of the game environment used for pathfinding. It divides the walkable areas of the game world into a network of interconnected polygons. Navmeshes allow NPCs to navigate complex environments efficiently by providing a clear map of traversable areas and the connections between them.

## Generating a Navmesh

To generate a Navmesh in your scene that adapts to the terrain and obstacles, you can simply ad the NavMesh actor to the scene. In the asset browser, filter on Actors and select NavMesh. Add it anywhere in the scene and it will generate a navmesh that can be used by the navigation service.

## Using navigation in gameplay

When there is a Navmesh actor in the scene, the Navigation service can utilise it to calculate an optimal path between two points or find the nearest point on the Navmesh around a point.

In the example below, we create a simple actor that will find the path to the player actor and move itself toward the player by a configured movement speed every frame.

```typescript

@Actor()
class AiCharacter extends BaseActor {

  private mesh = attach(MeshComponent, {
    object: new Mesh(
      new BoxGeometry(.5, .5, .5),
      new MeshStandardMaterial({color: 0xff0000})
    )
  })

  private navigation = inject(Navigation)
  private world = inject(World)

  private movementSpeed = .5

  onUpdate(deltaTime: number): void {
    const player = this.world.findActorByType(Character)

    const { success, path } = this.navigation.findPath(this.position, player.position)
    if (success) {
      const direction = path[1].clone().sub(this.position).normalize()
      this.position.addScaledVector(direction, deltaTime * this.movementSpeed)
    }
  }

}

```


# Behavior Trees

Behavior trees are a hierarchical model used to control the decision-making process of AI agents. They are composed of nodes that return a state of **Success**, **Failure**, or **Running**.

### Core Concepts

#### Nodes

Every node in a behavior tree is a subclass of `Node`. The tree is traversed from the root node down to leaf nodes.

* **Leaf Nodes**: Perform actions or checks (e.g., `ActionNode`, `ConditionNode`).
* **Composite Nodes**: Control the flow of execution by managing child nodes (e.g., `SequenceNode`, `SelectorNode`).
* **Decorator Nodes**: Modify the behavior of a single child node (e.g., `InverterNode`, `RepeatNode`).

#### Ticks

The tree is updated via a `tick(dt)` method, where `dt` is the delta time since the last update. This propagates down the tree, updating active nodes.

#### Node States

* `SUCCESS`: The node completed its task successfully.
* `FAILURE`: The node failed to complete its task.
* `RUNNING`: The node is currently executing and needs to be ticked again in the next frame.

### Built-in Nodes

Hology Engine provides a set of standard nodes to build your trees.

#### Composite Nodes

* **`SequenceNode`**: Runs children in order. Succeeds if all children succeed. Fails immediately if any child fails.
* **`SelectorNode`**: Runs children in order. Succeeds immediately if any child succeeds. Fails if all children fail.
* **`ParallelSequenceNode`**: Runs all children simultaneously. Succeeds if *all* children succeed. Fails if *any* child fails.
* **`ParallelSelectorNode`**: Runs all children simultaneously. Succeeds if *any* child succeeds. Fails if *all* children fail.
* **`WeightedRandomSelectorNode`**: Selects one child to run based on assigned weights.

#### Decorator Nodes

* **`InverterNode`**: Flips the result of its child (Success becomes Failure, Failure becomes Success).
* **`RepeatNode`**: Repeats the child node indefinitely.
* **`RepeatTimesNode`**: Repeats the child a specific number of times.
* **`RepeatUntilNode`**: Repeats the child until a condition function returns true.
* **`RepeatUntilFailNode`**: Repeats the child until it returns Failure.
* **`GuardNode`**: Only runs the child if a condition is met; otherwise returns Failure.
* **`CooldownNode`**: Prevents the child from running again until a cooldown period has passed.
* **`TimerNode`**: Runs the child for a specific duration, then returns Failure.
* **`DelayNode`**: Waits for a specified time before running the child.
* **`ThrottleNode`**: Limits how often the child node is ticked.

#### Leaf Nodes

* **`ActionNode`**: Executes a function that returns a `NodeState`.
* **`ConditionNode`**: Checks a condition function. Returns Success if true, Failure if false.
* **`WaitNode`**: Returns Running for a specified duration, then Success.
* **`SuccessNode`**: Always returns Success.
* **`FailNode`**: Always returns Failure.

### Creating a Behavior Tree

Behavior trees are typically constructed in your Actor's `onBeginPlay` method.

```typescript
import { 
  SelectorNode, SequenceNode, ActionNode, WaitNode, RepeatNode, 
  NodeState 
} from '@hology/core/gameplay';

// ... inside your Actor class

onBeginPlay() {
  // 1. Define leaf behaviors
  const attack = new ActionNode(() => {
    console.log("Attacking!");
    return NodeState.SUCCESS;
  });

  const patrol = new SequenceNode();
  patrol.addChild(new ActionNode(() => {
     console.log("Moving to waypoint");
     return NodeState.SUCCESS; 
  }));
  patrol.addChild(new WaitNode(1000)); // Wait 1 second

  // 2. Compose the tree
  const rootSelector = new SelectorNode();
  
  // Try to attack first, if that fails (e.g. condition not met), patrol.
  rootSelector.addChild(attack); 
  rootSelector.addChild(patrol);

  // 3. Wrap in a repeater to keep the AI active
  this.behaviorTree = new RepeatNode(rootSelector);
}

onUpdate(dt: number) {
  // 4. Update the tree every frame
  this.behaviorTree?.tick(dt);
}
```

### Custom Nodes

You can create custom nodes by extending `LeafNode` or `DecoratorNode` for more complex game-specific logic.

```typescript
import { LeafNode, NodeState } from '@hology/core/gameplay';

class CheckHealthNode extends LeafNode {
  constructor(private character: Character, private threshold: number) {
    super();
  }

  tick(dt: number): NodeState {
    if (this.character.health < this.threshold) {
      return NodeState.SUCCESS;
    }
    return NodeState.FAILURE;
  }
}
```

### Further Reading

For a complete step-by-step guide on implementing a chasing AI, check out the tutorial [Character AI behavior](https://docs.hology.app/tutorials/character-ai-behavior) .


# Performance

Performance is critical in real-time 3D applications. Ensuring smooth frame rates and responsive interactions makes the difference between something that *feels right* and something that *feels broken*.

### JavaScript is fast (if you use it right)

While JavaScript lacks some nice features of other programming languages often used in game development like C++ and C#, it is likely fast enough.

Modern JavaScript engines like V8 are highly optimized. Most performance issues come not from the language itself, but from poor coding patterns such as frequent object allocations, wrong data structures, or unnecessary physics queries.

By reusing objects, minimizing garbage collection, and keeping GPU usage efficient, **JavaScript can deliver smooth, real-time experiences**, even on lower-end hardware.


# Understanding performance

If your game is running slow, the first step should be to understand why. Performance could relate to many things, however in this context it refers to rendering and efficient hardware utilization.

## Show stats in game

You can show stats including by enabling the stats panel to get an initial understanding.

* **FPS** - How many frames are rendered per second. The upper limit is based on your monitor's refresh rate.
* **MS** - The number of milliseconds it takes to process each frame on the CPU. This includes your game play code as well as internal engine code. To achieve 60 FPS, you only have about 16 milliseconds to spare and some needs to be available for the GPU to render as well. Look out for spikes in this metric as it can result in dropping frames which leads to a bad player experience.
* **MB** - How much memory is currently being used for your rendered assets including geometries and textures.
* **Calls** - The number of draw calls each frame. A draw call is an instruction sent from the CPU to the GPU to draw something. Each mesh that needs to be rendered needs at least 1 draw call unless they are batched or instanced. This metric is likely related to the amount of objects in your scene and how varied geometries they have so it may not be related to your game play code unless you are creating a lot of objects. To ensure your game works well even on mid-tier mobile devices, try to aim for less than 150 draw calls.
* **Triangles** - The number of triangles rendered each frame. Similar to draw calls, this is mostly related to your scene and assets used, not necessarily your game play code.

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2Fgit-blob-d424df6aef0dd5c5c001dd9e448a8a97f4755d27%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

Show the stats panel by settings showStats to true on the ViewController service.

```typescript
@Service()
class Game extends GameInstance {
  private view = inject(ViewController)

  onStart(): void | Promise<void> {
    this.view.showStats = true
  }
}
```

{% hint style="info" %}
Make sure to **only** enable this for testing so you don't include it in the released game. Alternatively, add a keyboard shortcut for showing or hiding the stats in the game.
{% endhint %}

An alternative is to use the web browser's console to enable it using the following code.

```javascript
hology_view.showStats = true
```

## CPU or GPU bottleneck

One of the first things to check when trying to understand performance problems is if it due to CPU or GPU usage. In the stats panel, you can see in the MS (CPU) metric if it is high. If you are dropping frames and this metric exceeds 16 ms (in case your target frame rate is 60 fps), then the problem is likely due to processing on the CPU and otherwise the GPU. You can also open the task manager (Windows) or activity monitor (MacOS) to check the usage of the CPU and GPU. If your GPU usage is 100%,

### CPU problems

* **Expensive geometry calculations** - Game play code often involves a lot of geometry related math and algorithms, which can be expensive if done in excess. This includes for example raycasts and collision detection. Avoid doing this when necessary by adopting smarter algorithms and optimizations such as spatial partitioning to only process what is necessary for the player experience. If you absolutely need to do a lot of processing, you may choose to offload this to web workers or GPU compute.
* **Garbage collection** - If you are creating a lot of temporary objects in memory for every render update, they eventually have to be cleaned up which may block the main thread and therefore rendering and your game logic. However, this doesn't have to be an issue if you avoid making frequent new allocations. See [Avoid unnecessary allocations](https://docs.hology.app/gameplay/performance/avoid-unnecessary-allocations) to learn more.

### GPU problems

* **Unoptimized assets -** Highly detailed 3D models and high resolution textures will increase the time required to render each frame. It also increases the time it takes to process and upload these assets to the GPU. Therefore, try to optimize these assets before importing them to Hology by lowering resolution of textures and using lowest acceptable compression quality.
* **Draw calls** - The amount of calls to render objects can reduces the workload for the GPU. The GPU works most efficiently if it can do a lot of the processing in parallel. This can be improved by reusing the same geometry with instancing or batching. Instancing is done automatically for all static objects added in a scene in Hology. However, objects that are added at runtime will not automatically be instanced for you.
* **Integrated GPU** - If your device is using an integrated GPU, it may not be capable of rendering highly detailed scenes at 60 FPS. If your device has both an integrated and dedicated, make sure to check that it is being used. Your web browser may choose to use the integrated GPU even if you have a dedicated GPU.


# Avoid unnecessary allocations

## Why Avoid Memory Allocations?

JavaScript runs in a garbage-collected environment. That means every time you create a new object such as `new Vector3()`, the runtime allocates memory for it, which itself takes time. Eventually, when it's no longer used, the garbage collector will analyse references and reclaim that memory. This process sounds automatic and helpful (and it is), but frequent allocations and deallocations can cause performance hiccups, especially in real-time graphics applications like games.

In your game, your rendering loop will run 60+ times per second. If you're constantly creating new vectors, matrices, or objects each frame, the garbage collector can kick in often, leading to dropped frames or stuttering animations. To ensure smooth performance, it’s crucial to **reuse objects** and **minimize allocations**, especially inside the render update loop.

## Best Practices for Avoiding Garbage Collection

1\. **Reuse Vector3, Vector2, Matrix4, and other Math Objects**

**Bad:**

```js
function update() {
  const direction = new Vector3().subVectors(target.position, camera.position);
  // ...
}
```

**Good:**

```js
const direction = new Vector3(); // allocate once

function update() {
  direction.subVectors(target.position, camera.position);
  // ...
}
```

> ✅ Allocate once outside the loop and reuse.

**2. Avoid Anonymous Math Expressions in Loops**

Each chained call like `.clone().add()` creates new objects under the hood unless you’re careful.

**Bad:**

```js
function update() {
  const newPos = object.position.clone().add(new Vector3(0, 1, 0));
  // ...
}
```

**Good:**

```js
const newPos = new Vector3()
const up = new Vector3(0, 1, 0);

function update() {
  newPos.copy(object.position).add(up);
  // ...
}
```

> ✅ Prefer `copy()` and `set()` over `clone()` inside tight loops.

***

**3. Use Temporary Scratch Variables**

Keep shared "temp" variables for calculations to avoid repeatedly creating them.

```js
const tempVec3 = new Vector3();
const tempQuat = new Quaternion();
const tempScale = new Vector3();

function updateTransform(object) {
  object.matrixWorld.decompose(tempVec3, tempQuat, tempScale);
  // Reuse tempVec3, tempQuat, tempScale
}
```

***

## Use Chrome DevTools to Monitor Allocations

Use the "Performance" and "Memory" tabs in Chrome DevTools:

* Record a session.
* Look for spikes in JS heap or GC pauses.
* Hover over memory allocations to see what’s triggering them.


# Target slower devices

Your computer is likely faster than what players of your games are using, especially if they are on mobile devices like smartphones and tablets. As you add more and more features to your game over time, it is likely going to require more CPU. It is therefore useful to enable CPU throttling when testing your game to ensure that it runs smoothly even on slower devices.

In Chrome Dev Tools, go to Performance, then expand using the cog wheel on the right to show the CPU throttle options. The amount that is useful to throttle will depend on your own device so it can be best to re-calibrate so you can select a mid or low-tier mobile setting.

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2Fgit-blob-b7ad324f1d59d6f26cc004f5d5d8d21dba80bfbc%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>


# Introduction to shaders

Everything rendered on the screen needs shaders. Shaders are small programmes that run on the GPU (graphics processing unit) very efficiently. These programmes calculate both the position of geometry vertices on the screen and the color of each fragment.

## When do you need custom shaders?

For some visual styles, you may not need to to create your own shaders. Built in shaders support basic functionality like projecting vertices to screen space, configuring a specific color, texture, while also calculating how lights affect the color.

However, when this is not enough, you may have to create your own shaders. Some examples

* **Vertex animation:** You can transform the position of the geometry's vertices. This can be done to make an object spin around an axis or make foliage look like it is swaying in wind. As this happens on the GPU, it is very efficient as opposed to doing this on the CPU.
* **Mixing materials:** A mesh can only have one material rendered at a time. If you want to display different materials on different parts of a mesh, you can use a custom shader. You can for example use the angle of the surface to decide which color to render.


# Creating shaders

Shaders are created by defining TypeScript classes. The class can receive parameters and should return an instance of a material. The class should inherit from a base class such as Shader or NodeShader and override a specific method in each.

## Creating a shader class

Shaders can be written in either Typescript or GLSL.

### Using Typescript

To write a shader with typescript, extend from NodeShader and override the output method.

```typescript

import { rgb, standardMaterial } from "@hology/core/shader-nodes";
import { NodeShader, NodeShaderOutput, Parameter } from "@hology/core/shader/shader";
import { Color } from "three";

export class ExampleShader extends NodeShader {
  @Parameter()
  color: Color = new Color(0xff0000)

  output(): NodeShaderOutput {
    return {
      color: standardMaterial({color: rgb(this.color)})
    }
  }
}
```

### Using GLSL

To create a shader with GLSL, extend from the Shader class and override the build method, returning a new shader material.

```typescript
import { Shader } from "@hology/core/shader/shader";
import { Color, ShaderMaterial, Material } from "three";

export class MyShader extends Shader {
  
  build(): Material {
    return new ShaderMaterial({
      vertexShader: `
        void main() {
          gl_Position = projectionMatrix * modelViewMatrix * vec4( position, 1.0 );
        }
      `,
      fragmentShader: `
        void main() {
          gl_FragColor = vec4(1., 0., 0., 1.);
        }
      `
    })
  }
}
```

## Exporting shaders

For shaders to be available in the editor, shaders have to be exported in the **index.ts** file in a configured directory.

```typescript
import { ExampleShader } from './example-shader';
import { MyShader } from './my-shader';

export default {
  ExampleShader,
  MyShader,
}
```

The folder in which this **index.ts** file is, should be configured in the **hology.config.json** file in the root of your project's directory.

## When to use Typescript or GLSL

While you could achive the same thing directly with GLSL as in Typescript, it may require significantly more code. With typescript, it is much easier to reuse code. In the above example, we use \`standardMaterial()\` which adds light calculations to your color which otherwise is non-trivial to calculate on your own.

GLSL could be useful if your material doesn't require light calculations and your are more familiar with GLSL or already have code snippets you want to reuse.

Using the node based approach with Typescript is more common in Hology Engine and tutorials.


# Shader parameters

Shader parameters are properties on the shader class that you can set in the editor for materials created using the shader. This allows you to customize the shader's appearance from the editor and reuse the code for different materials

Parameters can be created by adding the `@Parameter()` decorator on a property in your actor class. The type of the parameter will be inferred by your property's type annotation.

The example below shows all currently supported types.

```typescript
import { rgb, standardMaterial } from "@hology/core/shader-nodes";
import { NodeShader, NodeShaderOutput, Parameter } from "@hology/core/shader/shader";
import { Color, Vector2, Vector3, Color, Euler } from "three";

export class ExampleShader extends NodeShader {
    @Parameter() color: Color = new Color(0xff0000)
    @Parameter() aNumber: number
    @Parameter() aBoolen: boolean
    @Parameter() aString: string
    @Parameter() vec2: Vector2
    @Parameter() vec3: Vector3
    @Parameter() color: Color
    @Parameter() rotation: Euler

    output(): NodeShaderOutput {
        return {
            color: standardMaterial({color: rgb(this.color)})
        }
    }
}
```


# Typescript shaders

With Hology Engine, you can write your shaders directly in Typescript, the same programming languages as the rest of your game play code. You can express any logic that you can do in a lower level language as GLSL while enjoying the benefits of using a higher level language like Typescript.

Internally, typescript code will build up a graph of nodes representing the calculations, which explains the use of the word node. These nodes are then converted to the code that is compiled to run on the GPU so it has no negative effect on performance.

See [Creating shaders](https://docs.hology.app/shaders/creating-shaders) for how to create a new Typescript shaders that can be used to create materials in the editor.

You can also use this shader library to create shaders for materials that are created directly in code instead of in the editor.

```typescript
import { rgb, standardMaterial, translateY, sin, float, NodeShaderMaterial, timeUniforms } from "@hology/core/shader-nodes"
import { SphereGeometry, Mesh } from "three"


const time = timeUniforms.elapsed
const diffuse = rgb(0x00ff00)
const color = standardMaterial({ color: diffuse })
const bounce = translateY(sin(time.multiply(float(5))))

const material = new NodeShaderMaterial({
  color,
  transform: bounce
})

const sphere = new SphereGeometry(5, 30, 15)
const mesh = new Mesh(sphere, material)
```


# Types

Types are referred to with classes such as `FloatNode`, `Vec3Node`, `Mat4Node`, etc. Although these can be instantiated, a nicer way that is less verbose making it easier to read and more similar to GLSL syntax is to use their respective creator functions `float` or `vec3` as will be illustrated for each type below.

These types have methods to support logical and arithmetic operators in GLSL such as `+ - / * && ||`. Typescript types ensure that you can not not for example multiply a 3-component vector with a 4x4 matrix so you can quickly discover bugs in your code.

### Scalar

#### Boolean

```ts
const aBool: BooleanNode = bool(true)
```

```ts
.or(other: BooleanNode): BooleanNode
.and(other: BooleanNode): BooleanNode
```

#### Float

```ts
const aFloat: FloatNode = float(.5)
const bFloat: FloatNode = float(aFloat)
```

```ts
.add(other: FloatNode): FloatNode
.subtract(other: FloatNode): FloatNode
.divide(other: FloatNode): FloatNode
.multiply(other: FloatNode): FloatNode
.multiplyVec2(other: Vec2Node): Vec2Node
.multiplyVec3(other: Vec3Node): Vec3Node
.multiplyVec4(other: Vec4Node): Vec4Node
.gt(other: FloatNode): BooleanNode
.lt(other: FloatNode): BooleanNode
.gte(other: FloatNode): BooleanNode
.lte(other: FloatNode): BooleanNode
.equals(other: FloatNode): BooleanNode
.notEquals(other: FloatNode): BooleanNode
```

#### Integer

```ts
const aInt: IntNode = int(5)
const bInt: IntNode = int(aInt)
```

```ts
.add(other: IntNode): IntNode
.subtract(other: IntNode): IntNode
.multiply(other: IntNode): IntNode
.gt(other: IntNode): BooleanNode
.lt(other: IntNode): BooleanNode
.gte(other: IntNode): BooleanNode
.lte(other: IntNode): BooleanNode
.equals(other: IntNode): BooleanNode
.notEquals(other: IntNode): BooleanNode
```

### Vectors

#### 2-component floating point vector

```ts
const aVec = vec2(0.5, 1)
const bVec = vec2(THREE.Vector2(0.5, 1))
const cVec = vec2(THREE.Vector3(0.5, 1, 0.2))
const dVec = vec2(THREE.Vector4(0.5, 1, 0.2, 0.8))
const eVec = vec2(vec3(1,1,1))
const fVec = vec2(vec4(1,1,1,1))
```

There are multiple ways of defining a vector.

* Provide constant values
* Use a ThreeJS vector class. Only the first components will be used.
* Use a higher dimensional vector node and only the first components will be used.

```ts
.x: FloatNode
.y: FloatNode
.subtractScalar(other: FloatNode): Vec2Node
.subtract(other: Vec2Node): Vec2Node
.addScalar(other: FloatNode): Vec2Node
.add(other: Vec2Node): Vec2Node
.divideScalar(other: FloatNode): Vec2Node
.divide(other: Vec2Node): Vec2Node
.multiplyScalar(other: FloatNode): Vec2Node
.multiply(other: Vec2Node): Vec2Node
.multiplyMat(other: Mat2Node): Vec2Node
.equals(other: Vec2Node): BooleanNode
.notEquals(other: Vec2Node): BooleanNode
```

#### 3 and 4-component floating point vectors

The higher dimensional vectors have the same functionality as a 2-component vector as described above. Their individual components can be extracted with `.x`, `.y`, `.z`, and `.w` for their respective first, second, third and fourth components.

These also have additional methods beyond their equivalents of Vec2Node.

```ts
// Additional Vec3Node properties
.xy: Vec2Node
.xz: Vec2Node
.yz: Vec2Node
.rgb: RgbNode

// Additional Vec4Node properties
.xy: Vec2Node
.xyz: Vec3Node
.rgb: RgbNode
.rgba: RgbaNode
```

### Colors

Colors are represented using the types `RgbNode` and `RgbaNode`, where the latter has an alpha component for transparency. These inherit from Vec3Node and Vec4Node respectively so any RgbNode or RgbaNode is a valid Vec3Node or Vec4Node. The reason for this is to make the code easier to understand as it makes it clear what is supposed to represent a color. These types also have methods for extracting the RGBA components which are just wrapping the methods to extract XYZW components from the vector parent class.

#### RGB

The color can be passed in as a hexadecimal value, string or a [THREE.Color](https://threejs.org/docs/#api/en/math/Color) instance.

```ts
const aColor = rgb(0x00ff00)
const bColor = rgb("#00ff00")
const cColor = rgb(THREE.Color(0x00ff00))
```

#### Color with transparency

```ts
const aColor = rgba(0x00ff00)
const bColor = rgba(0x00ff00, 0.5)
const cColor = rgba(0x00ff00, float(0.5))
const dColor = rgba(vec3(0, 1.0, 0.0))
const eColor = rgba(vec4(0, 1.0, 0.0, 1.0))
```

* A Vec3Node or RgbNode can be used to represent the color for `rgba`.
* A Vec4Node can be used to represent the color and transparency for `rgba`.
* The transparency (alpha channel) can be defined by a constant number
* The transparency can also be defined with a FloatNode instance which can be used to control the transparency programaticaly.

### Matrices

At the moment, no creator methods exist beyond the constructors of the matrix type node implementations. Most of the time, you don't instantiate these yourself but instead get them from uniforms or attributes.

#### 2x2 floating point matrix

```ts
const aMat = new ConstantMat2Node(
    1, 2, 
    3, 4)
const bMat = new ComponentsMat2Node(
    float(1), float(2), 
    float(3), float(4)
)
```

#### 3x3 floating point matrix

```ts
const aMat = new ConstantMat3Node(
    1, 2, 3,
    4, 5, 6,
    7, 8, 9
)
const bMat = new ComponentsMat3Node(
    float(0), float(0), float(1), 
    float(0), float(0), float(1), 
    float(0), float(0), float(1)
)
```

#### 4x4 floating point matrix

```ts
const aMat = new ConstantMat4Node(
    1, 0, 0, 0,
    0, 1, 0, 0,
    0, 0, 1, 0,
    0, 0, 0, 0,
)
const bMat = new ComponentsMat4Node(float(1), ...)
const cMat = new ConstantMat4Node(THREE.Matrix4(1, ...))
```

```ts
.add(other: Mat4Node): Mat4Node
.subtract(other: Mat4Node): Mat4Node
.divideScalar(other: FloatNode): Mat4Node
.multiplyScalar(other: FloatNode): Mat4Node
.multiplyVec(other: Vec4Node): Vec4Node
.multiply(other: Mat4Node): Mat4Node
.equals(other: Mat4Node): BooleanNode
.notEquals(other: Mat4Node): BooleanNode
```


# Math functions

Beyond the functions defined on the numeric types, there are other methods which works on most types. These are wrapping functions defined in the GLSL standard library. This page does not describe what each method does. Please see [GLSL documentation](https://www.shaderific.com/glsl-functions) to learn what they do if it is not clear by their signature.

Import functions like this:

```ts
import { dot, radians, saturate } from "@hology/core/shader-nodes"

```

### Trigonometry functions

```ts
radians<T extends FloatNode | Vec2Node | Vec3Node | Vec4Node>(x: T): T
degrees<T extends FloatNode | Vec2Node | Vec3Node | Vec4Node>(x: T): T
sin<T extends FloatNode | Vec2Node | Vec3Node | Vec4Node>(x: T): T
cos<T extends FloatNode | Vec2Node | Vec3Node | Vec4Node>(x: T): T
tan<T extends FloatNode | Vec2Node | Vec3Node | Vec4Node>(x: T): T
asin<T extends FloatNode | Vec2Node | Vec3Node | Vec4Node>(x: T): T
acos<T extends FloatNode | Vec2Node | Vec3Node | Vec4Node>(x: T): T
atan<T extends FloatNode | Vec2Node | Vec3Node | Vec4Node>(yOverX: T): T
```

### Exponential functions

```ts
exp<T extends FloatNode | Vec2Node | Vec3Node | Vec4Node>(x: T): T
log<T extends FloatNode | Vec2Node | Vec3Node | Vec4Node>(x: T): T
exp2<T extends FloatNode | Vec2Node | Vec3Node | Vec4Node>(x: T): T
log2<T extends FloatNode | Vec2Node | Vec3Node | Vec4Node>(x: T): T
sqrt<T extends FloatNode | Vec2Node | Vec3Node | Vec4Node>(x: T): T
inversesqrt<T extends FloatNode | Vec2Node | Vec3Node | Vec4Node>(x: T): T
pow<T extends FloatNode | Vec2Node | Vec3Node | Vec4Node>(x: T, y: T): T
```

### Geometric functions

```ts
length<T extends FloatNode | Vec2Node | Vec3Node | Vec4Node>(x: T): FloatNode
normalize<T extends FloatNode | Vec2Node | Vec3Node | Vec4Node>(x: T): T
```

### Common functions

```ts
abs<T extends FloatNode | Vec2Node | Vec3Node | Vec4Node>(x: T): T
sign<T extends FloatNode | Vec2Node | Vec3Node | Vec4Node>(x: T): T
floor<T extends FloatNode | Vec2Node | Vec3Node | Vec4Node>(x: T): T
fract<T extends FloatNode | Vec2Node | Vec3Node | Vec4Node>(x: T): T
ceil<T extends FloatNode | Vec2Node | Vec3Node | Vec4Node>(x: T): T

mix<
  T extends FloatNode | Vec2Node | Vec3Node | Vec4Node,
  U extends T | FloatNode
>(x: T, y: T, a: U): T

step<
  T extends FloatNode | Vec2Node | Vec3Node | Vec4Node,
  U extends T | FloatNode
>(edge: U, x: T): T

smoothstep<
  T extends FloatNode | Vec2Node | Vec3Node | Vec4Node,
  U extends T | FloatNode
>(edge0: U, edge1: U, x: T): T

clamp<
  T extends FloatNode | Vec2Node | Vec3Node | Vec4Node,
  U extends T | FloatNode
>(x: T, minVal: U, maxVal: U): T

saturate<T extends FloatNode | Vec2Node | Vec3Node | Vec4Node>(a: T): T
```

### Vector functions

```ts
dot<T extends FloatNode | Vec2Node | Vec3Node | Vec4Node>(x: T, y: T): FloatNode
```

### Matrix functions

```ts
inverse<T extends Mat2Node | Mat3Node | Mat4Node>(x: T): T
transpose<T extends Mat2Node | Mat3Node | Mat4Node>(x: T): T
```


# Attributes

Attributes contain information for each vertex.

In order to use attribute information for calculating the color, they have to first be made varying. See the the guide on [Varying](https://docs.hology.app/shaders/typescript-shaders/varying) for how to do this.

#### Predefined

ThreeJS provides data for each vertex for position, uv, and normal. These can be accessed from the common attributes object.

```ts
import { attributes } from "@hology/core/shader-nodes"

const uv: Vec2Node = attributes.uv
const position: Vec3Node = attributes.position
const normal: Vec3Node = attributes.normal

```

#### Transformed value helpers

If a vertex transformation is included in the material, then the attributes passed in to the shaders for each vertex are often less useful. Use these values to refer to the position and normal after vertex transformations. Usually you always want to use these to calculate the amount of light reflected from a surface.

```ts
import { transformed } from "@hology/core/shader-nodes"

const position: Vec4Node = transformed.position // After applying vertex transform
const mvPosition: Vec4Node = transformed.mvPosition // After applying vertex transform and the model view matrix
const normal: Vec3Node = transformed.normal // Recalculated normal after applying the vertex transform
```

#### Custom attributes

You can also define your own attributes with attribute node classes.

```ts
import { AttributeVec3Node, Vec3Node } from "@hology/core/shader-nodes"
import { BoxGeometry } from 'three'


const customAttribute: Vec3Node = new AttributeVec3Node('myCustomAttribute')

const customAttributeValues = new Float32Array([
   1, 1, 1,
   1, 1, 1,
   ...
])

const geometry = new BoxGeometry(1,1,1)
geometry.setAttribute('myCustomAttribute', new THREE.BufferAttribute(customAttributeValues, 3));
```

The following classes exist to define your own attributes and the only constructor argument is the name of the attribute as it is defined when calling `setAttribute` on a [THREE.BufferGeometry](https://threejs.org/docs/#api/en/core/BufferGeometry).

```ts
AttributeFloatNode
AttributeVec2Node
AttributeVec3Node
AttributeVec4Node
AttributeMat2Node
AttributeMat3Node
AttributeMat4Node
AttributeRgbNode
AttributeRgbaNode
```


# Varying

In order to use information in each fragment of a triangle that exists on the vertex level, this information needs to be interpolated between the vertices. The variable referred to at a specific fragment needs to be interpolated for that fragment's position based on the the value at each of the triangle's vertices and the fragment's offset from those vertices. In order for this information to be available, they need to be passed in as "varying" variables to the fragment shader. This is done by wrapping the value in call to a special function defined for each type as illustrated below.

```ts
import { float, varyingVec2, attributes } from "@hology/core/shader-nodes"

const coord: Vec2Node = varyingVec2(attributes.uv)

// coord can now be used to lookup a color from a texture on each fragment
```

#### Functions

```ts
varyingFloat(n: FloatNode): FloatNode
varyingVec2(n: Vec2Node): Vec2Node
varyingVec3(n: Vec3Node): Vec3Node
varyingVec4(n: Vec4Node): Vec4Node
varyingMat2(n: Mat2Node): Mat2Node
varyingMat3(n: Mat3Node): Mat3Node
varyingMat4(n: Mat4Node): Mat4Node
```

#### When you must use varyings

If you try to use a value that only exists in the vertex shader, you will get an error that you are referring to something undefined. This is easily fixed by wrapping it in a varying call but it is useful to know when this would happen. These are the scenarios in which you have to define a varying:

* You are referring to attributes such as position, uv, normal as this information only exist per vertex and has to be interpolated for each fragment in order to affect the color calculation.
* You have defined a value which is used both in a vertex transformation and the color.


# Uniforms

Uniforms are used to pass in information to the shader at runtime.

### Creating uniforms

A uniform can be defined with a given key that later can be used to define the default value and to update the uniform on the instance of a material.

```ts
import { uniformFloat, float, sin, translateY } from "@hology/core/shader-nodes"

const uniformTime = uniformFloat("time")

const material = new NodeShaderMaterial({
  color: rgba(0x00ff00, sin(uniformTime).multiply(float(0.5)).add(float(0.5)),
  transform: translateY(sin(uniformTime.multiply(float(5)))),
  uniforms: {
    time: { value: 0 }
  }
})
```

You can update the uniform value just like you would for ShaderMaterial in Three.js.

```ts
material.uniforms.time.value = clock.getElapsedTime()
```

These are some helper methods to create uniforms for common types. Note that you can also pass in a default value to most uniform type when defining the uniform.

```ts
uniformBool(name: string, value?: boolean): BoolNode
uniformFloat(name: string, value?: number): FloatNode
uniformVec2(name: string, value?: Vector2): Vec2Node
uniformVec3(name: string, value?: Vector3): Vec3Node
uniformVec4(name: string, value?: Vector4): Vec4Node
uniformMat2(name: string, value?: Matrix2): Mat2Node
uniformMat3(name: string, value?: Matrix3): Mat3Node
uniformMat4(name: string, value?: Matrix4): Mat4Node
uniformSampler2d(name: string): Sampler2dNode
```

#### Uniform arrays

Uniform arrays requires in addition to the name of the uniform the type it should contain and an IntNode to represent the size of the array which needs to be known at compile time.

The example below illustrates how to refer to the directional shadow matrix uniform provided by ThreeJS. In this case, the number of elements is provided with a defined constant `NUM_DIR_LIGHT_SHADOWS`.

```ts
import { UniformArrayNode, IntExpressionNode, Mat4Node } from "@hology/core/shader-nodes"

export const uniformDirectionalShadowMatrix = new UniformArrayNode(
  'directionalShadowMatrix',
  Mat4Node,
  new IntExpressionNode('NUM_DIR_LIGHT_SHADOWS')
);
```

**Uniform struct arrays**

Structs exist in GLSL but are normally not necessary when using this library as regular JavaScript objects and classes can do their job. However, when passing an array of a struct type to the shader, the struct needs to be defined.

The example below illustrates how this can be done to create a struct for the DirectionalLight type.

```ts
import { StructType }  from "@hology/core/shader-nodes"

abstract class DirectionalLight extends StructType {
  static readonly typeName = 'DirectionalLight';
  readonly direction = this.get(Vec3Node, 'direction');
  readonly color = this.get(RgbNode, 'color');
}
```

* A struct should be defined as an abstract class.
* It must have its name defined using a static property named `typeName`. This does not need to match the class name.
* All properties must be defined with a call to `this.get(type, name)`

The class is abstract as you should not try to instantiate it on your own. Internally, a subclass will be defined during the build process of the shader and passed to array methods.

With this struct defined, it can now be used to create a uniform struct array.

```ts
const uniformDirectionalLights: ArrayNode<DirectionalLight> = new UniformArrayNode(
    'directionalLights', 
    DirectionalLight,
    new IntExpressionNode('NUM_DIR_LIGHTS')
);
```

### Predefined

#### Camera and model

Three.js provides uniforms documented [here](https://threejs.org/docs/#api/en/renderers/webgl/WebGLProgram).

```ts
import { uniforms }  from "@hology/core/shader-nodes"

uniforms.modelMatrix // Mat4Node 
uniforms.modelViewMatrix // Mat4Node
uniforms.projectionMatrix // Mat4Node
uniforms.viewMatrix // Mat4Node
uniforms.normalMatrix // Mat3Node
uniforms.cameraPosition // Vec3Node
```

#### Time

The time uniforms can be useful to animate colors or vertex transforms.

<pre class="language-typescript"><code class="lang-typescript"><strong>import { timeUniforms } from "@hology/core/shader-nodes"
</strong>
timeUniforms.elapsed // FloatNode - Time in seconds. 
</code></pre>

#### Particles

```typescript
import { particleUniforms } from "@hology/core/shader-nodes"

particleUniforms.energy // FloatNode - A value going from 1 to 0 over the lifetime of the particle
particleUniforms.velocity // Vec3Node - The velocity of the particle 
```

#### Depth

The depth uniforms can be used to get the depth behind a fragment on a triangle to the geometry behind it. This can be useful create create effects like water where the edges are more translucent.

```typescript
import { fragmentLinearEyeDepth, linearEyeDepth } from "@hology/core/shader-nodes";

const depth = linearEyeDepth.subtract(fragmentLinearEyeDepth).divide(linearEyeDepth)
```

#### Lights and shadows

The following uniforms are provided in case you want to implement your own lighting shaders.

```ts
import {
    uniformPointLights,
    uniformHemisphereLights,
    uniformDirectionalLights,
    uniformAmbient,
    uniformReceiveShadow,
    uniformDirectionalLightShadows,
    uniformDirectionalShadowMap,
    uniformDirectionalShadowMatrix 
}  from "@hology/core/shader-nodes"

uniformPointLights // ArrayNode<PointLight>
uniformHemisphereLights // ArrayNode<HemisphereLight>
uniformDirectionalLights // ArrayNode<DirectionalLight>
uniformAmbient // Vec3Node
uniformReceiveShadow // Boolean
uniformDirectionalLightShadows // ArrayNode<DirectionalLightShadow>
uniformDirectionalShadowMap // ArrayNode<Sampler2DNode>
uniformDirectionalShadowMatrix // ArrayNode<Mat4Node>
```


# Textures

In order to use a texture as the color, the texture data needs to be provided as a uniform to the shader and the color needs to be sampled from the texture on each fragment.

```ts
import { texture2d, uniformSampler2d, float, varyingVec2, Sampler2D, Vec2Node, attributes }  from "@hology/core/shader-nodes"
import * as THREE from 'three'

const sampler: Sampler2D = uniformSampler2d('image')
const coord: Vec2Node = varyingVec2(attributes.uv)
const color: RgbaNode = texture2d(sampler, coord)

const texture = new THREE.TextureLoader().load( "path/to/texture.jpg" )

const material = new NodeShaderMaterial({
    color: color,
    uniforms: { image: { value: texture } }
})
```

If the texture is already available when creating the shader such as when it is passed in to a shader material via a parameter, then you can use the `textureSampler2d` function to create a sampler. By passing in the texture directly to this function, the texture does not also need to be added as a uniform.

```typescript
import { texture2d, textureSampler2d, float, varyingVec2, Sampler2D, Vec2Node, attributes }  from "@hology/core/shader-nodes"
import * as THREE from 'three'

const texture = new THREE.TextureLoader().load( "path/to/texture.jpg" )

const sampler: Sampler2D = textureSampler2d(texture)
const coord: Vec2Node = varyingVec2(attributes.uv)
const color: RgbaNode = sampler.sample(coord)

const material = new NodeShaderMaterial({
    color: color
})
```


# Arrays

Arrays are especially useful when passing in data to a shader as a uniform and this is currently the only way to create arrays unless you create your own node that outputs an array. [See the how pass in an array of uniforms](https://github.com/adamringhede/three-shader-graph/wiki/Uniforms#uniform-arrays).

### Using arrays

#### Map

An array can be mapped into another array by providing a mapping function.

```ts
const doubledNumbers: ArrayNode<FloatNode> = numbers.map((value: FloatNode) => {
    return value.multiply(float(2))
})
```

#### Sum

An array can be reduced to a single value by providing a function that applies some transformation before summing the values. The return type of the mapping function must be numeric.

```ts
const doubledSum: FloatNode = numbers.sum((value: FloatNode) => {
    return value.multiply(float(2))
})
```

#### Get element by index

```ts
array.get(0) // Using a constant
array.get(int(0)) // Using an IntNode to pick an element programatically
```


# Select

In GLSL, you have both if statements and the ternary operator in order to be able to evaluate which of two expressions should be used. This can be achieved using the `select` function which works like a ternary operator.

```ts

const aboveZero: BooleanNode = attributes.position.y().gt(float(0))
const displacement: FloatNode = select(
    // condition
    aboveZero, 
    // if it is true
    pow(attributes.position.y(), 2), 
    // if it is false
    float(0) 
)

```

The condition must be of type `BooleanNode` and the values need to be of the same type.


# Lighting

Lighting is an important and non trivial part of creating shaders.

### Built in

The library comes with some built in implementations of materials.

#### Lambert

The Lambert material implementation is highly efficient as it only calculated the light at each vertex. It can take a diffuse color and returns an RgbaNode.

```ts
import { lambertMaterial, RgbaNode, rgb } from "@hology/core/shader-nodes"

const color: RgbaNode = lambertMaterial(rgb(0x00ff00))
```

#### Standard

The standard material is based on a physically based rendering approach and looks just like [THREE.MeshStandardMaterial](https://threejs.org/docs/#api/en/materials/MeshStandardMaterial) except it that it does not have features like metalness or refraction.

```ts
import { standardMaterial, RgbaNode, rgb } from "@hology/core/shader-nodes"

const color: RgbaNode = standardMaterial({ 
    color: rgb(0x00ff00), 
    emissive: rgb(0x9f7070), 
    emissiveIntensity: float(0),
    roughness: float(1)
})
```

### Creating your own

Light and shadow information is passed in by ThreeJS based on what exists in the scene and you can access them with uniforms. Check out the / for what predefined uniforms exist and for how to create new ones if some you need are missing.


# Internals of nodes

This page describes how nodes are created so that you can understand what goes on internally or to create new nodes yourself using GLSL. Given that Hology's Typescript shaders already has support for all GLSL features, you normally don't need to create your own nodes like this.

#### Structure of a node implementation

The class name (NODE\_NAME) can be anything you want and the parent class (BASE\_TYPE) is usually one of the built in types like FloatNode, Vec3Node, etc.

```ts
export class NODE_NAME extends BASE_TYPE {
  // Other nodes can be passed into the constructor.
  constructor(private diffuseColor: RgbNode) {
    super();
  }
  public compile(c: Compiler) {
    // Generate an incrementing number to use in variables. It helps with creating unique variables and makes it easier to debug generated code. 
    const k = c.variable() 
    // Extract the output of an input. This can now be inserted in the GLSL code below. 
    const diffuseColor: string = c.get(this.diffuseColor)
    
    return {
        // Code that exist outside the main function such as uniforms, structs and functions. This is optional.
       pars: `

       `,
       // Code that exist inside the main function. This is optional as the `out` can contain an expression. 
       // However, to avoid reevaluating the expression every time, assign it to a variable here and just refer to the variable in `out`. 
       chunk: `
          vec3 color_${k} = ${diffuseColor};
       `,
       // `out` should be a GLSL expression, which usually is one variable defined in the `chunk` above.
       out: `color_${k}`
    }
  }
}
```


# Scene color

You can access the color in the scene behind object for certain effects like screen space refraction. This is especially useful in visual effects to create the effects like shockwaves or heat distortion.

The code below shows how we can get the color from the scene behind the fragment we render. By using the screenUV coordinate, we get the color immediately behind the object from the direction of the camera. If we output this color, the object would appear completely transparent.

```typescript
import { sampleSceneColor, screenUV, RgbaNode } from "@hology/core/shader-nodes";

const color: RgbaNode = sampleSceneColor(screenUV)
```

To create various effects like heat distortions of shockwaves, you would simply add an offset to this coordinate which is demonstrated in the example below.

## Example - Shockwave sprite

We can create the effect shown in the image below using a sprite and sample the color behind it with an animated offset.

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2Fgit-blob-0b19eb926f8690f1444b22e3c22b3956ad20201e%2Fimage%20(2).png?alt=media" alt=""><figcaption></figcaption></figure>

```typescript

import { SpriteNodeShader } from '@hology/core';
import { distance, normalize, oneMinus, particleUniforms, sampleSceneColor, screenUV, sin, smoothstep, timeUniforms, varyingAttributes, vec2 } from "@hology/core/shader-nodes";
import { NodeShaderOutput, Parameter } from "@hology/core/shader/shader";

export default class ShockwaveShader extends SpriteNodeShader {

  @Parameter()
  distortionStrength: number = 0.05
  
  @Parameter() 
  waveScale: number = 20

  @Parameter()
  waveSpeed: number = 0.2

  @Parameter()
  fadeDistance: number = 0.1
  

  output(): NodeShaderOutput {

    const center = vec2(0.5)
    const dir = normalize(varyingAttributes.uv.subtract(center))
    const dist = distance(varyingAttributes.uv, center)
    
    const alpha = smoothstep(0.5, 0.5 + this.fadeDistance, oneMinus(dist))

    const wave = sin(
      dist.subtract(timeUniforms.elapsed.multiply(this.waveSpeed)).multiply(this.waveScale)
    ).multiply(this.distortionStrength).multiply(alpha)

    const offset = dir.multiplyScalar(wave)

    const sample = sampleSceneColor(screenUV.add(offset)).rgb
    
    return {
      color: sample.rgba(alpha.multiply(particleUniforms.opacity)),
      transparent: false
    }
  } 
}

```


# Painted materials

Creating custom shaders to support painted materials

Objects like landscapes normally have variation in the ground like some parts are grassy, some might be sand and maybe a dirt road. This requires two things

1. Painted weights on an object such as a landscape
2. A material using a custom shader that can use these painted weights

### What are painted weights?

When you are using the paint tool in the editor, you are not necessarily painting a color. Instead, as your brush goes over a vertex (a corner of a triangle) on the geometry of the selected object, it will store a "weight" on that vertex as a fractional value between 0 and 1 for the specific painting layer used when painting. This is similar to a feature that exists in 3D editors called *vertex painting*. These weights are then available to shaders to create materials that can use the weights to determine the color of each pixel on the surface.

### Using painted weights in a shader

In order to use the weights, you need to create a custom shader. The easiest way to accomplish this in a custom shader is to use the function `mixColorsByLayer` as shown below.

```typescript

import { LayerMixMode, mixColorsByLayer, rgb, standardMaterial } from "@hology/core/shader-nodes";
import { NodeShader, NodeShaderOutput } from "@hology/core/shader/shader";

export class ExampleShader extends NodeShader {

  output(): NodeShaderOutput {

    const color = mixColorsByLayer({
      layerColors: [
        rgb("#CCCCCC"), // Default color
        rgb("#FF0000"), // Painted layer 1
        rgb("#00FF00"), // Painted layer 2
        rgb("#0000FF"), // Painted layer 3 
      ], 
      enableNoise: true,
      noiseScale: .5,
      noiseAmount: .1,
      mode: LayerMixMode.soft,
      decay: .5,
    })

    return {
      color: standardMaterial({color})
    }
  }
}

export default ExampleShader

```

For each layer in your material, including the bottom (default) layer, you need to assign a color. Colors could be defined as in the example above, or they could be the result of sampling textures and anything else you otherwise can do in shaders.

In the example above, the color created from mixing the painted layers with their assigned colors is passed to the `standardMaterial` function which adds support for lights and shadows on top of your material.

#### Transitions

You also need to decide how to transition between the layers. As the painted weights are stored in the corners of triangles, you don't have a especially high precision for exactly where a color should appear. If your object's geometry has a high triangle density, meaning it has a lot of tiny triangles as opposed to fewer large ones, it will require more processing power to render the object but you could get more control over where the paint goes. Also, uniformly sized and positioned triangles in a grid as on a landscape object will easily make it look unnatural. To handle this, there are several parameters you can use to control how to transition between the layers. This requires knowing what kind of art style you are going for and some experimentation to find values that makes it look the way you want.

* **enableNoise (boolean)** - By adding noise to the transition between layers, you can add some more natural looking edges as opposed to the straight and jagged edges you would otherwise get when the geometry is just triangles.
* **noiseScale (number)** - Control the detail level of the noise.
* **noiseAmount (number)** - A value between 0 and 1 for how much the noise should affect the transition.
* **mode (enum)** - The transition can either be soft or hard.
  * A soft transition will create a gradient between the colors of the layers. For something to look realisitc like in nature, you likely want this.
  * A hard transition on the other hand could be favourable for an art style that is more stylized.
* **decay (number)** - This is only relevant when the mode is soft. It controls the length of the gradient between the two layers.


# Water shader tutorial

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2Fgit-blob-55cd5aed1028f24532708e42e51f8d37a387c319%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

This tutorial will go over how to create a stylized water material using a custom shader. We also have a video tutorial provided at the bottom of this documentation page.&#x20;

## Create a scene

For our scene, to see how our material will look, we need a landscape and a plane. Create the landscape and dig down to create something that looks like a small lake. For the water surface, we can just use a plane and rotate it -90 degrees around the X axis so that it faces up. Scale the plane and move it to cover the hole in the ground while intersecting with the sides like in the image below.

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2Fgit-blob-816ff8f22b3b63a24d294c74e426d8571ab11b40%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

## Create a custom shader class

In the asset browser, click “Add new” and then click “Shader class”. Name it “WaterShader”. If we now open our code base, we should find a file at **src/shaders/water-shader.ts**.

We will need a couple of parameters later so we can define them here. Add the properties "shallowColor" and "normalMap" with the `@Parameter` decorator like in the code below.

```typescript
@Parameter()
shallowColor: Color = new Color()

@Parameter()
normalMap: Texture = new Texture()
```

## Upload a normal map texture

To create the appearance of small waves on top of our flat water surface, we will use a normal map which is an image in which the pixels describe the angle of the surface at that point. Download the image below.

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2Fgit-blob-a1ab4c87a2dc3dc3cf7bf04e0e8dda7eb8ba171d%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

You could also use any other seamless normal map for a different look.

## Create a material

Now that we have the shader parameters declared and the normal map texture asset we need, we can create the material asset. In the asset browser, click "Add new" and then "Material". You can name it "Water".

Configure the material with the following values.

* Type = Custom shader
* Shader = WaterShader
* Side = Front
* Transparent = Yes
* Bloom = No
* Color = #FE9397
* Shallow Color = #05FFB4
* Normal Map = water\_normal

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2Fgit-blob-85241719babc384602279a600d392e687c24afa3%2Fimage.png?alt=media" alt="" width="311"><figcaption></figcaption></figure>

Assign the material to your plane by either dragging the material asset onto the plane or by selecting the material in the object editor panel.

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2Fgit-blob-b978a9adb5d5ed8a9f95c2763ae777d2f6b4ea63%2Fimage%20(16).png?alt=media" alt="" width="274"><figcaption></figcaption></figure>

## Implement the shader

Now that the scene is prepared, we can go back into the shader code. Whenever you make changes to the shader code, it will automatically update the material in the Hology editor. It can therefore be useful to have both the code editor and the Hology editor open side by side.

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2Fgit-blob-313dccf92b071996d77d7dc8f42136da96428449%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

### Depth

To make the water appear more realistic, we want to adjust the color based on the depth, making it look murkier the deeper it is. This can be done using a built in function `edgeDepthEffect(power: number)` . This function will return a number between 0 and 1 where 1 means that the fragment behind the fragment we render is at the same distance from the camera. This can be useful to calculate a different color or opacity where a geometry intersects with another or based on depth. The number given as the argument to the function is an exponent that can be used to create a sharper edge detection. In your shader code, we can replace the content of the output function with the following code. We can output the depth value as the color to see this effect.

```typescript
const depth = edgeDepthEffect(4)

return {
  color: depth
}
```

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2Fgit-blob-2377e9393b51170d83e1966632a0a63f786937ad%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

### Color gradient

With the depth value, we can now easily create a gradient with our two color parameters to render a different color where the water is more shallow. The mix function will calculate a color between the two given colors based on the depth value. As the color parameters are of type `Color`, we need to convert them to RgbNodes using the `rgb()` function.

```typescript
const depth = edgeDepthEffect(4)

const gradient = mix(rgb(this.color), rgb(this.shallowColor), depth)

return {
  color: gradient
}
```

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2Fgit-blob-7e0eda7aeaf38a5f40e469105e09c5f49f2a86ec%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

### Opacity

Water is often transparent so we will adjust the opacity value of the color. To add to the appearance of depth, we will utilize the depth value again so that the water becomes less transparent when it is deeper.

In the code below, the opacity is calculated using 1 minus the depth raised to an exponent that we can tweak to change how much of the edge should be transparent. by using a higher exponent, the transparency will decrease faster as it gets deeper. Then, the gradient color and opacity is combined into and an RgbaNode.

<pre class="language-typescript"><code class="lang-typescript"><strong>const opacity = oneMinus(pow(depth, 1.2))
</strong>
const color = rgba(gradient, opacity)

return {
  color: color
}
</code></pre>

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2Fgit-blob-26561290d09f9b8ae158915257c8511f615d2687%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

### Lighting

The color we are outputing it currently not influenced by lights or shadows. To fix that, the function `standardMaterial` can be used. This function adjusts the given color based on lights in the scene and shadows cast by other objects.

<pre class="language-typescript"><code class="lang-typescript">return {
<strong>    color: standardMaterial({color})
</strong>}
</code></pre>

### Waves

To give the appearance of waves, we will utilize the normal map that was previously imported.

#### World coordinate

To sample our normal map we need to use a coordinate vector with 2 values. While it is common to use the UV values contained in the geometry's vertex for many shaders, in this case that is less favourable. We may want to use this same material for several different water surfaces using planes with different scale. If we use the UV values, this would lead to the image being stretched unless the plane is completely square. Also, we likely want the waves to appear the same size regardless of how large the body of water is.

We can utilize the geometry's vertex position in the world using the built-in `worldPosition` value and extract the x and z components to create a Vec2Node. To make the value interpolate across the surface of the triangle, the function `varying` should be used. This coordinate will allow us to sample the normal map using the fragment's position in the world, independent of how stretches the geometry is.

```typescript
const worldCoord = varying(transformed.worldPosition.xz)
```

#### Animation

We need to sample our normal map while also animating it so that it looks like it is moving. Normally, water will have smaller waves on top of other waves that move independently from the waves underneath. To accomplish this, we need to sample our normal map twice with different coordinates. We will also use the same normal map so we need to adjust the scale of the coordinates to make some waves smaller. You could also achieve this by using a second normal map with a different pattern. We can define a function like below that provides this functionality.

```typescript
function sampleWaveNormal(map: Sampler2DNode, coord: Vec2Node, scale: number, direction: Vec2Node, speed: number) {
  const offset = direction.multiplyScalar(timeUniforms.elapsed.multiply(speed))
  return map.sample(coord.add(offset).multiplyScalar(scale))
}
```

#### Sampling the normal map

To sample the normal map, we first need to create a sampler with the function `textureSampler2d` and pass in our normal map texture parameter.

```typescript
const normalMap = textureSampler2d(this.normalMap)
```

Then we create two samples with different scale, direction and speed values.

```typescript
const normalSample1 = sampleWaveNormal(normalMap, worldCoord, .01, vec2(-.4, .9), 1) 
const normalSample2 = sampleWaveNormal(normalMap, worldCoord, .05, vec2(.5, .2), .4)
```

The samples are mixed together evenly and the function `colorToNormal` is used to convert the color value provided by the normal maps to a normal that we can use for light calculations. The last argument to this function can be used to adjust the `normalScale` to increase or decrease the height of the waves.

```typescript
const normal = colorToNormal(mix(normalSample1, normalSample2, .5), 1)
```

Finally, we add this normal value to the `standardMaterial` function. To see the light shimmer on the water we need to also adjust the roughness value to a small number. You may need to move the camera around in the editor to see this effect.

```typescript
return {
  color: standardMaterial({color, normal, roughness: 0.15})
}
```

Bringing this all together, we now have a simple stylized water material.

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2Fgit-blob-32a63cedbf033707a71d3eaad062fc57ae6a6303%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

To learn more about creating shaders with Typescript in Hology Engine, see our other articles on [Typescript shaders](https://docs.hology.app/shaders/typescript-shaders)

You can also check out our video tutorial on water shader below

{% embed url="<https://youtu.be/2iXnr5yAdhc?si=-x4_Y-1UI5QWqhJg>" %}


# Landscape sculpting

{% embed url="<https://youtu.be/zEsLag1muB0?si=4aNornZZt1pD3v03>" %}

Our landscape sculpting tool can help you mold mountains, carve valleys, and smooth rolling hills into existence.&#x20;

{% hint style="info" %}
Landscape sculpting is currently an experimental feature. It is missing many features that would help with user experience. There may be performance problems and other bugs.
{% endhint %}

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2Fgit-blob-42804a2612ff25fb266c3c8615e18f7d181a3eda%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

## Creating a landscape

1. In the asset browser, click on the Shapes category (top left highlighted in yellow in the image below).
2. Find Landscape in the asset browser (highlighted in yellow in the browser), and drag and drop it into the scene.&#x20;

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2FRZliqS54XTGQ5vKwa5Vc%2FScreenshot%202026-03-07%20180217.png?alt=media&amp;token=2c9a21c7-49e8-4fe7-b7c0-8c709c565306" alt=""><figcaption></figcaption></figure>

### Configuring a landscape

When adding it, you will be have the option to change some parameters for the landscape before it is created. Currently, these can't be changed after the landscape is created. So you may want to try out various options for the landscape before you commit to a landscape to start sculpting.

* **Section size** - The size of each section in meters per side. Sections are square.
* **Resolution**- The number of rows and columns across each section. A higher number increases the amount of triangles rendered, which will make it look smoother but will require more processing to render and sculpt. Use a value as small as possible while still looking good enough.
* **Sections** - The number of sections in the x and z directions. As sections are loaded based on view distance, there is not much of a cost to have a lot of sections. If you are planning on creating a large world, use a lot of sections because you currently can't add more later.

### Multiple landscapes

It is possible to have multiple landscapes in a scene. It can be difficult to create a smooth transition between landscapes so you may want to have a larger single one if you want to create a large open world.

## Sculpting

1. Select the landscape object in your scene.
2. Start the sculpting tool by clicking **L** on your keyboard.
3. Hold your left mouse button and move your mouse for the sculpt tool to affect the landscape.

### Adjusting sculpt tool

* **Size** - Adjust the radius of the sculpt tool to affect a larger area by holding down **F** and move your mouse cursor
* **Strength** - Adjust how much the landscape should be affected by adjusting the strength of the sculpting tool by holding down **Shift+F** and move your mouse cursor.

### Sculpt modifiers

* **Add** - Increase the height of the landscape under the sculpt tool
* **Dig** - Decrease the height of the landscape under the sculpt tool. Hold down **Ctrl** or **Cmd (for Mac)**
* **Smooth** - Reduce hard edges by smoothing parts of the landscapes. Hold down **Shift**
* **Flatten** - Make the landscape more flat under the landscape tool. Hold down **Ctrl** or **Cmd** + **Shift**


# Landscape painting

Landscape painting is a way to define or control how the surface should look. What is important to know is that the painting tool does not paint a specific color. When the paint tool goes over a surface, it will increase or decrease a single numerical value in the corner of each triangle ranging from 0 to 1. This value can then be used by a shader to decide what color to use based on that value. The shader can, for example, mix the colors from two different texture samples based on if this painted vertex value is 0, 1, or something in between.

See [Painted materials](https://docs.hology.app/shaders/painted-materials)for how to create a custom shader that can utilise vertex painted values.

You can also use predetermined materials such as landscape basic or landscape composite for landscape painting.&#x20;

## Landscape basic material

Landscape Basic is a material type designed for applying solid colors to landscapes, ideal for low-poly, toon-shaded, or blockout workflows. It supports up to 8 customizable color channels, allowing you to define clean, stylized surfaces with minimal visual complexity.<br>

1. In the asset browser, select → Add New → select Material. Enter the material name → select Create.

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2FePAiowDQOHhyTvRzQc49%2FScreenshot%202026-03-07%20173000.png?alt=media&amp;token=76e64e2d-24f4-407e-ada3-f1d193fbb6e0" alt=""><figcaption></figcaption></figure>

2. In the materials editor, for Type, pick landscape basic.&#x20;
3. Under the Properties category, you will be able to pick the solid colors you wish to assign. Please make sure to click Save at the bottom of the materials' edit window.&#x20;
4. Click on the landscape in the scene. In the landscape editor under the Materials category, please choose the material you just created.&#x20;

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2Fb0O2YmBB6eOyIpYWsxAm%2FScreenshot%202026-03-08%20000159.png?alt=media&amp;token=af0711f4-0139-4f7c-a8a9-12bb38616975" alt=""><figcaption></figcaption></figure>

2. Now you are ready to start painting! Please scroll down to the "Start painting" section to continue.&#x20;

## Landscape composite material

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2F6P5ceK7MJDxGuE9sgDeO%2FScreenshot%202026-03-07%20233540.png?alt=media&amp;token=7b95fa29-ad39-40eb-98e8-a8019d49befc" alt=""><figcaption></figcaption></figure>

A landscape composite material is a shader material that blends several different textures together across a terrain. It lets you mix things like grass, rock, dirt, and sand in one unified material, instead of assigning a separate material per patch of ground.

1. Drag and drop the texture files (PNG) you wish to use into the asset browser in the engine.&#x20;
2. In the asset browser, select → Add New → select Material. Enter the material name → select Create.
3. In the materials editor, for Type, select landscape composite.&#x20;
4. Under the Properties → find Layers → click + button to add a layer (highlighted yellow in picture below) → select the texture files you wish to use. Please make sure to click Save at the bottom of the materials editor window.&#x20;

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2FH0eNearSEUDeoPwRDhgK%2FScreenshot%202026-03-08%20000538.png?alt=media&amp;token=6147f935-16ac-422d-b181-36db4fa5ff12" alt=""><figcaption></figcaption></figure>

4. Click on the landscape in the scene → in the landscape editor window, find the Materials category → select the material you just created.&#x20;
5. Now you are ready to start painting. Please see below for painting instructions.&#x20;

## Start painting

When the landscape is selected, you can start landscape painting by clicking **P** on your keyboard. The default material used on landscapes will show a blue color. This color is just used to help visualise where you are painting.

### Layers

Multiple values can be stored per vertex in order to be able to mix different ground attributes or to layer different ground materials on top of each other. You can switch which layer you want to paint on using the keyboard shortcuts 1, 2, 3, 4, 5 up to 8

### Falloff

The paint tool has a smooth fall off which means that it will affect the painted layer value of vertices closed to the middle of the affected area than vertices further from the tool.

### Erase paint

Paint values can be decreased or completely erased by holding down **Shift** on your keyboard as you paint.

### Paint radius

The size, or radius, of your paint tool can be changed by holding down **F** on your keyboard and moving your mouse left or right to decrease or increase the size.


# Grass

{% embed url="<https://youtu.be/2dkNeQ10hP4?si=xcrkPTV2I_21vZCu>" %}

On a landscape, you can add foliage using the grass settings. This will scatter a 3D model across a landscape.

### 3D model limitations

This feature is currently limited to work with models that have a single geometry and material. If your model is for example several planes, ensure to combine them to a single geometry before exporting.

## Tutorial

### 1. Import assets

To create grass using this technique, you need both a 3D model and an alpha map texture which we will use in a material later. Download the files below and drag them into your editor.

[grass.glb](https://drive.google.com/file/d/1whgQc8scJyRHOhTRA1zYhSxyG8HEs4Dl/view?usp=drive_link)

[sprite\_0004.png](https://drive.google.com/file/d/1_ouwbD_1HzgnGjHfVnkpGACrOodYpBu-/view?usp=drive_link)

### 2. Create a landscape

In the asset browser, select shapes and find Landscape. Add it to the scene. For the purpose of just learning how to use grass, you can leave the default options.

### 3. Add a grass mesh

1. Select your landscape object in the scene
2. Expand the Grass settings
3. Click add grass layer
4. Click add mesh
5. Right click the imported model and click "Select"

You will now have something that looks like this.

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2Fgit-blob-6e86fbc53553d693d6e4643ace561a392f039381%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

### 4. Create a grass shader

In the asset browser, click add new and then click Shader class. Give the shader the name *GrassShader*.

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2Fgit-blob-4dc53ad7d0761dac9cf6d97ba193d7669ca50858%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

Open the project in your code editor and change the created file called *grass-shader.ts*. Replace the contents of the file with the code below.

```typescript
import { float, mix, rgb, rgba, smoothstep, standardMaterial, textureSampler2d, transformed, varyingAttributes, varyingFloat, vec2 } from "@hology/core/shader-nodes";
import { NodeShader, NodeShaderOutput, Parameter } from "@hology/core/shader/shader";
import { Color, Texture } from "three";

export default class GrassShader extends NodeShader {
  @Parameter()
  color?: Color

  @Parameter()
  colorBottom?: Color

  @Parameter()
  alphaMap?: Texture

  output(): NodeShaderOutput {
    const distanceFromCamera = transformed.mvPosition.z.multiply(float(-1))
    const distanceAlpha = varyingFloat(smoothstep(float(100), float(60) , distanceFromCamera))    

    const tipColor = rgb(this.color ?? 0xffffff)
    
    const gradientColor = mix(
      tipColor,
      rgb(this.colorBottom ?? 0x000000),
      varyingAttributes.uv.y
    )

    const alpha = this.alphaMap != null 
      ? textureSampler2d(this.alphaMap).sample(varyingAttributes.uv.multiply(vec2(1, -1))).r
      : float(1)

    const litColor = standardMaterial({color: gradientColor}).rgb

    return {
      color: rgba(litColor, alpha.multiply(distanceAlpha)),
      alphaTest: 0.8
    }
  }
}

```

### 5. Create a grass blades material

In the asset browser, click "Add new" and this time select "Material". You can name it "GrassBlades".

1. Select type Custom shader
2. Set Side to Double.
3. Select the shader you created in the previous step "GrassShader"
4. Select two colors. It looks best if the top color is slightly lighter than the bottom color.
5. For the alpha map, select the texture you imported previously.

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2Fgit-blob-452658ace42a43875de63da7458b04461bb774e8%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

### 6. Create a landscape material

The key to make the grass mesh blend in nicely is to use a similar color at the bottom of the grass mesh as the material used on the landscape.

Create a new material like you did for the grass blades. This time, instead of using a custom shader, we can use Lambert or Standard. Set the color property to the color you used for the bottom of the grass blades.

Assign this new ground material by finding it in the asset browser, click and drag it onto the landscape in the scene.

### 7. Adjusting the grass settings

You can now go back to the landscape's grass settings and adjust the options.

* Increase **density**. Set the density higher to something like 10. A higher density can look more realistic as you will have more grass models scattered on the landscape. However, this comes with a performance cost as it will be much more triangles for the GPU to render.
* Enable **normals up**. This will make it so light calculations on the grass mesh is similiar to the ground below. This can make it look more realistic or your moodel may look very dark on the side that is not facing the light.
* Adjust **min scale**, to create some variation.

You should now have a landscape that looks similar to this.

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2Fgit-blob-ddc085dbd5573ae27c9d90a3a088883490d0647c%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>


# Creating user interfaces

As Hology Engine runs in yours web browser, it allows you to use existing libraries and tools to create user interfaces with Typescript, HTML and CSS. You can use any existing library or framework such as React, Vue, Angular, and many more. This enables you to leverage existing skillsets and resources rather than having to use something custom for Hology Engine. If you already have a preferred technology stack for building web application, this may be great. If on the other hand, your are new to web development, this may present you with lots of options of which you don't know what to choose. We have a suggested technology stack for UI development that will be used in our official tutorials that you can lean on.


# Using React

React is a popular library that enables you to create UI components that easily can be reused. Hology Engine provides a library specifically to help integrating React components with the game play state and actors.

## Using the Hology Scene component

To run Hology Engine within a react application, you can simply use the `HologyScene` component.

```tsx
<HologyScene gameClass={Game} sceneName='demo' dataDir='data' shaders={shaders} actors={actors}>  
</HologyScene>
```

This will start the Hology Engine runtime with a given scene. You also need to pass in some parameters for Hology Engine as these may differ depending on your your projects is set up. If you are using the default react project template when you create a new Hology project, then the values shown in the code above should work.

* **sceneName** - The name of the scene you want to load
* **dataDir** - A path to the folder where all Hology game data exists.
* **shaders** - An object with shader classes
* **actors** - An object with actor classes

## Adding UI components

Inside the `HologyScene` component, you can put components that should be displayed on top of the rendered game.

```tsx
function App() {
    return (
      <HologyScene gameClass={Game} sceneName='demo' dataDir='data' shaders={shaders} actors={actors}>
        <p>This will be displayed over the game</p>     
      </HologyScene>
    )
}
```

### Required CSS

To properly handle pointer events when using the `HologyScene` component, the following CSS needs to be added in your project. It will ensure that pointer events can be captured on the canvas which is used by the Pointer Events service while also capturing events on your own HTML elements added as children of the component.

```css
.hology-overlay {
  pointer-events: none
}
.hology-overlay * {
  pointer-events: auto; 
}
```

### Hology React hooks

Components used within the HologyScene component can use hooks like `useService` as seen below to access any of your game play services within this instance of the game.

```tsx

function PlayerHealthDisplay() {
  const playerState = useService(PlayerState)
  return <h1>{playerState.health.value}</h1>
}

function App() {
    return (
      <HologyScene gameClass={Game} sceneName='demo' dataDir='data' shaders={shaders} actors={actors}>
        <PlayerHealthDisplay></PlayerHealthDisplay>   
      </HologyScene>
    )
}
```

* **useService** - Get the instance of any service in your game play code. This can be useful for services that hold some global game play state that you want to display.
* **useActorQuery** - Query actors currently added to the game world. Whenever an actor that matches the query is added or removed from the world, the component will re-render.
* **useRenderUpdate** - Execute a given function before every frame.
* **useRenderLaterUpdate** - Execute a given function before every frame but after other update functions.

## Updating the UI when state changes

React is meant to only re-render when something changes which is great for a performant user interface but it needs to know when something changes. If you want to display some value from your game play code in the user interface, your can read the value by accessing it from a service or an actor but you need to let React somehow know that the value has changed.

One way to manage this is by using signals. Signals is a concept that is becoming more popular in web front end development that lets you represent state in a way that consumers of that state can know when the value of the signal changes. When you create a new Hology Engine project and selects React as the UI framework, it will automatically also install a library called [@preact/signals-react](https://www.npmjs.com/package/@preact/signals-react).

Let's say you have a service in your game play code that looks like below. We use the signal function when defining a property.

```typescript
import { Service } from '@hology/core/gameplay'
import { signal } from "@preact/signals-react"

@Service()
class PlayerState {
  health = signal(100)
}

export default PlayerState
```

We can now access this health signal in our React components like below. First we use the useService hook to access the instance of the PlayerState class. The value of the health signal can be accessed by using the `.value` property.

```tsx
function PlayerHealthDisplay() {
  const playerState = useService(PlayerState)
  return <h1>{playerState.health.value}</h1>
}
```

We can later update the value of the signal by assigning a new value to the value property. In the below example we define a method that updates the health signal based on a given damage amount.

```typescript
import { Service } from '@hology/core/gameplay'
import { signal } from "@preact/signals-react"

@Service()
class PlayerState {
  health = signal(100)
  
  takeDamage(damage: number) {
    this.health.value = Math.max(0, this.health.value - damage)
  }
}

export default PlayerState
```

Whenever the signal is updated, the react component will automatically re-render.


# VR

To enable VR in your game or 3D experience, you can simply pass in XR settings using the HologyScene component. The only setting you need is to set enabled to true.

```tsx
function App() {
  return (
    <HologyScene 
      gameClass={Game} 
      sceneName='main' 
      dataDir='data' 
      shaders={shaders} actors={actors} 
      xr={{enabled: true}}>
    </HologyScene>
  );
}
```


# Tutorial: Using getScreenPosition to Overlay UI at a World Position

The `getScreenPosition`method (from the `ViewController` service in Hology) converts a 3D world position (a `Vector3`) into 2D screen coordinates. This is useful for overlaying UI elements (like markers, health bars, or tooltips) on top of objects in your 3D scene.

```tsx
import { ViewController } from '@hology/core/gameplay';
import { useRenderLateUpdate, useService } from '@hology/react';
import { useRef } from 'react';
import { Vector3 } from 'three';

function WorldPositionMarker() {
  const markerRef = useRef<HTMLDivElement>(null);
  const view = useService(ViewController);

  useRenderLateUpdate(() => {
    // Replace (0,0,0) with any world position you want to track
    const pos = view.getScreenPosition(new Vector3(0, 0, 0));
    if (pos && markerRef.current) {
      markerRef.current.style.visibility = 'visible';
      markerRef.current.style.left = pos.x + 'px';
      markerRef.current.style.top = pos.y + 'px';
    } else if (markerRef.current) {
      markerRef.current.style.visibility = 'hidden';
    }
  });

  return (
    <div
      ref={markerRef}
      style={{
        position: 'absolute',
        width: '20px',
        height: '20px',
        background: 'red',
        borderRadius: '50%',
        pointerEvents: 'none',
        transform: 'translate(-50%, -50%)',
      }}
    />
  );
}

```

#### How it Works

* The component uses useService(ViewController) to access the camera and projection logic.
* On every frame (`useRenderLateUpdate`), it calls `getScreenPosition`with a 3D world coordinate.
* If the position is visible, it updates the marker's CSS to move it to the correct screen position.
* If the position is off-screen or not visible, it hides the marker.

#### Customization

* To track a different world position, change the argument to getScreenPosition.
* You can style the marker as needed (color, size, etc.).
* You can render multiple markers for different world positions by reusing this component.


# Introduction to VFX

## What are visual effects?

Visual effects (also known as VFX) is an integral component of storytelling and gameplay immersion. They serve to convey mood, evoke emotions, and communicate vital information to players. A well-executed visual effect can enhance gameplay feedback, guide player actions, and amplify the overall aesthetic appeal of a game.

A visual effect can be composed of multiple components including particle systems, custom shaders, materials, animation and post processing.

## VFX in Hology Engine

Given how integral VFX is to good gameplay, there is dedicated tooling to efficiently create effects that can be placed in scenes or spawned dynamically through game play code.


# VFX assets

## Creating a VFX asset

You can create a new visual effect by clicking "Add new" in the asset browser. You will be prompted to enter a name for the visual effect asset.

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2Fgit-blob-d7ed391d71e909a89bb10080064704d23813da61%2FScreenshot%202024-05-13%20at%2020.16.01.png?alt=media" alt="" width="254"><figcaption></figcaption></figure>

## Placing visual effect in a scene

After creating a visual effect, you can place them in scenes and prefabs just like other 3D models. In the asset browser, filter on "Visual Effects". Then click and drag the visual effect into the scene to place it.

## Using VFX assets in code

### Spawning a VFX actor from asset ID

You can reference a VFX asset in your code using the asset ID. This will spawn a VFX actor in the world and return it to you so that you can control the vfx using methods like `play`, `stop`, or adjust `timescale`.

```typescript
@Actor()
class Player {
    private vfx = inject(VfxService)

    async onInit() {
        const vfxActor = await this.vfx.createFromAssetId('your-asset-id')
        vfxActor.play()
    }
}
```

### Spawning a VFX actor using a Visual Effect parameter

To enable configuring which visual effect to use in the Hology editor, you can define a parameter on the actor. This can enable you to alse reuse the same actor class but change the visual effect asset.

```typescript
@Actor()
class Player {
    @Parameter()
    private vfxParam: VisualEffect 

    async onInit() {
        const vfxActor = await this.vfxParam.create()
        vfxActor.play()
    }
}
```


# Emitter basic tutorial

{% embed url="<https://youtu.be/G3hce28VGPo?si=aSNfWTQB_PbsdsOF>" %}

## Creating a snowfall visual effect

This beginner tutorial demonstrates how to create a snowfall effect with 1 emitter, using the VFX Editor in the Hology Engine. By following these steps, you’ll learn how emitters, behaviors, and properties work together to produce dynamic particle effects.

## Create a new visual effect

1. In the asset browser, select → Add New → select Visual Effect.

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2Felk9nopPqCca34vOPGxs%2FScreenshot%202026-03-07%20172525.png?alt=media&amp;token=289499a3-6504-43b5-bb2b-22689ac17b2b" alt="" width="516"><figcaption></figcaption></figure>

2. Name the new effect, for example, “Snowy”  → click Create.
3. The VFX Editor will open automatically.

## Configure the emitter

1. Select Add emitter on the upper right hand corner of the VFX editor.&#x20;

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2FXYhGzNA7EWWlF5YRbjUy%2FScreenshot%202026-03-07%20174247.png?alt=media&amp;token=abb22377-0a50-43c3-953e-fdb2d6b0a7ff" alt=""><figcaption></figcaption></figure>

2. Click on the created emitter to open the emitter edit window.
3. Set the Type to Continuous to ensure the snow continuously spawns.
4. Under Count, enter 14 to increase the number of active particles.
5. Change the Spawn Time to 0.6 seconds to control how frequently particles appear.
6. Find the Initializers category → In the Lifetime property, enter a duration time, for example, 6,  so snowflakes remain visible longer.

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2F8sFBI1U3VmcA9MPLMzpo%2FScreenshot%202026-03-08%20163742.png?alt=media&amp;token=222761dd-2291-4ebf-8415-c705439e7f55" alt="" width="311"><figcaption></figcaption></figure>

## Add randomized particle direction

1. Initializers category → Click the + button to add a new emitter property.
2. Select Random Direction.

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2FP8Q3bb2eS784ugFmxIYk%2FScreenshot%202026-03-08%20163950.png?alt=media&amp;token=449b26b3-7792-47fa-82f5-933a40a07150" alt="" width="305"><figcaption></figcaption></figure>

3. Adjust the Speed value to give snowflakes varying movement directions. For example, change the Speed value to 3.85. You should now see particles drifting in different directions within the scene view.

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2FCkmZ4VIhb9gET6Ess7PI%2FScreenshot%202026-03-08%20164415.png?alt=media&amp;token=61092f4c-4698-41e9-92d8-025845f5c319" alt="" width="375"><figcaption></figcaption></figure>

## Define the particle spawn area

1. Initializers category → Click the + button again and choose Position Box. This defines a 3D region where particles can appear.
2. Set the Dimensions to: X: 50, Y: 0.3, Z: 50\
   This ensures snowfall covers a wide area.

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2FPvlb8z078U4Tyw7ZQRyG%2FScreenshot%202026-03-08%20164534.png?alt=media&amp;token=b6bedda5-6d83-4623-9369-70e9022e83cb" alt=""><figcaption></figcaption></figure>

## Adjust particle scale

1. Initializers category → Click + button → Select Scale. Set Scale to 0.5. Smaller particles create a lighter, more realistic snowfall effect.

## Add random drift behavior

1. Find the Behaviours category → click + button → select Random Drift (highlighted in yellow in the picture below)

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2FuEmhwPzujANN7RPqw6D1%2FScreenshot%202026-03-08%20165340.png?alt=media&amp;token=3ba85a52-a6dc-4094-a84a-2c2e16dd5895" alt="" width="419"><figcaption></figcaption></figure>

2. Set Drift values to 0.2, 0.2, 0.2. Random Drift applies small, subtle motion variations, simulating natural turbulence in falling snow. You can experiment with these values for different looks.

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2Fdn7eHruW99dNSOnqlyQc%2FScreenshot%202026-03-08%20164829.png?alt=media&amp;token=407ff066-467a-46fe-b6ca-6d88ee0b67da" alt=""><figcaption></figcaption></figure>

## Apply gravity

1. In the Behaviours Category → click + button → select Gravity.
2. Reduce the gravity force from 8 (default) to 0.1. A smaller gravity value slows the fall speed, producing a gentle snowfall rather than a heavy drop.

## Add fade out with opacity

1. In the Behaviours category → click + button →  select Change Opacity.
2. Set the Start Opacity (A) to 0  → then set End Opacity (B) to 1. This creates a fade-out effect as snowflakes reach the ground.

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2Fvqlw0bmRoBG4UTNIodmm%2FScreenshot%202026-03-08%20165035.png?alt=media&amp;token=5846c6e7-f975-470b-bf61-bff0c5ed68c2" alt=""><figcaption></figcaption></figure>

## Apply linear damping

1. In the Behaviours category → click the + button →  select Linear Damping.
2. Set Factor value to 2. This introduces air resistance, causing snowflakes to gradually slow down as they fall, enhancing realism.

## Save and place in the scene

1. When satisfied, click Save (or press Ctrl and S key at the same time), and close the VFX editor.

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2FEBfna9izXFsihnHeBiGg%2FScreenshot%202026-03-08%20165800.png?alt=media&amp;token=7512f954-5b56-4604-875b-5c49f2e2a7d7" alt=""><figcaption></figcaption></figure>

2. Click on the VFX and hold → drag and drop the Snowy VFX from the asset browser into your scene.

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2FEQX9pzqtL4lO4qIu7hqP%2FScreenshot%202026-03-08%20170027.png?alt=media&amp;token=4d18360b-4646-4ee0-af12-9f268fabd419" alt="" width="563"><figcaption></figcaption></figure>

3. Move the effect slightly higher in the scene hierarchy so the snow appears to fall from above.&#x20;

You’ve now created your first visual effect in the Hology Engine!&#x20;

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2F0y0W2dVCwkIugH55cYnp%2FScreenshot%202026-03-08%20155347.png?alt=media&amp;token=8a537f27-9362-440c-b762-dcf818751ee2" alt=""><figcaption></figcaption></figure>


# Flipbook tutorial

## What is the flipbook visual effect?

Flipbook is a technique used to play a sequence of images (frames) quickly one after another, to create the appearance of motion, like an old school paper flipbook animation.

In VFX, this usually means a single texture sheet (called a flipbook texture or sprite sheet) that contains multiple frames of an animation arranged in a grid. For example, a fire animation might have eight rows and eight columns, creating 64 frames in total.

When the particle system or material cycles through these frames over time, it looks like a smooth, animated effect—such as fire, smoke, explosions, or magic glows—without requiring complex 3D simulations.\
\
The flipbook VFX tutorial is also available in video format below, where we create a campfire.&#x20;

{% embed url="<https://youtu.be/aMcHon8BKRQ?si=IcPcmE_bo0ZJY74p>" %}

## Import flipbook texture file

Drag and drop your flipbook texture (eg. PNG file) directly into the Hology Engine asset browser.&#x20;

You may use our example campfire texture from our video tutorial: [Click Here](https://drive.google.com/file/d/1_qBXuEcMypITD9xdwN2bMOoIvO6uLVPq/view)

## Create a new visual effect material

1. In the asset browser, select → Add New → select Visual Effect.

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2Felk9nopPqCca34vOPGxs%2FScreenshot%202026-03-07%20172525.png?alt=media&amp;token=289499a3-6504-43b5-bb2b-22689ac17b2b" alt=""><figcaption></figcaption></figure>

2. Name it using your preferred convention, e.g., *FX\_Stylized\_Fire (from video tutorial).*
3. *Click the Create button, and you will enter the VFX editor in a new tab.*&#x20;

## Add and set up an emitter in the VFX editor

1. In the VFX editor, click Add Emitter (top-right corner).

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2FXYhGzNA7EWWlF5YRbjUy%2FScreenshot%202026-03-07%20174247.png?alt=media&amp;token=abb22377-0a50-43c3-953e-fdb2d6b0a7ff" alt=""><figcaption></figcaption></figure>

1. Name the emitter (for example, *Fire*).
2. Set Loop to Continuous.
3. Leave Time empty (do NOT enter 0).
4. Scroll down to the Output section.
5. Next to Texture, click the empty slot and select your imported flipbook texture.

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2FoB4RdygLVjfSGjOC3T16%2FScreenshot%202026-02-27%20040957.png?alt=media&amp;token=ea2e87ad-35ae-42e2-bc69-04119b8d35dd" alt=""><figcaption></figcaption></figure>

## Enable the flipbook animation

1. Under the Output section, find the Flipbook category, and select YES
2. Underneath the Flipbook category, enter the correct layout for your texture. For example:

* &#x20;     Columns: 8
* &#x20;     Rows: 8 (This corresponds to a total of 64 frames.)

3. Press Play to preview the animation.

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2FrQR73Jz6v4LkySxZQexU%2FScreenshot%202026-02-27%20040836.png?alt=media&amp;token=5c4febb2-795f-42a7-93f5-645d83d6e3ae" alt=""><figcaption></figcaption></figure>

## Adjust the scale&#x20;

This is an optional step specifically for using our example texture campfire

1. Go to the Initializers section,  press the + button on the right, and select Scale.
2. Increase the scale to your desired value (e.g., 10) so the effect is properly visible.

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2FrfS758FXhe4keFrLgD7c%2FScreenshot%202026-02-27%20041128.png?alt=media&amp;token=c304bfe6-92ea-47bc-9e68-2e45622ff5c8" alt=""><figcaption></figcaption></figure>

## Correct the color channel&#x20;

This is an optional step, specifically for using our example texture campfire.

Go to the Output Section, find the Opacity Channel category, and change it from Alpha to Red to match the intended color behavior.

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2FLYfPmghD7kVY1tzSQLy1%2FScreenshot%202026-02-27%20041359.png?alt=media&amp;token=f6b73c80-a20f-412c-b33f-ee39368ce83d" alt=""><figcaption></figcaption></figure>

## Fix looping and playback speed

This is an optional step, specifically for using our example texture campfire.

1. Go to the Initializer Section, under Lifetime, adjust the duration value slightly to prevent clipping.
2. Change the total time from 1.0 seconds to approximately 1.066 seconds.
3. Press Play again to confirm it loops smoothly.

## Adjust the spawn position height

This is an optional step, specifically for using our example texture campfire.

1. Go to the Initializers Section, press the + button, and select Position Point
2. Increase the height value to raise the effect above the grid (e.g., 3.5).

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2FZfZTvXxhPBUgCAxgJQYZ%2FScreenshot%202026-02-27%20041913.png?alt=media&amp;token=9287d599-5600-49d3-abc9-5d1a31939f03" alt=""><figcaption></figcaption></figure>

## Save your effect

1. Press Ctrl + S to save your visual effect.
2. This step ensures the flipbook will appear properly in the asset browser.

## Place the effect in the scene

1. Drag the saved VFX from the asset browser into the scene.
2. You now have a looping, stylized fire created with a flipbook in Hology Engine.

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2F5MhLXl8CyWgG8tOXegLp%2FScreenshot%202026-03-07%20224315.png?alt=media&amp;token=a4f4a0d6-cafd-4855-aef3-7bec73d59f66" alt=""><figcaption></figcaption></figure>


# Lens flare tutorial

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2Fi5guFlBzmotMcDtq96Bc%2F26-03-07-23-04-50-389_deco.jpg?alt=media&amp;token=79d14775-7f4d-4a62-994c-7f71a60de430" alt=""><figcaption></figcaption></figure>

## What is a lens flare?&#x20;

When you point a camera at the sun or a bright light, you sometimes see extra bright shapes, rings, or streaks in the picture. These shapes are called lens flare. Game engines copy this look to make games and 3D projects feel more cinematic.\\

\
Because lens flare happens when light is bouncing around inside the camera lens, not out in the real world, that means:

* A normal glow effect usually sits around the light (for example, around a lamp or a fireball).
* A lens flare effect appears on top of the screen, as if it is in front of everything, because it is happening in the camera.

So sometimes it looks like the flare is in front of buildings or trees. This is because the effect is drawn in the camera image, not stuck to the light object in 3D space.

Below are the steps to set up a lens flare in Hology

Create/obtain a lens flare image\\

Create or find a PNG image/texture of a lens flare with a transparent background.\
This is the picture the engine will draw on the screen as the flare.

## Import the file to Hology Engine

1. Open Hology Engine, select an existing project or create a new project.
2. Drag and drop the PNG file into the asset browser, make sure to give it a clear name, such as *T\_OrangeFlare*

## Create a new material

1. In the asset browser, select → Add New → select Material.

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2FePAiowDQOHhyTvRzQc49%2FScreenshot%202026-03-07%20173000.png?alt=media&amp;token=76e64e2d-24f4-407e-ada3-f1d193fbb6e0" alt=""><figcaption></figcaption></figure>

2. On top, give it a clear name, for example: *M\_OrangeFlare*, so you remember what it is for.
3. Look for the Type setting, choose Sprite. This tells Hology that this material will draw a flat 2D image, perfect for a lens flare.
4. Scroll down to the Properties section.
5. Find the Map, select the PNG file you imported into the asset browser.

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2FvejnKopdV7y0Hirnpd4I%2F2.%20Screenshot%202026-02-25%20093503.png?alt=media&amp;token=7d72e8b0-df52-4117-be47-eb3bf89ab5e9" alt=""><figcaption></figcaption></figure>

6. Find the Lens Flare category in Properties, set it to YES, and press Save.

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2F7rtshPytEEeRQ7N64TQm%2FScreenshot%202026-03-07%20172210.png?alt=media&amp;token=b400b3cd-f36b-4724-9eaa-aae3aaf431d1" alt=""><figcaption></figcaption></figure>

## Implement in the scene

1. In the asset browser, click top left (highlighted yellow below image)→select Shapes.

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2Ffor6SANOo0qzggQFJaum%2FScreenshot%202026-03-07%20173713.png?alt=media&amp;token=93dec8fd-5b19-4ea2-b919-7e47966a20b0" alt=""><figcaption></figcaption></figure>

1. Find Plane in the asset browser (highlighted yellow above image), then drag and drop it into the project scene.
2. In the Plane’s edit panel, scroll to the bottom to find the Materials category, and select the Material you just created.
3. Now you can drag the plane anywhere you want the lensflare to show, for example, somewhere around the street light 3D model.&#x20;
4. You can also adjust the size of the lens flare by selecting the plane and clicking the scale option in the left utility bar on the screen.

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2F7vPIzOwjqFVR430JOBPg%2F6.%20Screenshot%202026-02-25%20094109.png?alt=media&amp;token=e3510324-5666-4e3e-91d9-7e03569dfa74" alt=""><figcaption></figcaption></figure>

Now you are ready to try and find the lensflare that fits your environment!


# Arcweave

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2Fgit-blob-f68cf9004adcf4cadfb3c4233066a4771d55dda3%2Faw.png?alt=media" alt=""><figcaption></figcaption></figure>

[Arcweave](https://arcweave.com/) is an easy to use and collaborative tool for creating narratives and dialogues that can be used in games. This can be suitable if your game lets the players talk with NPCs (non-player-characters). You can create the game's story and dialogue in Arcweave and export it to be used with Hology Engine.

[Try the example project in your browser](https://hologyengine.github.io/arcweave-tutorial/)

You can access the example project's code at <https://github.com/hologyengine/arcweave-tutorial> to see how it can be integrated in your Hology Engine game.

## Exporting

To use your Arcweave boards, you need to export it as a JSON file. In the Arcweave editor, click the Share & Export button on the top right. Select the JSON export and click export.

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2Fgit-blob-a5333676b4209e0f9886dbfa28a17c9dd5621bec%2FScreenshot%202024-07-18%20at%2019.14.07.png?alt=media" alt="" width="375"><figcaption><p>Arcweave JSON export</p></figcaption></figure>

## Using the Arcweave data

Place the exported JSON file in your code base in the src folder and rename the file to arcweave.json.

Install the Hology Arcweave library by running the following command in your terminal.

```sh
npm i @hology/arcweave
```

Import the file and create an ArcweaveStory instance.

```typescript
import { ArcweaveStory } from '@hology/arcweave'
import awProject from './arcweave.json'

const story = new ArcweaveStory(awProject)
```

With the story, you can get the current element, get options for what to respond or what decision to make in dialogue and to select which option to use. The story maintains the state of which elements have been visited and global variables that are updated based on selected options.

## Connecting dialogue to actors

Arcweave lets you define elements and connections between them to represent the story and paths. In an open world where you as a player have the freedom to walk up to any character to start the conversation, we need a way to trigger the game to display the correct dialogue by selecting the right element in the story. In Arcweave, you can create components that could represent a character. We can use this to connect elements to what the character is saying. We then need to know which element should be the starting point of the dialogue.

We will follow the practices used in the *Game Engine Example* project that comes with Arcweave. To specify the starting point of the dialogue, we add an attribute to the element with name "tag" and value "dialogue\_start". To connect a character component to an actor, we define an attribute on the component with name "obj\_id" and a value that will be used in the game as well. In the example, we use the name of the character in all uppercase characters.

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2Fgit-blob-afed3beb354dc2b9fa1a232e6c0fde4305fcabeb%2FScreenshot%202024-07-19%20at%2010.37.33.png?alt=media" alt="" width="375"><figcaption><p>Dialogue start attribute</p></figcaption></figure>

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2Fgit-blob-6953962a83c8cd3c7c5e46594fc5717449433936%2FScreenshot%202024-07-19%20at%2010.37.11.png?alt=media" alt="" width="375"><figcaption><p>Component obj_id attribute</p></figcaption></figure>

In your Hology Engine project's code base, we will create an actor component with a parameter for the obj id so that we can specify that an instance of that actor refers to a character in the Arcweave project.

```typescript
import { ActorComponent, Component, Parameter } from "@hology/core/gameplay";

@Component()
class DialogueStartComponent extends ActorComponent {

  @Parameter()
  public objId: string

}

export { DialogueStartComponent }
```

We will then add a few more things. A trigger volume and a dialogue service that will manage the story. In the code below, you can see how we pass the objId property to the startDialogue method on the dialogue service when the character actor starts overlapping the trigger volume. This will be used to find the element that is the starting point of the dialogue.

```typescript
import { ActorComponent, attach, Component, inject, Parameter } from "@hology/core/gameplay";
import { TriggerVolumeComponent } from "@hology/core/gameplay/actors";
import Character from "../actors/character";
import { DialogueService } from "../services/dialogue-service";


@Component()
class DialogueStartComponent extends ActorComponent {

  @Parameter()
  public objId: string

  private triggerVolume = attach(TriggerVolumeComponent)
  private dialogueService = inject(DialogueService)

  onBeginPlay(): void {
    this.triggerVolume.onBeginOverlapWithActorType(Character).subscribe(() => {
      this.dialogueService.startDialogue(this.objId)
    })

    this.triggerVolume.onEndOverlapWithActorType(Character).subscribe(() => {
      this.dialogueService.endDialogue()
    })
  }

}

export { DialogueStartComponent }
```

For this example, we create a dialogue service to act as an interface for actors to manage the story and to expose it to the user interface. In the code below, you can see how we find the starting element of the story using the passed in objId and set the current element in the story.

```typescript
import { Service } from "@hology/core/gameplay";
import { signal } from "@preact/signals-react"
import arcweaveProject from '../arcweave.json'
import { StoryOption, ArcweaveStory } from "@hology/arcweave";

export type DialogueElement = {
  speakerName?: string
  content: string
  options: StoryOption[]
  end: boolean
}

@Service()
class DialogueService {
  readonly activeDialogue = signal<DialogueElement|null>(null)
  readonly story = new ArcweaveStory(arcweaveProject)

  startDialogue(objId: string) {
    const characterId = this.story.findComponentId({attribute: [{name: 'obj_id', value: objId}]})
    if (characterId == null) {
      console.error(`Could not find character with obj_id ${objId}`)
      return
    }
    const startElementId = this.story.findElementId({attribute: [{name: 'tag', value: 'dialogue_start'}], componentId: characterId})
    if (startElementId == null) {
      console.error(`Could not find dialogue start for character with obj_id ${objId}`)
      return
    }
    this.story.setCurrentElement(startElementId)
    this.updateActiveDialogue()
  }

  endDialogue() {
    this.activeDialogue.value = null
  }

  selectOption(path: StoryOption) {
    this.story.selectOption(path)
    this.updateActiveDialogue()
  }

  private updateActiveDialogue() {
    const element = this.story.getCurrentElement()
    this.activeDialogue.value = {
      speakerName: element.components.find(c => c.attributes['obj_id'] != null)?.name,
      content: element.content,
      options: element.options,
      end: element.attributes['tag'] === 'dialogue_end' || element.options.length === 0
    }
  }
}

export { DialogueService }
```

## Automatic refresh

Instead of exporting the Arcweave project as a JSON file and placing it in your Hology project every time you want to make test changes, we can use Arcweave's API to fetch the data. This is can be accomplished using a plugin to the build system.

### Configuring the plugin

To start using the plugin, you first need to add a plugin to the Vite build configuration used in default Hology projects.

In the file vite.config.ts, replace it with the following code. What we add here is the import of the Vite plugin on line 4 and on line 11-14, we configure the plugin with your API key and project hash. See sections further down for how to find your API key and project hash.

{% code lineNumbers="true" %}

```typescript
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import hologyBuild from '@hology/vite-plugin'
import arcweave from '@hology/arcweave/vite-plugin'

export default defineConfig({
  esbuild: {
    target: "es2020",
  },
  plugins: [
    arcweave({
      apiKey: 'YOUR_ARCWEAVE_API_KEY', 
      projectHash: 'YOUR_PROJECT_HASH'
    }),
    hologyBuild(),
    react({
      babel: {
        plugins: [
          ["@babel/plugin-proposal-decorators", { version: "2023-11" }],
          ["module:@preact/signals-react-transform"],
        ],
      },
    }),
  ],
})
```

{% endcode %}

### API Key

To get the API key, you need a team workspace in Arcweave. Then in their user interface, you can navigate to the API section and create a new API key.

### Project hash

The project hash is a unique identifier for the project that you want to use in your game. To get the project hash, you need to open the project in Arcweave, and find the hash in the URL.

<https://arcweave.com/app/project/**PROJECT\\_HASH**?board=>...

<figure><img src="https://2195662805-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUL3kt9YBybm9hHgVsG1h%2Fuploads%2Fgit-blob-76884a3c600c891f4b384a53b9c905c619e8ec65%2Fimage.png?alt=media" alt="" width="476"><figcaption><p>Find Arcweave project hash</p></figcaption></figure>

### Importing the virtual arcweave module

Instead of importing the json file from your source code, just replace it with an import form '`virtual:arcweave'` . This will make the build system resolve the Arcweave project data via the Arcweave API every time you build or refresh in dev mode.

```typescript
//import arcweaveProject from '../arcweave.json'
import arcweaveProject from 'virtual:arcweave'
```

## Next steps

To learn more about how to integrate Arcweave into your project, take a look at the [example project](https://github.com/hologyengine/arcweave-tutorial) on Github.


# 歡迎來到Hology文檔

本網站旨在幫助新用戶開始使用Hology，同時也作為經驗豐富的用戶學習所有相關知識的資源。新文章將隨時間添加。

## 如何聯絡客服

如果您對Hology有任何疑問或需要幫助，請通過<hello@hology.app>與我們聯繫。我們很樂意通過電子郵件為您提供指導或安排線上通話。

## 如何開始

* 請按照 [第一步指南](https://docs.hology.app/zh-tw/getting-started/di-yi-bu-zhi-nan)  了解設置Hology和運行應用程序或遊戲的基礎知識。
* 通過 [編輯器基礎指南](https://docs.hology.app/zh-tw/getting-started/bian-ji-qi-ji-chu-zhi-nan) 了解如何使用編輯器。
* 按照遊戲程式設計指南 [滾球 - 遊戲玩法編程](https://docs.hology.app/zh-tw/tutorials/gun-qiu-you-xi-wan-fa-bian-cheng) 進行操作。
* 下載 [入門遊戲模板 - 第三人稱射擊遊戲](https://docs.hology.app/zh-tw/getting-started/ru-men-you-xi-mu-ban-di-san-ren-cheng-she-ji-you-xi)，查看如何設置角色移動的示例。[入門遊戲模板 - 第三人稱射擊遊戲](https://docs.hology.app/zh-tw/getting-started/ru-men-you-xi-mu-ban-di-san-ren-cheng-she-ji-you-xi)&#x20;


# Hology Engine簡介

Hology Engine是一個遊戲引擎，允許用戶使用網絡技術（如Typescript、HTML和CSS）創建3D遊戲和體驗。您創建的內容可以用於網站、移動應用程序或安裝為桌面應用程序。Hology Engine提供了使3D體驗開發更容易的工具，如用於創建場景（遊戲關卡）的3D編輯器和遊戲框架。


# 第一步指南

Hology編輯器可以安裝在Windows、Mac和Linux上。請點擊下方連結。(Link to download engine)

[下載編輯器](https://hology.app/download)

#### 在Windows上安裝

如果您下載Windows版本，可能會看到一個藍色窗口顯示"Windows保護了您的電腦"。只需點擊"更多信息"，然後點擊"仍要運行"。

## 先決條件

### 下載軟件

您還需要先安裝Node.js和一個代碼編輯器。任何代碼編輯器都可以使用。Visual Studio Code是一個的選擇。

[下載Node.js](https://nodejs.org/en/download)

[下載Visual Studio Code](https://code.visualstudio.com/download)

### 知識

使用Hology Engine，需要具備一些網路開發和相關技術的知識。這包括Typescript、HTML、CSS以及如何使用terminal。

## 創建新項目

要創建新項目，請在您的電腦上打開Hology編輯器。

點擊 "Create a new project/創建新項目"。然後設置項目名稱，可以是您將要創建的遊戲名稱。可以選擇一個模板/template作為起點。選擇一個UI框架，如React，它將在創建項目時為您在項目的代碼庫中設置。

<figure><img src="https://content.gitbook.com/content/vmiEoZNjYR9FQabz2WCa/blobs/1NHQyo74ZJOdEn3lftd6/Screenshot%202023-09-12%20at%2018.09.28.png" alt=""><figcaption></figcaption></figure>

點擊 "Create/創建" 後，項目的代碼庫將被設置，並安裝構建項目所需的各種依賴項。安裝完成後，您的項目應該在新窗口中打開。

一個場景（可以代表您遊戲的整個世界或單個遊戲關卡）已為您創建，名為demo。要在遊戲中使用該場景，您需要在代碼中引用場景的名稱。

## 在瀏覽器中測試您的遊戲

該項目本質上是一個網站，這意味著在開發過程中，您可以在瀏覽器中測試遊戲。

要運行您的遊戲，打開終端/terminal並導航到項目文件夾，然後運行命令npm run dev。

{% code fullWidth="false" %}

```
cd /path/to/my-project
npm run dev
```

{% endcode %}

一個"localhost"地址會被記錄（<http://localhost:5173/>）。在瀏覽器中打開此地址，您現在應該能看到您的場景。在Hology編輯器中對場景所做的任何更改，在刷新後都會立即反映在瀏覽器窗口中。


# 編輯器基礎指南

Hology編輯器使您能夠設計遊戲世界和關卡。它提供了一個管理資產的介面，以及用於放置和更改物件的各種工具。本頁將詳細解釋如何使用編輯器。

{% embed url="<https://youtu.be/dDrOy6PYHi0?si=YZFcmaWAVlfwWWiQ>" %}

## 面板主要功能

### 資產瀏覽器/Asset browser

資產瀏覽器(Asset browser)包含可在您的場景中使用的內容。它包含許多內建資產，如簡單形狀和角色，以及您自己導入的資產。

<figure><img src="https://content.gitbook.com/content/vmiEoZNjYR9FQabz2WCa/blobs/kXusDEkZW5bqlXMFUF5p/Screenshot%202023-11-02%20090559.png" alt=""><figcaption></figcaption></figure>

#### 類別/Categories

資產按類別分組。使用此下拉選擇器選擇類別。

<figure><img src="https://content.gitbook.com/content/vmiEoZNjYR9FQabz2WCa/blobs/X40AbmgUI0ESZ5rJck6a/Screenshot%202023-11-02%20090154.png" alt=""><figcaption><p>Asset category selector</p></figcaption></figure>

Models/模型：3D物件的幾何形狀和結構。 \
Materials.材質：定義物體表面外觀的屬性集合。 \
Shapes/形狀：基本的幾何形體，如立方體、球體等。 \
Actors/角色：可在遊戲中互動或控制的實體。 \
Prefabs/預製體：預先配置好的遊戲物件模板。 \
Textures/紋理：應用於3D模型表面的2D圖像。 \
Audio/音訊：遊戲中使用的聲音文件。\
VFX(Particles systems)/視覺特效：增強視覺體驗的粒子系統或其他效果。 \
Lights/燈光：用於照亮場景的各種光源。

### 大綱視圖/Outliner

大綱視圖(Outliner)呈現場景中物件的層次結構。它允許您選擇物件，並對物件執行各種操作。 &#x20;

* 通過先選擇一個物件，然後按住 Shift 鍵並選擇另一個物件，可以選擇一系列物件。
* 按住 Ctrl 鍵（在 Mac 上為 ⌘ 鍵）可以將其他物件添加到您的選擇中。
* 按住 Ctrl 鍵和英文字母G鍵來將物件組合為一個群組。

<figure><img src="https://content.gitbook.com/content/vmiEoZNjYR9FQabz2WCa/blobs/gBqVmSMp9cEyfWaQJKrT/Screenshot%202023-11-02%20090440.png" alt=""><figcaption><p>Outliner</p></figcaption></figure>

### 控制欄/Control bar

控制欄(Control bar)包含易於使用的設置，可以快速更改您在編輯器中查看場景的方式，以及某些工具的工作方式。

按順序從左到右按鈕解釋：

* **局部變換(Local transform)：**&#x9EDE;擊以切換變換工具在局部空間中工作。在局部空間中，縮放和移動的軸線將與物件的旋轉對齊，而不是與世界對齊。
* **網格(Grid)：**&#x5728;移動或放置物件時啟用吸附。吸附可以幫助更準確地放置物件，使它們彼此緊鄰或保持均勻的間距。這使您能夠更有效地使用模組化資產，例如具有標準寬度和高度的建築組件，以便它們可以精確地放置在彼此相鄰的位置。
* **2D：**&#x4EE5;俯視正交視圖顯示場景。這可以幫助您比使用透視攝像機更容易地對齊物品。
* **攝像機設置(Camera setting)：**&#x63A7;制飛行攝像機的移動、視野、視距，以及查看碰撞形狀。

<figure><img src="https://content.gitbook.com/content/vmiEoZNjYR9FQabz2WCa/blobs/99jjsQNfi3uwfVjxPSyc/Screenshot%202023-11-02%20091355.png" alt=""><figcaption></figcaption></figure>




---

[Next Page](https://docs.hology.app/llms-full.txt/1)

