
# Using External Assets in the Playground

Sometimes you might want to load you own assets into the playground. Should the reason for doing so be to get help with a feature please think carefully before doing so.

It is very likely that the issue you are struggling with can be isolated and presented in a simplified and more focused form using basic meshes and existing [textures](/toolsAndResources/assetLibraries/availableTextures) and [models](/toolsAndResources/assetLibraries/availableMeshes).

Doing this will lead to quicker answers as your question will be more understandable, since few people want to work through long sections of code. Using the existing assets will also ensure that they remain reachable and the playgrounds you create will still be a useful resource in the future. However should you still wish to use your own assets then this page describes ways of doing so.

Any site hosting you assets must be [CORS compliant](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing) and use the secure [https](https://en.wikipedia.org/wiki/HTTPS) protocol.

## From github.com

### using raw.githubusercontent.com

- ensure that your git repo is set to **public**
- navigate to your file. We'll take as example https://github.com/BabylonJS/MeshesLibrary/blob/master/PBR_Spheres.glb
- remove `/blob/` part
- replace `https://github.com` by `https://raw.githubusercontent.com`
- you now have raw access to your file `https://raw.githubusercontent.com/BabylonJS/MeshesLibrary/master/PBR_Spheres.glb`

```javascript
BABYLON.ImportMeshAsync("https://raw.githubusercontent.com/BabylonJS/MeshesLibrary/master/PBR_Spheres.glb", scene);
```

 <Playground id="#YIU90M#1416" title="Using Assets From Github" description="Simple example of loading assets from github into the playground."/>

### using rawgit.com

You were able to use [GitHub](https://github.com/) with a link generated by the **[RawGit](https://rawgit.com/)** site to ensure correct MIME type. Unfortunately this site has now closed.

Any existing links to files using **RawGit** can be updated using **[Raw Git to jsDelivr](https://www.jsdelivr.com/rawgit)**. Changes should be made to **RawGit** links before October 2019.

### using jsdelivr.com

To use **[jsDelivr](https://www.jsdelivr.com)** with a file:

- ensure that your git repo is set to **public**
- let's say you have a file named _myFile.babylon_ on **github**, go to that file in your repository and click on the commit number.
- then in the address bar copy the part after `https://github.com/`, for example

```javascript
myGithubUserName/myRepository/commit/2bd79648e08709145cd9575e6679b2ea360f12f6
```

- replace `/commit/` with `@`

```javascript
myGithubUserName/myRepository@2bd79648e08709145cd9575e6679b2ea360f12f6
```

- add at the front `https://cdn.jsdelivr.net/gh/`

```javascript
https://cdn.jsdelivr.net/gh/myGithubUserName/myRepository@2bd79648e08709145cd9575e6679b2ea360f12f6
```

- _(optional)_ by adding the filename to the end, you now have direct download access

```javascript
https://cdn.jsdelivr.net/gh/myGithubUserName/myRepository@2bd79648e08709145cd9575e6679b2ea360f12f6/myFile.babylon
```

You now have all necessary data to load your meshes.

```javascript
BABYLON.ImportMeshAsync("https://cdn.jsdelivr.net/gh/myGithubUserName/myRepository@2bd79648e08709145cd9575e6679b2ea360f12f6/myFile.babylon", scene);
```

From our MeshesLibrary repo, [using PBR_Spheres.glb](https://github.com/BabylonJS/MeshesLibrary/commit/fa494961cbe0b8d44854b3cf8aa8268ba211741a):

 <Playground id="#IX12S2#139" title="Loading Assets From The Babylon.js Meshes Library" description="Simple example showing how to load assets from the Babylon.js meshes library."/>

## From Gitlab.com

### using GitLab pages

You have to configure your own [Gitlab pages](https://docs.gitlab.com/ee/user/project/pages/).

When done, just use the direct link in the loader:

```javascript
BABYLON.ImportMeshAsync("https://yourpages.gitlab.io/yourScene/myFile.babylon", scene);
```

## From dropbox.com

[Dropbox](https://dropbox.com) could be use both for playground debugging and easily sharing assets.

- upload your file
- click on `Share` button
- generate a public download link, here our example: `https://www.dropbox.com/s/rANdoMGeneR4tedLink/my-file.glb?dl=0`
- replace `www` in url by `dl`, also remove `?dl=0` at the end if this is the only argument
- there may also be an `rlkey` augument included which looks like `?dl=0&rlkey=rANdoMGeneR4tedValUe`, this argument needs to stay in the link, even if you remove the `dl=0&` first argument leaving `?rlkey=rANdoMGeneR4tedValUe`
- you now have a direct access url which will look like `https://dl.dropbox.com/s/rANdoMGeneR4tedLink/my-file.glb` if there was no `rlkey` parameter or `https://dl.dropbox.com/s/rANdoMGeneR4tedLink/my-file.glb?rlkey=rANdoMGeneR4tedValUe` if there is one

It can be used in this way:

```javascript
BABYLON.ImportMeshAsync("https://dl.dropbox.com/s/rANdoMGeneR4tedLink/my-file.glb", scene);
```

 <Playground id="#8LFTCH#14" title="Loading Assets From Dropbox" description="Simple example of loading assets from dropbox."/>

## From imgur.com

[Imgur](https://imgur.com) could be useful to quickly use custom textures.

- upload your image, here our example: https://imgur.com/a/KhuCTFr
- copy the direct link, here https://imgur.com/yn98ktz
- do a `right-click > View image` or add `i.` in front of `imgur.com` and image extension to the end of url, here https://i.imgur.com/yn98ktz.png
- use this direct access url in your playground

```javascript
var texture = new BABYLON.Texture("https://i.imgur.com/yn98ktz.png", scene);
```

 <Playground id="#UNEWTE" title="Loading Assets From Imgur" description="Simple example of loading assets from imgur."/>

## Embedded assets

You can make a raw text copy-paste of your assets, like the content of a .gltf file.

Note that you need to use `Append` so you can define the plugin to use as there is no more file extension.

```javascript
    var mymodel = {
        [...]
    };

    var json = JSON.stringify(mymodel);
    var blob = new Blob([json]);
    var url = URL.createObjectURL(blob);

    BABYLON.AppendSceneAsync(url, scene, {
        pluginExtension: ".gltf"
    }).then(function() {
        scene.createDefaultCameraOrLight(true, true, true),
        scene.createDefaultEnvironment();
    });
```

 <Playground id="#KEY4S4#93" title="Loading Embedded Assest" description="Simple example showing how to load embedded assets."/>

## Javascript files

For Javascript files you need to wait for the file to be loaded before attempting to access it.

```javascript
var url = "LINK ADDRESS";
var s = document.createElement("script");
s.src = url;
document.head.appendChild(s);

var createScene = function () {
  //Scene set up code

  s.onload = function () {
    //any code calling on loaded file code
  };

  return scene;
};
```

 <Playground id="#WF3VKZ" title="Loading Embeded Assets (javascript)" description="Another example of loading embedded assets."/>



## Using Playground Templates

With Babylon.js 4.2, you now have a handy new tool available in the playground. This tool allows you to hit `CTRL+Space` on your keyboard to bring up snippets handy bits of code. From loading a box, to exporting a .gltf file, some of the most commonly used code blocks are now available at the click of a button.

You can also use the `tab` button to quickly navigate to the next property in the code block to fill in.

## Contributing Playground Templates

If you'd like to add your own snippet of code to the available templates, you can do so by updating the playground templates configuration file in the engine.

[Playground Templates Config File](https://github.com/BabylonJS/Babylon.js/blob/master/packages/tools/playground/public/templates.json)

Each playground template entry into this .json file should include 3 components:

- Label - The name that will be visible in the Intellisense menu when hitting `CTRL+Space`
- Documentation - A link to the appropriate documentation page that most accurately covers the topic of the template you're adding.
- insertText - The code snippet itself

Let's take a look at a simple example, setting up a shadow generator.

```json
{
    "label" : "Setup a shadow generator",
    "documentation" : "https://doc.babylonjs.com/divingDeeper/lights/shadows",
    "insertText" : "var shadowGenerator = new BABYLON.ShadowGenerator(${1:size}, ${2:the_light_source});\nshadowGenerator.getShadowMap().renderList.push(${3:the_mesh_that_casts_a_shadow});\n${4:mesh_that_receives_the_shadow}.receiveShadows = true;"    
},
```

This will produce the following lines of javascript code:
```javascript
var shadowGenerator = new BABYLON.ShadowGenerator(${1:size}, ${2:the_light_source});
shadowGenerator.getShadowMap().renderList.push(${3:the_mesh_that_casts_a_shadow});
${4:mesh_that_receives_the_shadow}.receiveShadows = true;
```
While the label and documentation components are fairly straight forward, the code snippet itself has a few things to note.

- 1) For any property that you'd like the user to be able to tab over to, you can wrap a default value into this syntax: `${1:x}`. In the case of the shadow generator, the first property entry has the word "size" substituted for 'x'. This means that the word "size" will show up as the default value for that property, inviting the user to override it with their desired value. Also note that for every additional property you'd like to allow the user to tab over to, you'll increment the number in front of the colon. So in the case of the shadow generator we see the following tab property entries `${1:size}`, `${2:the_light_source}`, `${3:the_mesh_that_casts_a_shadow}`, `${4:mesh_that_receives_the_shadow}`. Notice how the number is increasing.

- 2) If you'd like your playground template to span multiple lines, use the `\n` syntax to signal the start of a new line. Again, take a look at the shadow generator example to see this in action.



## The Playground

The place to try out coding with Babylon.js. [Playground](https://playground.babylonjs.com/)

Experimenting and changing any code in the playground and clicking on the **Run** button will not affect any original code in the playground you are currently using.
Original code can be restored by refreshing the browser.

You can write the code in JavaScript or Typescript. The playground software compiles the code to JavaScript, in the background, before rendering.

### Scene creation functions

Usually you'll want to place your scene creation code in the already defined `createScene` function. But sometimes, you might want to substitute it for the `delayCreateScene` function, which allows you to return a scene without a camera (because for instance you plan to create the camera after an asynchronous mesh load, like: <Playground id="TVHK90#113" title="delayCreateScene example" description="An example of a Playground scene defined using the delayCreateScene function" image="/img/playgroundsAndNMEs/delayCreateSceneExample.png"/>).

You can also override the engine creation by defining the `createEngine` function. This can be useful if you want to test a scene without antialiasing, for example: <Playground id="#NCWBUU#1" title="createEngine example" description="How to use createEngine on the playground to customize engine creation" image="/img/playgroundsAndNMEs/createEnginePG.png"/>

## Overview

![Playground Overview](/img/how_to/Introduction/playground.jpg)

The Playground consists of four areas:

- A menu bar at the top.
- A links bar at the bottom.
- A coding editor on the left
- A rendering area of the right.

The space for the coding editor and rendering area can be adjusted by dragging the vertical bar between them.

## The Menu

![Playground Menu](/img/how_to/Introduction/pgmenu.jpg)

In Typescript mode the menu has an orange color theme:

![Playground Typescript Menu](/img/how_to/Introduction/pgmenu_ts.jpg)

### Large Screen

- **Title and Version**: As stated.
- **Language**: Typescript/JavaScript switch.
- **Run**: Commands the playground to try to render your scene.
- **Save**: Causes your scene to be permanently stored in the playground's database and it will issue a unique URL for each save. On save you will be asked to complete the metadata so that it can be searched for. Once saved it is a good idea to bookmark the page so you can return to it later. You could then share the URL with others, for example, if it is not working as you expect you can ask a question in the forum along with the link to your playground.
- **Download**: Allows you to download a zip file named _sample.zip_. Once downloaded and unzipped, you will see a file named `index.html`
  which contains everything necessary to run the code in your browser, including links to external _Babylon.js_ and other files.
- **New**: Places a basic `createScene()` function into the editor along with code to initialize the scene variable and provide a camera.
- **Clear**: Empties all the code out of the playground editor. You could then paste in any createScene function you are working on locally.
- **Settings**: The Settings button has a sub menu with extra options
  - _Theme_: Choose the theme for the playground
  - _Font size_: Set the font size in the editor.
  - _Safe Mode_: When the checkbox is ticked the playground issues a "leaving the page?" confirmation warning when you try to unload/reload a freshly-edited, un-saved scene.
  - _Editor_: The checkbox hides or un-hides the editor portion of the playground.
  - _Full Screen_: Makes the render area full screen.
  - _Editor Full Screen_: Makes the editor area full screen.
  - _Format Code_: Pretty prints the code.
  - _Minimap_: Display the minimap of the code editor.
  - _Metadata_: This is where you describe your playground allowing yourself and other to search the playground database for examples of use.
- **Version**: Allows and shows your choice of the Babylon.js framework, either the current stable one or the latest preview version.
- **Examples**: A drop down menu giving examples of playgrounds with a search filter.

### Small Screens

![Playground Typescript Menu](/img/how_to/Introduction/smallScreensPG.png)

- **Menu**: Contains Run, New, Clear, Save and Zip as submenus.
- **Code/Scene**: Bottom Left Corner - switch between Code and Scene views.

## Playground URL formats and templates

After editing any saves of the playground are numbered incrementally from one, for example:

- https://playground.babylonjs.com/#6F0LKI#1
- https://playground.babylonjs.com/#6F0LKI#2
- etc...

Some useful HTML templates are also available:

| Template                                                           | Description                                                                                          |
| ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- |
| [full.html](https://playground.babylonjs.com/full.html#6F0LKI#2)   | Shows the render area in full screen                                                                 |
| [frame.html](https://playground.babylonjs.com/frame.html#6F0LKI#2) | Shows the render area in full screen, but with a bottom toolbar showing FPS, reload and edit buttons |
| [debug.html](https://playground.babylonjs.com/debug.html#6F0LKI#2) | Uses a debug version of Babylon.js                                                                   |

## Forum sharing

Of course the playground is extremely useful to get help from the community. In the forum, simply paste the link of your playground.

You can have fun showing directly your playground embedded into your message, using iframe. But take note that you have to be sparing with this functionality: this will slow down the loading of your topic.

```html
<iframe src="https://playground.babylonjs.com/frame.html#6F0LKI#2" width="400px" height="250px"></iframe>
```

![playground forum sharing ways](/img/features/pgsupport/pg-forum-sharing-ways.jpg)

## Compilation Errors

![compilation error popup](/img/features/pgsupport/pg-compilation-error.jpg)

Any errors in your playground are flagged with a red pop-up box containing limited information. After making an adjustment to your code, you need not close the compilation error pop-up. It should close automatically at the next Run, if all errors have been corrected.

## Focus

Whenever a scene in the playground needs the use of keys to move an object, such as a mesh or camera, around then the rendering area needs to have the focus. After running the playground ensure that the render area has the focus by clicking inside it before using the keys.
