
# Using the Playground in Development of BJS

During the early stages of developing code to contribute to Babylon.js, it can be useful to try that code in the Playground. Just ensure that the Playground is in TypeScript mode by using the link https://www.babylonjs-playground.com/ts.html#. The `New` button will then give you the starting code.

## An Example

Babylon.js has code to create a Bezier curve at https://github.com/BabylonJS/Babylon.js/tree/master/packages/dev/core/src/Maths/math.path.ts (just search for `Curve3` on this page), so it would make sense to put any code to create a Bezier surface in the same file.

The first step is to produce code that works. You can, of course, immediately follow the steps in [how to start contributing](/contribute/toBabylon/HowToContribute), and before submitting a PR there will need to be working code, as described on this page. However, you might not yet be confident with the full process of forking the code, using Git, setting up an IDE, and creating pull requests, even if you are familiar with using TypeScript.

So, an alternative is to try out the code in the Playground. The following Playground shows the TypeScript code for a Bezier surface being developed in the Playground.

<Playground id="H3AF26#1" title="Playground Code Example - Bezier Surface" description="Simple playground example of a Bezier Surface." image="/img/playgroundsAndNMEs/divingDeeperUsingPlaygrounds1.webp"/>

Though this shows working code, it is not completely ready to be copied into a local Babylon.js repository, committed, and submitted as a PR. For a start, not all the needed comments are in place.

Also once placed in the local repository the first line

```javascript
class BezierSurface {
```

would need to be changed to

```javascript
export class BezierSurface {
```


## From Playground to Pull Request

Once you are happy that the code works and have copied it to your local repository, please read the following before submitting your PR to help ensure a smooth, positive result.

[Start Contributing](/contribute/toBabylon/HowToContribute)
[Contributing Read Me](https://github.com/BabylonJS/Babylon.js/blob/master/contributing.md)
[Code Guidelines](/contribute/toBabylon/approvedNamingConventions)
[Comments in the API](/contribute/toBabylon/contributeToAPI)

On the other hand, there is always the possibility that someone on the core team will like your idea and its execution so much that they might just copy it into Babylon.js directly.



## Overview

The Babylon.js Sandbox is a powerful, web-based 3D asset viewer and debugging tool for developers and designers working with Babylon.js. It allows users to load and inspect 3D models, textures, animations, and materials with an intuitive interface. The Sandbox is an essential utility for testing and fine-tuning assets before integrating them into a Babylon.js project.

## Features

- **Model Preview**: View and interact with 3D models in real-time.
- **Supported File Formats**: `.gltf`, `.glb`, `.obj`, `.stl`, `.babylon`, `.bvh`, `.ply`, `.sog`, `.splat`, `.spz`
- **Animation Playback**: Play, pause, and scrub through animations.
- **Environment Map Support**: Select built-in or load custom environment textures for realistic lighting.
- **Inspector Integration**: Explore detailed object properties like meshes, lights, cameras, and more.

## Accessing the Sandbox
1. Open a web browser.
2. Visit the Sandbox at [sandbox.babylonjs.com](https://sandbox.babylonjs.com).

## Installing as a Desktop App
The Sandbox can be installed as a Progressive Web App (PWA) for a native desktop experience. Once installed, the Sandbox also registers itself as a file handler for supported file formats, allowing you to open 3D assets directly from your file system. The PWA also supports offline mode, so you can view and inspect your 3D assets without an internet connection.

### Installation
1. Visit [sandbox.babylonjs.com](https://sandbox.babylonjs.com) in a supported browser (e.g., Chrome, Edge).
2. Click the install icon in the browser's address bar or use the browser menu to install the app.
3. The Sandbox will be available as a standalone application on your desktop.

### File Handler
After installation, the Sandbox registers as a handler for supported file formats (`.gltf`, `.glb`, `.obj`, `.stl`, `.babylon`, etc.). This enables:
- **Double-click to open**: Double-click a supported 3D file to open it directly in the Sandbox.
- **Open with**: Right-click a file and select the Sandbox from the "Open with" menu.

This integration provides a seamless workflow for quickly previewing 3D assets without needing to manually drag and drop files into a browser window.

## Loading Assets
Load assets into the Sandbox using one of the following methods:
- **Drag and Drop**: Drag supported files directly onto the Sandbox interface.
- **File Selection**: Use the open button on the toolbar to browse the file system and load assets.

Note that all required assets, including files referenced from the main asset file, must be dropped or
selected so that the browser knows about them. For example, if the asset is a glTF, the `.bin` file and
all image files must be dropped or selected for the asset to load properly.

## User Interface

### Toolbar
The toolbar at the bottom provides quick access to common tasks:
- **Animation Controls**: Play, pause, and scrub animations when animations are available.
- **Display inspector**: Opens the Inspector for detailed analysis.
- **Select environment**: Change environment lighting.
- **Open your scene**: Opens files from the local file system.

### Special Keys
- `R` - Reloads the current asset
- `Space` - Toggles the toolbar

## Advanced

### Custom Environment
Drag and drop an HDR environment map to test lighting and reflections on the loaded asset.

### URL Parameters
The sandbox URL accepts a query string to load a specific asset or configure settings. This is particularly useful when sharing an asset with a link so that the asset is presented with a specific configuration. Below are the available parameters.

_Parameter names and values are case-insensitive if possible._

- `asset` - The asset URL to load automatically.
- `autoRotate` - Set to `true` to turn on auto rotation of the active camera. Auto rotation is off by default.
- `camera` - The active camera index to use from the loaded scene.
- `cameraPosition` - The comma-separated `x,y,z` position of the active camera.
- `clearColor` - The clear color for the loaded scene in hex form (e.g., `FFFFFF` for pure white).
- `environment` - The environment URL to load for glTF assets. This parameter is ignored for other asset formats.
- `kiosk` - Set to `true` to hide the toolbar. The toolbar is visible by default.
- `skybox` - Set to `false` to not create a skybox for glTF assets. Skyboxes are created by default for glTF assets. This parameter is ignored for other asset formats.
- `toneMapping` - The tone mapping (`Standard`, `ACES`, `KHR_PBR_Neutral`) to use for the loaded scene.

#### Examples
- Load a specific URL  
  https://sandbox.babylonjs.com/?asset=https://assets.babylonjs.com/meshes/boombox.glb
- Hide the toolbar and auto rotate the camera  
  https://sandbox.babylonjs.com/?asset=https://assets.babylonjs.com/meshes/boombox.glb&kiosk=true&autorotate=true
- Use a specific environment  
  https://sandbox.babylonjs.com/?asset=https://assets.babylonjs.com/meshes/boombox.glb&environment=https://assets.babylonjs.com/environments/studio.env
- Use the Khronos PBR Neutral tone mapping and set the camera to a specific position  
  https://sandbox.babylonjs.com/?asset=https://raw.githubusercontent.com/KhronosGroup/glTF-Sample-Assets/main/Models/DragonDispersion/glTF/DragonDispersion.gltf&toneMapping=khr_pbr_neutral&cameraPosition=-0.13,1.64,3.4



## What is the Snippet Server?

The Snippet Server is the content server used by the Babylon library. Whenever you save a Playground, an animation, or a node material and get a unique URL pointing to your content, HTTP requests are sent to the Snippet Server. However, the default server we use does not have authentication, which means anyone with this unique URL can access your content. It is also closed source, so it is not possible to run a local copy. If you want to run your own private server, you will have to implement it yourself. This page explains one example implementation.

## Making your own Snippet Server

To see the minimum expected from a Snippet Server, take a look at this reference [implementation](https://github.com/BabylonJS/SnippetServerReference). It was written in Node.js and Express, which are JavaScript-based like Babylon itself, but you could implement your server in any language you prefer, such as Python or Go. You only need to implement two API calls. It also uses the file system to store snippet files, which is simple to implement but not the safest option. Feel free to modify it to suit your needs.

In this reference implementation, the snippets are stored in a directory called `data`, while another directory, called `metadata`, stores the latest version of each snippet ID. What are a "snippet ID" and a "version"? If you look at any URL that is saved in our tools, you can see that it has two parts:

![Example of a snippet ID: https://playground.babylonjs.com/#CBGEQX#2, with a red arrow pointing from the section "CBGEQX" to the words "snippet ID" and a blue arrow pointing from the number 2 to the word "version" ](/img/tools/Playground/snippet_url.webp)

In the example `https://playground.babylonjs.com/#CBGEQX#2`, the section `CBGEQX#2` is the snippet URL. Everything before the `#` is the snippet ID, and the number after it is the snippet version. The first version of a snippet may not have an explicit version number. We use a 5-character string for our snippet IDs, but that is not a requirement. You do need to have the `#<version>` section, though.

## Saving a snippet

When saving a snippet, such as when you click the "Save" button in the Playground, a [HTTP POST](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST) request is sent to the server. It may not contain an ID, in which case a new ID will be created and it will be the first version, or it may contain an ID, in which case a new version is created for that ID. You can see this in action here:

```javascript
app.post("/:id?", (req, res) => {
    let id = req.params.id;
    let version;

    if (!id) {
        // Generate "random" 5 character string
        const genRndChar = () => {
            const idx = Math.floor(Math.random() * chars.length);
            return chars[idx];
        };

        id = "";
        for (let i = 0; i < ID_LEN; i++) {
            id += genRndChar();
        }
    }

    const metadataPath = METADATA_DIR + id + METADATA_EXT;
    // Look for the latest version in the metadata directory. If there is no metadata file, then it is the first version.
    if (fs.existsSync(metadataPath)) {
        version = fs.readFileSync(metadataPath, {encoding: 'utf-8'});
        // Increment the version and convert back to string
        version = Number.parseInt(version) + 1;
        version = version + "";
    } else {
        version = "1";
    }

    const newLocalToken = id + LOCAL_SEPARATOR + version;
    
    fs.writeFileSync(metadataPath, version);

    const filePath = DATA_DIR + newLocalToken + FILE_EXT;
    const stringBody = JSON.stringify(req.body);
    fs.writeFileSync(filePath, stringBody);
    
    res.status(200).json({
        id,
        version
    });
});
```

The request body itself is JSON containing the following attributes:

* payload: That's the content itself in the form of a string, which may be a JavaScript/TypeScript code string in the case of the Playground, or a JSON string in the case of Animations.
* name
* description
* tags

The response body is also a JSON, and should contain the snippet ID and snippet version as attributes.

## Retrieving a snippet

When retrieving a snippet, a [HTTP GET](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/GET) request is sent to the Snippet Server, containing at least the ID of the snippet and possibly its version. You can see this in action here:

```javascript
app.get("/:id/:version?", (req, res) => {
    const id = req.params.id;
    const version = req.params.version || "1";
    
    const localToken = id + LOCAL_SEPARATOR + version;
    const path = DATA_DIR + localToken + FILE_EXT;
    
    if (fs.existsSync(path)) {
        const rawData = fs.readFileSync(path);
        const parsedData = JSON.parse(rawData);
        
        res.status(200).json({
            name: parsedData.name,
            description: parsedData.description,
            tags: parsedData.tags,
            jsonPayload: parsedData.payload
        });
    } else {
        res.status(404).send();
    }
});
```

The response returned to the Babylon tools is JSON in almost the same format as the POST body, with only one difference: the "payload" attribute is named "jsonPayload".

And that is all you need for your own Snippet Server. You can also add more features, such as deletion, authentication, and search.

## Using your server on Babylon

Now that you have a server up and running, you will want to point your Babylon library and tools to it. You can do this by [making a copy of the Babylon repository locally](/contribute/toBabylon/HowToContribute) and changing instances of the URL "https://snippet.babylonjs.com" to your own Snippet Server URL. You can use the same server instance for every case, or you can use separate instances with separate URLs for different purposes, such as Node Material or Animation. To make these URLs easier to find, you can use the "CTRL+SHIFT+F" shortcut in Visual Studio Code (if that is your IDE of choice):

![Example of using the Search function of Visual Studio Code to search for "https://snippet.babylonjs.com"](/img/tools/Playground/snippet_search.webp)

## A Note About CORS

Depending on your browser of choice, your calls to the Snippet Server may be blocked by [CORS policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS), so you'll need to add the [Access-Control-Allow-Origin](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#access-control-allow-origin) header to your responses. The easiest way to do that in Express is using the [CORS Middleware](https://expressjs.com/en/resources/middleware/cors.html).


Using the Playground for Development in Babylon.js

An Example

From Playground to Pull Request