
This guide you will show you how you can build a multiplayer experience with Colyseus Multiplayer Framework and Babylon.js.

<iframe height="70%" width="70%" src="https://tutorial-babylonjs-server.glitch.me" />

**By the end of this guide, you will:**

- Set-up your first authoritative server with Colyseus
- Synchronize shared state data between server and client
- Exchange messages between client and server
- Match-make clients into game sessions (rooms)

## Full source code

- [Babylon.js Project (Client-side)][1]
- [Colyseus Node.js/TypeScrippt Project (Server-side)](https://github.com/colyseus/tutorial-babylonjs-server/)

## Before you start

### Prior Knowledge Expected

- Basic Babylon.js knowledge ([See Getting Started with Babylon.js](https://doc.babylonjs.com/start))
- Basic knowledge of Node.js ([See Introduction to Node.js](https://nodejs.dev/learn/))

### Software Requirements

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

## Creating the server

We will be making a basic server, hosted locally on your computer for keeping player states. Changes will be synchronized with clients accordingly.

To create a fresh new Colyseus server, run the following from your command-line:

```
npm init colyseus-app ./babylonjs-multiplayer-server
```

Let's make sure you can run the server locally now, by running `npm start`:

```
cd babylonjs-multiplayer-server
npm start
```

If successful, the output should look like this in your command-line:

```
> my-app@1.0.0 start
> ts-node-dev --respawn --transpile-only src/index.ts

✅ development.env loaded.
✅ Express initialized
🏟 Your Colyseus App
⚔️ Listening on ws://localhost:2567
```

### Including the Colyseus JavaScript SDK

For simplicy sake, the examples on this guide are using the [Babylon.js Playground](https://doc.babylonjs.com/toolsAndResources/tools/playground). Although the full source-code available for download uses [NPM + Webpack](https://doc.babylonjs.com/divingDeeper/developWithBjs/npmSupport).

In the Playground, we inject the Colyseus JavaScript SDK manually through a `<script>` tag created via code, as described in [_"Using External Assets In The Playground"_ → _"Javascript files"_](https://doc.babylonjs.com/toolsAndResources/tools/playground/externalPGAssets#javascript-files).

_(This is not recommended in a real-world scenario)_

```typescript
// Load Colyseus SDK (asynchronously)
var scriptUrl = "https://unpkg.com/colyseus.js@^0.15.0-preview.2/dist/colyseus.js";
var externalScript = document.createElement("script");
externalScript.src = scriptUrl;
document.head.appendChild(externalScript);
```

In a real-world scenario, please follow the [official Colyseus documentation](https://docs.colyseus.io/colyseus/getting-started/javascript-client/) on how to include the Colyseus JavaScript SDK.

<Playground id="#ZRZS5F#1" title="Loading the SDK Example" description="This example only loads the Colyseus JavaScript SDK" image="/img/resources/networking/colyseus/playground-load-sdk.png"/>

### Establishing a Client-Server Connection

Now we can instantiate Colyseus `Client` instance and join a game from any script.

```typescript
var createScene = function () {
  // (...)

  //
  // Create the Colyseus Client.
  //
  var colyseusSDK = new Colyseus.Client("ws://localhost:2567");

  //
  // Connect with Colyseus server
  //
  colyseusSDK
    .joinOrCreate("my_room")
    .then(function (room) {
      console.log("Connected to roomId: " + room.roomId);
    })
    .catch(function (error) {
      console.log("Couldn't connect.");
    });

  // (...)
};
```

> Note that we're using the local `ws://localhost:2567` endpoint here. You need to [deploy your server](https://docs.colyseus.io/arena/getting-started/create-application/) to the public internet in order to play with others online.

> If you happen to see `net::ERR_BLOCKED_BY_CLIENT` error in the console, make sure to disable ad-block or shields due to untrusted origin.

When you run your BabylonJS project now, your client is going to establish a connection with the server, and the server is going to create the room `my_room` on demand for you.

Notice that `my_room` is the default room identifier set by the barebones Colyseus server. You can and should change this identifier in the `arena.config.ts` file.

You will be seeing the following message in your server logs, which means a client successfully joined the room!

```shell
19U8WkmoK joined!
```

<Playground id="#3K64VU#2" title="Room connection Example" description="This example loads the Colyseus SDK and connects into a room." image="/img/resources/networking/colyseus/playground-room-connection.png"/>

## Room State and Schema

In Colyseus, we define shared data through its `Schema` structures.

> `Schema` is a special data type from Colyseus that is capable of encoding its changes/mutations _incrementally_. The encoding and decoding process happens internally by the framework and its SDK.

The state synchronization loop looks like this:

1. State changes (mutations) are synchronized automatically from Server → Clients
2. Clients, by attaching callbacks to their local _read-only_ `Schema` structures, can observe for state mutations and react to it.
3. Clients can send arbitrary messages to the server - which decides what to do with it - and may mutate the state (Go back to step **1.**)

---

Let's go back to editing the Server code, and define our Room State in the Server.

We need to handle multiple `Player` instances, and each `Player` will have `x`, `y` and `z` coordinates:

```typescript
// MyRoomState.ts
import { MapSchema, Schema, type } from "@colyseus/schema";

export class Player extends Schema {
  @type("number") x: number;
  @type("number") y: number;
  @type("number") z: number;
}

export class MyRoomState extends Schema {
  @type({ map: Player }) players = new MapSchema<Player>();
}
```

> See more about the [Schema structures](https://docs.colyseus.io/colyseus/state/schema/).

Now, still in the server-side, let's modify our `onJoin()` method to create a `Player` instance whenever a new connection is established with the room.

```typescript
// MyRoom.ts
// ...
    onJoin(client: Client, options: any) {
        console.log(client.sessionId, "joined!");

        // create Player instance
        const player = new Player();

        // place Player at a random position
        const FLOOR_SIZE = 500;
        player.x = -(FLOOR_SIZE/2) + (Math.random() * FLOOR_SIZE);
        player.y = -1;
        player.z = -(FLOOR_SIZE/2) + (Math.random() * FLOOR_SIZE);

        // place player in the map of players by its sessionId
        // (client.sessionId is unique per connection!)
        this.state.players.set(client.sessionId, player);
    }
// ...
}
```

Also, when the client disconnects, let's remove the player from the map of players:

```typescript
// MyRoom.ts
// ...
    onLeave(client: Client, consented: boolean) {
        console.log(client.sessionId, "left!");

        this.state.players.delete(client.sessionId);
    }
// ...
```

The state mutations we've done in the server-side **can be observed** in the client-side, and that's what we're going to do in the next section.

## Setting up the Scene for Synchronization

For this demo, we need to create two objects in our Scene:

- A Plane, mesh object to represent the floor
- A Sphere, mesh object to represent the players, which we will initiate for each new player joining the room.

### Creating the Plane

Let's create a Plane with size `500`.

```typescript
// Create the ground
var ground = BABYLON.MeshBuilder.CreatePlane("ground", { size: 500 }, scene);
ground.position.y = -15;
ground.rotation.x = Math.PI / 2;
```

## Listening for State Changes

After a connection with the room has been established, the client-side can start listening for state changes, and create a visual representation of the data in the server.

### Adding new players

As per [Room State and Schema](#room-state-and-schema) section, whenever the server accepts a new connection - the `onJoin()` method is creating a new Player instance within the state.

We're going to listen to this event on the client-side now:

```typescript
// (...)

// connect with the room
colyseusSDK.joinOrCreate("my_room").then(function (room) {
  // listen for new players
  room.state.players.onAdd((player, sessionId) => {
    //
    // A player has joined!
    //
    console.log("A player has joined! Their unique session id is", sessionId);
  });
});

// (...)
```

When playing the scene, you should see a message in the browser's console whenever a new client joins the room.

For the visual representation, we need to clone the "Player" object, and keep a local reference to the cloned object based on their `sessionId`, so we can operate on them later:

```typescript
// (...)

// we will assign each player visual representation here
// by their `sessionId`
var playerEntities = {};

colyseusSDK.joinOrCreate("my_room").then(function (room) {
  // listen for new players
  room.state.players.onAdd(function (player, sessionId) {
    // create player Sphere
    var sphere = BABYLON.MeshBuilder.CreateSphere(`player-${sessionId}`, {
      segments: 8,
      diameter: 40,
    });

    // set player spawning position
    sphere.position.set(player.x, player.y, player.z);
  });
});

// (...)
```

<Playground id="#W613VP#2" title="Adding players Example" description="This example connects into a room, and display the players who joined the room" image="/img/resources/networking/colyseus/playground-onadd.png"/>

### The "Current Player"

We can give the current player, color `#ff9900` and other players `grey`, by checking the `sessionId` against the connected `room.sessionId`:

```typescript
// (...)

room.state.players.onAdd((player, sessionId) => {
  var isCurrentPlayer = sessionId === room.sessionId;

  // (...)

  // set material to differentiate CURRENT player and OTHER players
  sphere.material = new BABYLON.StandardMaterial(`player-material-${sessionId}`);

  if (isCurrentPlayer) {
    // highlight current player
    sphere.material.emissiveColor = BABYLON.Color3.FromHexString("#ff9900");
  } else {
    // other players are gray colored
    sphere.material.emissiveColor = BABYLON.Color3.Gray();
  }

  // (...)
});

// (...)
```

### Removing disconnected players

When a player is removed from the state (upon `onLeave()` in the server-side), we need to remove their visual representation as well.

```javascript
// ...
room.state.players.onRemove(function (player, sessionId) {
  playerEntities[sessionId].dispose();
  delete playerEntities[sessionId];
});
// ...
```

<Playground id="#CB3LF6#1" title="Current player color Example" description="This example connects into a room, and set different color for current player." image="/img/resources/networking/colyseus/playground-onadd-onremove.png" />

## Moving the players

### Sending the new position to the server

We are going to allow the `Scene.onPointerDown` event; to determine the exact `Vector3` position the player should move towards, and then send it as a message to the server.

```typescript
scene.onPointerDown = function (event, pointer) {
  if (event.button == 0) {
    const targetPosition = pointer.pickedPoint.clone();

    // Position adjustments for the current play ground.
    // Prevent spheres from moving all around the screen other than on the ground mesh.
    targetPosition.y = -1;
    if (targetPosition.x > 245) targetPosition.x = 245;
    else if (targetPosition.x < -245) targetPosition.x = -245;
    if (targetPosition.z > 245) targetPosition.z = 245;
    else if (targetPosition.z < -245) targetPosition.z = -245;

    // Send position update to the server
    room.send("updatePosition", {
      x: targetPosition.x,
      y: targetPosition.y,
      z: targetPosition.z,
    });
  }
};
```

### Receiving the message from the server

Whenever the `"updatePosition"` message is received in the server, we're going to mutate the player that sent the message through its `sessionId`.

```typescript
// MyRoom.ts
// ...
  onCreate(options: any) {
    this.setState(new MyRoomState());

    this.onMessage("updatePosition", (client, data) => {
      const player = this.state.players.get(client.sessionId);
      player.x = data.x;
      player.y = data.y;
      player.z = data.z;
    });
  }
// ...
```

### Updating Player's visual representation

Having the mutation on the server, we can detect it on the client-side via `player.onChange()`, or `player.listen()`.

- `player.onChange()` is triggered **per schema instance**
- `player.listen(prop)` is triggered **per property** change

We are going to use `.onChange()` since we need all the new coordinates at once, no matter if just one has changed individually.

```typescript
// (...)

room.state.players.onAdd(function (player, sessionId) {
  // (...)
  player.onChange(function () {
    playerEntities[sessionId].position.set(player.x, player.y, player.z);
  });

  // Alternative, listening to individual properties:
  // player.listen("x", (newX, prevX) => console.log(newX, prevX));
  // player.listen("y", (newY, prevY) => console.log(newY, prevY));
  // player.listen("z", (newZ, prevZ) => console.log(newZ, prevZ));
});

// (...)
```

> Read [more about Schema callbacks](https://docs.colyseus.io/colyseus/state/schema/#client-side)

<Playground id="#JMA5FE#2" title="Updating player's position Example" description="This example update players positions without interpolation" image="/img/resources/networking/colyseus/playground.png"/>

### Interpolating the player's position

To enable position interpolation, we're going to use the [Render Loop](/features/featuresDeepDive/animation/render_frame_animation) and the [`Scalar.Lerp()`](/typedoc/classes/babylon.scalar#lerp) method.

Instead of updating the player position directly (as in [previous section](#updating-players-visual-representation)), we are going to cache the next position, and constantly interpolate each player position during the Render Loop:

```typescript
// (...)
var playerNextPosition = {};

room.state.players.onAdd(function (player, sessionId) {
  // (...)
  playerNextPosition[sessionId] = sphere.position.clone();

  player.onChange(function () {
    playerNextPosition[sessionId].set(player.x, player.y, player.z);
  });
});
// (...)
```

And finally, the Render Loop:

```typescript
scene.registerBeforeRender(() => {
  for (let sessionId in playerEntities) {
    var entity = playerEntities[sessionId];
    var targetPosition = playerNextPosition[sessionId];
    entity.position = BABYLON.Vector3.Lerp(entity.position, targetPosition, 0.05);
  }
});
```

<Playground id="#RAG7FE#27" title="Full example with player interpolation" description="Full example with player position interpolation" image="/img/resources/networking/colyseus/playground.png"/>

## Extra: Monitoring Rooms and Connections

Colyseus comes with an optional monitoring panel that can be helpful during the development of your game.

To view the monitor panel from your local server, go to [http://localhost:2567/colyseus](http://localhost:2567/colyseus).

![monitor](/img/resources/networking/colyseus/monitor.png)

You can see and interact with all spawned rooms and active client connections through this panel.

> See [more information about the monitor panel](https://docs.colyseus.io/colyseus/tools/monitor/).

## More

We hope you found this tutorial useful, if you'd like to learn more about Colyseus please have a look at the [Colyseus documentation](https://docs.colyseus.io/), and join the [Colyseus Discord community](https://discord.gg/RY8rRS7).

[1]: https://github.com/colyseus/tutorial-babylonjs-client/


![Wireframe](/img/resources/networking/colyseus_ammojs/d1.gif)

This guide will help you realize the synchronization of network physical effects based on colyseus. This is a very simple demonstration. It does not include any server verification. Collision and detection only occur on the player's client. The server is responsible for synchronizing the data of physical effects and allocating the permissions of physical calculation;

We use ammojs as the physical engine for this demonstration, and you can also replace it with other physical engines;


## Full source code

- [colyseus-babylonjs-ammojs](https://github.com/renjianfeng/colyseus-babylonjs-ammojs)

## Before you start

#### Prior Knowledge Expected

-  ([Using A Physics Engine](https://doc.babylonjs.com/divingDeeper/physics/usingPhysicsEngine))
-  ([Real-time Multiplayer with Colyseus](https://doc.babylonjs.com/guidedLearning/multiplayer/Colyseus))


## Quick demo

Please clone this project and follow the instructions to install and start the project:
[colyseus-babylonjs-ammojs](https://github.com/renjianfeng/colyseus-babylonjs-ammojs)

#### Client application

To be able to build the client application, you'll need to enter in the folder,
and install its dependencies first.

```
cd client/
npm install
```

Now you can build and run it by running:

```
npm start
```

It will spawn the `webpack-dev-server`, listening on [http://localhost:8080](http://localhost:8080).


#### Server application

For the server, the steps are exactly the same. Install the dependencies:

```
cd server/
npm install
```

Now you can build and run it by running:

```
npm start
```

It will spawn a web socket server, listening on [ws://localhost:2657](ws://localhost:2657).

## Explanation of overall implementation logic
The red mesh calculates the physical effects locally of the current user, and the green mesh calculates the physical effects on the clients of other players, and then synchronizes them through colyseus.

the sphere represents the player character, and the cube represents the interactive objects in the scene.

The first player to enter the scene is responsible for the physical calculation of the cube, and other players are responsible for receiving data and rendering. When other players collide with the cube, the physical calculation of the cube is transferred to the collided players. You can distinguish these changes by color, just like the difference between green and red mentioned above

Yes, that's it

## Code implementation demonstration

#### Character control and network synchronization

First, we create a box and ground, and add physics to it,the ground represents the scene, and the box represents the interactive objects in the scene (such as a football played by many people)

```javascript
scene.enablePhysics(new BABYLON.Vector3(0, -10, 0), new AmmoJSPlugin(true, Ammo));
var ground = BABYLON.Mesh.CreateGround("ground1", 160, 160, 2, scene);
ground.position.y=-5
ground.physicsImpostor = new BABYLON.PhysicsImpostor(ground, BABYLON.PhysicsImpostor.BoxImpostor, { mass: 0, friction: 0.5, restitution: 0.7 }, scene);

var box = BABYLON.Mesh.CreateBox("box", 2, scene);
box.position.y = 1;
box.physicsImpostor = new BABYLON.PhysicsImpostor(box, BABYLON.PhysicsImpostor.BoxImpostor, { mass: 1, restitution: 0.9 }, scene);
box.material = new BABYLON.StandardMaterial("s-mat", scene);
box.material.diffuseColor = new BABYLON.Color3(0, 0, 1);
box.material.emissiveTexture = new BABYLON.Texture("./src/grass.png", scene);
```
Players and other players, we will create character grid after they join the room

```javascript
client.joinOrCreate<StateHandler>("game").then(room => {
    const playerViews: {[id: string]: BABYLON.Mesh} = {};

    room.state.players.onAdd = function(player, key) {
        // Our built-in 'sphere' shape. Params: name, subdivs, size, scene
        playerViews[key] = BABYLON.Mesh.CreateSphere("sphere1", 16, 2, scene);
    }
});
```
Physical control of player characters through keyboard keys
```javascript
 // Keyboard listeners
     const keyboard = { x: 0, y: 0 };
    window.addEventListener("keydown", function(e) {
        if (e.which === Keycode.LEFT) {
            keyboard.x = -10;
        } else if (e.which === Keycode.RIGHT) {
            keyboard.x = 10;
        } else if (e.which === Keycode.UP) {
            keyboard.y = 10;
        } else if (e.which === Keycode.DOWN) {
            keyboard.y = -10;
        }
        playerViews[sessionId].physicsImpostor.setLinearVelocity(new BABYLON.Vector3(keyboard.x, 0, keyboard.y))
    });

    window.addEventListener("keyup", function(e) {
        if (e.which === Keycode.LEFT) {
            keyboard.x = 0;
        } else if (e.which === Keycode.RIGHT) {
            keyboard.x = 0;
        } else if (e.which === Keycode.UP) {
            keyboard.y = 0;
        } else if (e.which === Keycode.DOWN) {
            keyboard.y = 0;
        }

        playerViews[sessionId].physicsImpostor.setLinearVelocity(new BABYLON.Vector3(0, 0, 0))
       
    });
```
In runrenderloop, the rotation and position data of each frame of the player are sent to the server
```javascript
engine.runRenderLoop(function() {
    if(room&&playerViews[sessionId]){
        room.send('playData', {
            position:{
            x: playerViews[sessionId].position.x,
            y: playerViews[sessionId].position.y,
            z: playerViews[sessionId].position.z},
            quaternion:{
            x:playerViews[sessionId].rotationQuaternion.x,
            y:playerViews[sessionId].rotationQuaternion.y,
            z:playerViews[sessionId].rotationQuaternion.z,
            w:playerViews[sessionId].rotationQuaternion.w}
        });
    }
});
```
Broadcast the position and rotation data submitted by players in the server
```javascript
  onCreate (options) {
   //...
    this.onMessage("playData", (client, message) => {
        this.state.players.get(client.sessionId).playerData = message;
    });  
   //...
  }
  onUpdate () {
    //...
    this.state.players.forEach((player, sessionId) => {
        player.position.x = player.playerData.position.x
        player.position.y = player.playerData.position.y
        player.position.z = player.playerData.position.z

        player.quaternion.x = player.playerData.quaternion.x
        player.quaternion.y = player.playerData.quaternion.y
        player.quaternion.z = player.playerData.quaternion.z
        player.quaternion.w = player.playerData.quaternion.w
    });
      //...
  }
```
Update the position and rotation of other players through the broadcast rotation data;

Note: to prevent jitter caused by linear speed, position will be directly used to lock the position when the target is close enough to the broadcast position.
```javascript
player.position.onChange = () => {
    if(key != room.sessionId){
          if( Math.abs(playerViews[key].position.x)<0.2
          &&Math.abs(playerViews[key].position.y)<0.5
          &&Math.abs(playerViews[key].position.x)<0.2)
          {
              playerViews[key].position=new BABYLON.Vector3(
                player.position.x, 
                player.position.y, 
                player.position.z
              )
          }else{
              playerViews[key].physicsImpostor.setLinearVelocity(
                  new BABYLON.Vector3((player.position.x-playerViews[key].position.x)*10,
                  (player.position.y-playerViews[key].position.y)*10,
                  (player.position.z-playerViews[key].position.z)*10))

              playerViews[key].rotationQuaternion=BABYLON.Quaternion.Slerp(
                playerViews[key].rotationQuaternion,
                new BABYLON.Quaternion(
                  player.quaternion.x, 
                  player.quaternion.y, 
                  player.quaternion.z,
                  player.quaternion.w)
              ,0.4)
          }
    }
};
```
Now, the control of our players' characters and network synchronization are completed. Next, we will continue to realize the interaction of scene objects;

#### Physical interaction of scene objects(Multiplayer football)

We are in 'GameRoom.ts' create a variable "boxData" in the file to save the position and rotation data of the box, where "targetId" represents the "sessionId" of the player responsible for the physical calculation and hosting of the box; at the same time, you need to receive the box data sent by the player client and broadcast it to other players.
```javascript
export class GameRoom extends Room {
    maxClients = 8;
    boxData={
        targetId:null,
        position:null,
        quaternion:null
    }
    //...
    onCreate (options) {
        //...
        this.onMessage("boxUpdate", (client, message) => {
            this.boxData= message;
        });
    }
    onUpdate () {
        this.broadcast("boxUpdate",this.boxData)
        //...
    }
}
```

We declare a variable "isUpdateBox" to record whether the local player character is responsible for the physical collision of the box. If the targetid value broadcast by the server is null or the targetid is equal to the sessionid of the local player, the local player will immediately take over the physical collision. Otherwise, the position and rotation of the box will use the data broadcast by the server
```javascript
let isUpdateBox=false;

 room.onMessage("boxUpdate", (message) => {
    if(message.targetId==null||message.targetId==sessionId){
        isUpdateBox=true
        box.material.diffuseColor. = new BABYLON.Color3(1, 0, 0);
    }else{
        isUpdateBox=false
        box.material.diffuseColor = new BABYLON.Color3(0, 1, 0);
        box.position= BABYLON.Vector3.Lerp(
          box.position,
          new BABYLON.Vector3(
            message.position.x, 
            message.position.y, 
            message.position.z
          ),  
          0.5)
        box.rotationQuaternion=BABYLON.Quaternion.Slerp(
          box.rotationQuaternion,
          new BABYLON.Quaternion(
            message.quaternion.x, 
            message.quaternion.y, 
            message.quaternion.z,
            message.quaternion.w
          ),
          0.4)
    }
});

 engine.runRenderLoop(function() {
    if(room&&playerViews[sessionId]){
        // ...
        if(isUpdateBox){
            room.send('boxUpdate', {
                targetId:sessionId,
                position:{
                  x: box.position.x,
                  y: box.position.y,
                  z:box.position.z
                },
                quaternion:{
                  x:box.rotationQuaternion.x,
                  y:box.rotationQuaternion.y,
                  z:box.rotationQuaternion.z,
                  w:box.rotationQuaternion.w
                }
            });
        }
    }
});
```
If other players collide with the box, the targetid will be replaced by the sessionid of other players. Correspondingly, the physical collision permission will also be transferred to other players.
```javascript
if (key === room.sessionId) {
    //...
    box.physicsImpostor.registerOnPhysicsCollide( 
      playerViews[sessionId].physicsImpostor, 
      function(main, collided) {
        room.send('boxUpdate', {
            targetId:sessionId,
            position:{x: box.position.x,y: box.position.y,z:box.position.z},
            quaternion:{x:box.rotationQuaternion.x,y:box.rotationQuaternion.y,z:box.rotationQuaternion.z,w:box.rotationQuaternion.w}
        });
    });
}else{
    //...
}
```
Now, we have completed all the functions!!!

## Please enjoy the final effect
![Wireframe](/img/resources/networking/colyseus_ammojs/d2.gif)

## Homework
There is a small bug in this demo, that is, when the player responsible for the physical operation of the box quits the game, the box is suspended in the air due to the loss of the computing console. In this case, you need to switch the console of the box to other players. Please try to implement this function in the case code.


## Networking

In this section, you can learn how to create networked Babylon.js experiences such as multiplayer games or remote multi-user interactions.



![Vite + Babylon.js Combo Logo](/img/how_to/using-vite/01.png)

## What is Vite and why do you need it?

[Vite](https://vitejs.dev/) is a modern development environment that bundles & optimizes your code, launches local test servers instantly, automates more project configurations out-of-the-box, and contains other quality-of-life improvements. In other words, it's an all-in-one tool that lets you develop Babylon.js projects on your computer locally and with ease. It's intended to replace Webpack, which has a similar goal as Vite but requires more work and maintenance (especially with its config files.)

Whether you're ready to graduate from playing with example projects in the [Playground](https://playground.babylonjs.com/), or if you're already a seasoned developer looking to upgrade your software stack, this guide can benefit any of your future Babylon.js projects!

## Leaving the Playground with VSCode & npm

***You can skip to Step 3 if you already have a code editor and npm installed.*** Otherwise, it's time to finally leave the Playground and learn how to create Babylon.js projects that you can publish and share anywhere. This is usually done with a code editor, a program that helps you write and manage your projects.

**(1)** Install a code editor. This tutorial will be using [Visual Studio Code](https://code.visualstudio.com/) *(or [VSCodium](https://vscodium.com/))* but you can still follow along if you want to use a different one.

![VSC](/img/how_to/using-vite/02.png)

Your code editor may look something like this when opened.

**(2)** Close your code editor and install Node.js with [one of these installers](https://nodejs.dev/en/download/) (or via your package manager if you use Linux.) Installing this gives us access to [npm](https://www.npmjs.com/), a library of Node.js packages to help you build web-based apps and keep them up-to-date. This is how we're going to install Babylon.js and Vite.

![npm test](/img/how_to/using-vite/03.png)

You'll know if you did it right by opening Command Prompt on Windows (or Terminal on macOS/Linux) and writing `npm -v`. If the output is a version number, you're good to go.

## Setting up Vite & Babylon.js

Once you have your code editor and Node.js installed, we can begin setting up your development folder.

**(3)** Create a folder on your computer wherever you want to store your Babylon.js projects, and open it in your code editor using the menu `File` > `Open Folder`. If prompted, click on "Yes, I trust the authors." You should now have a sidebar on your left like this:

![npm test](/img/how_to/using-vite/04.png)

**(4)** Toggle the terminal using the menu `View` > `Terminal` and enter the following commands one after the other:

- `npm i vite` *(`i` is short for `install`)*
- `npm i -D @babylonjs/core`  *(`-D` is short for `--save-dev`)*
- `npm i -D @babylonjs/inspector`

This installs Vite and some of Babylon.js' features in your created folder (in a subdirectory called `node_modules`.)

**(5)** Now enter the command `npm init vite`. Enter the name of your Babylon.js project, such as `testProj` or whatever name you want. You can also set a package name, but the default one works fine. Choose "Vanilla" from the list that pops up, and then choose "TypeScript." (This setup also works with JavaScript, but with slightly different steps not documented here.)

![folder structure with vanilla Vite](/img/how_to/using-vite/05.png)

Look at that! We have a new folder containing a Vite template project. You can rename the folder if you want.

## Configuring a test project

Now let's turn our vanilla Vite folder into an example Babylon.js project that you can use as a foundation for your future Vite & Babylon.js projects.

**(6)** Right-click your new folder in the left-hand side and choose `Open in Integrated Terminal`. A second tab in your terminal will open, which is pointing to your newly-generated project folder.

![new tab](/img/how_to/using-vite/06.png)

*Note to advanced users: The reason why we didn't just `cd` into the new folder is because it's convenient to have both the root and project folders open as separate tabs in our Terminal. Doing this lets us maintain our packages in the root folder separately from the project subfolder. We can install our necessary packages once in the root folder, and reference them freely in the code inside our project subfolders. NPM is smart enough to detect any packages installed in parent folders- you don't have to directly install them inside your project root directories. This is a good habit to get into instead of maintaining multiple copies of Vite and Babylon.js installed in every single project folder, resulting in wasted storage space. Feel free to deviate from this structure if you'd like, though.*

**(7)** Now enter the following commands in the terminal:

- `npm i`
- `npm run dev`

The first command updates the Vite packages in your project root folder that still need to be directly in there, and the second one tells Vite to run a server that tests your current code.

**(8)** Your terminal should now say that Vite is currently running. Ctrl+click on the localhost: URL to view your test server inside your browser.

![Vite success](/img/how_to/using-vite/07.png)

If you see this screen, good job! The foundation of our Vite project is set up. Now let's make it run Babylon.js.

**(9)** Go back to your Terminal and press Ctrl+C to stop the server. (Don't forget that keyboard shortcut.) 

Now use the left-hand sidebar (and some right-clicking) to do the following:

- Delete everything inside the `public` and `src` folders
- Create a new file inside `src` called `app.ts`
- Double-click on `index.html` and `tsconfig.json`

![file tabs](/img/how_to/using-vite/08.png)

You should now have all three of these files open.

**(10)** Copy the contents of the three code blocks below and paste them into their respective files. Save each file (Ctrl+S) after you do this.

![Picture of a file](/img/how_to/using-vite/09.png)

This code for **app.ts** is a test scene of a sphere from [another Babylon.js tutorial](https://doc.babylonjs.com/guidedLearning/createAGame/gettingSetUp). Notice how the `import` statements at the top allow the rest of the code to function: 

```typescript
import "@babylonjs/core/Debug/debugLayer";
import "@babylonjs/inspector";
import { Engine, Scene, ArcRotateCamera, Vector3, HemisphericLight, Mesh, MeshBuilder } from "@babylonjs/core";

class App {
    constructor() {
        // create the canvas html element and attach it to the webpage
        var canvas = document.createElement("canvas");
        canvas.style.width = "100%";
        canvas.style.height = "100%";
        canvas.id = "gameCanvas";
        document.body.appendChild(canvas);

        // initialize babylon scene and engine
        var engine = new Engine(canvas, true);
        var scene = new Scene(engine);

        var camera: ArcRotateCamera = new ArcRotateCamera("Camera", Math.PI / 2, Math.PI / 2, 2, Vector3.Zero(), scene);
        camera.attachControl(canvas, true);
        var light1: HemisphericLight = new HemisphericLight("light1", new Vector3(1, 1, 0), scene);
        var sphere: Mesh = MeshBuilder.CreateSphere("sphere", { diameter: 1 }, scene);

        // hide/show the Inspector
        window.addEventListener("keydown", (ev) => {
            // Shift+Ctrl+Alt+I
            if (ev.shiftKey && ev.ctrlKey && ev.altKey && ev.keyCode === 73) {
                if (scene.debugLayer.isVisible()) {
                    scene.debugLayer.hide();
                } else {
                    scene.debugLayer.show();
                }
            }
        });

        // run the main render loop
        engine.runRenderLoop(() => {
            scene.render();
        });
    }
}
new App();
```

This code for **index.html** contains the title that will appear in the browser title bar, as well as a `<script>` tag to tell Vite which file has the main code to start our project, which is `app.ts` in our case:

```html
<!DOCTYPE html>
<html>
    <head>
        <meta charset="UTF-8">
        <title>Title of Your Project</title>
    </head>
    <body>
       <script type="module" src="./src/app.ts"></script>
    </body>
</html>
```

This code for **tsconfig.json** is a slimmed-down combination between the default Vite file and the one from that other Babylon.js tutorial mentioned earlier. Each line roughly explains what each setting does. (Note that JSON files normally don't allow you to insert comments like this example here, but tsconfig.json in particular does.) You can read the [TypeScript docs](https://www.typescriptlang.org/tsconfig) if you want to learn more:

```json
{
  "compilerOptions": {
    "target": "es6", // choose our ECMA/JavaScript version (all modern browsers support ES6 so it's your best bet)
    "lib": [ // choose our default ECMA/libraries to import
      "dom", // mandatory for all browser-based apps
      "es6" // mandatory for targeting ES6
    ],
    "useDefineForClassFields": true, // enable latest ECMA runtime behavior with older ECMA/JavaScript versions (delete this line if target: "ESNext" or "ES2022"+)
    "module": "ESNext", // use the latest ECMA/JavaScript syntax for our import statements and such
    "moduleResolution": "node", // ensures we are using CommonJS for our npm packages
    "noResolve": false, // disable TypeScript from automatically detecting/adding files based on import statements and etc (it's less helpful than you think)
    "isolatedModules": true, // allows our code to be processed by other transpilers, such as preventing non-module TS files (you could delete this since we're only using base TypeScript)
    "removeComments": true, // remove comments from our outputted code to save on space (look into terser if you want to protect the outputted JS even more)
    "esModuleInterop": true, // treats non-ES6 modules separately from ES6 modules (helpful if module: "ESNext")
    "noImplicitAny": false, // usually prevents code from using "any" type fallbacks to prevent untraceable JS errors, but we'll need this disabled for our example code
    "noUnusedLocals": false, // usually raises an error for any unused local variables, but we'll need this disabled for our example code
    "noUnusedParameters": true, // raises an error for unused parameters
    "noImplicitReturns": true, // raises an error for functions that return nothing
    "skipLibCheck": true // skip type-checking of .d.ts files (it speeds up transpiling)
  },
  "include": ["src"] // specify location(s) of .ts files
}
```

**(11)** Run `npm run dev` in your terminal and Ctrl+click the localhost: link again.

![Babylon & Vite ready](/img/how_to/using-vite/10.png)

🎉 YOU DID IT!! You just successfully created a local development environment for Babylon.js using Vite!

## Maintenance and updates

**HOWEVER,** before you continue your Babylon.js journey with your shiny new setup, here's some basic upkeep you'll have to keep in mind:

- You should occasionally run `npm up` *(short for `update`)* in the first terminal tab, which is the one for the main folder above your projects. This keeps Vite and Babylon.js updated.
- If you need to uninstall a package from Step 4 or otherwise, run `npm un <packageNameHere>` *(short for `uninstall`)* in that same main folder or terminal tab.
- Static assets such as images or 3D models should go in the `public` folder. These can then be referenced as if they're in the root folder `"./likethis.png"`.
- If you ever get stuck, reach out to [the Babylon forums](https://forum.babylonjs.com/) for help.

And that's it- you can go code now!

## Building and sharing online

...But let's say you finished making a project and you want to share it with the rest of the world. It's time to take advantage of Vite's bundling abilities and export your code into lightweight JS for the web!

Here's how:

- Make sure all your non-code assets (images, 3D models, etc.) are in the `public` folder to ensure that they end up in the final bundle.
- If it's not already open as a tab, right-click on your project's folder (not the main one) and choose `Open in Integrated Terminal`. Or just click on your second Terminal tab if you still have it.
- Run this command: `npm run build`
- Your exported code bundle is now in a folder called `dist`. Check if it works by running: `npm run preview`
- **IMPORTANT:** Once you verify this test works, open `dist/index.html` and look for any file paths that point to root with `/`. Add a period in front of all of those root paths (meaning `/assets` would become `./assets`) and save the file.

![Final dist folder](/img/how_to/using-vite/11.png)

NOW you can upload the contents of your `dist` folder to a host like GitHub Pages or Vercel to share it with the world! It'll run way faster than a project from the Playground since the code bundle only includes the parts of Babylon.js that you need, instead of the entire engine.

*Note to advanced users: if you really want to push the limits of Vite and its bundling capabilities, you can look into using Dynamic `import` Statements. This feature allows you to put import statements inside functions instead of at the top of your code, which helps reduce the overall size of your exported bundle via code-splitting. I haven't tried this feature myself, but [this overview video](https://www.youtube.com/watch?v=kwUfeWe7DCw) from Beyond Fireship is a great place to start exploring this workflow if you're interested.*

*Note to existing Vite users: you might've noticed that I instructed users to put all static assets in the `public` folder, instead of using URL-holding variables that come from having every asset as an `import` statement, as specified in [the Vite documentation](https://vitejs.dev/guide/assets.html#importing-asset-as-url). This is because we don't really have to do this when Babylon.js projects contain heavy assets like 3D models by default. The obscured filenames that result from using the Vite docs' method don't really prevent the end user from ripping assets from Babylon.js projects either. If you still want to use this "Importing Assets as URLs" workflow anyway, do note that you'll have to create a `.d.ts` file in your `src` folder and figure out [this code snippet](https://stackoverflow.com/questions/51100401/typescript-image-import#answer-51163365) to get it to work with TypeScript. As you can probably tell, I also haven't tested this method.*

## Credits

This tutorial was originally a [forum post](https://forum.babylonjs.com/t/how-to-vite-with-babylon-js-game-tutorial-series/33845) I wrote to replace Webpack in capucat's [Create A Game Tutorial Series](https://doc.babylonjs.com/guidedLearning/createAGame), but I was told to turn it into an article for the docs, so here we are. Thank you PirateJC for requesting this write-up! I think it turned out great.

***Written by [wavetro](https://wavetro.net/)***

*Last updated: 2022-SEP-22*


Networking

Networking

Coming next

Real-time Multiplayer with Colyseus

Learn to develop multiplayer experiences with Colyseus

Network Physical Synchronization (based on ammojs + colyseus)

Learn to develop Network Physical Synchronization by colyseus