Metacar: A reinforcement learning environment for self-driving cars in the browser.

Documentation

Table of contents:

1. Getting Started
2. Your first environement
3. Interact with the environement
4. Custom the environement
5. Create your own level

Getting started

Installing Metacar

You can used Metacar with a direct link in your HTML file or installing it from NPM. However, metacar is based on Pixi.js: 4.7.1, then you need to include pixi.js as a global dependencies in your HTML.

Script Tag

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8" />
    <title>Metacar: Documentation</title>
    <script src="https://cdnjs.cloudflare.com/ajax/libs/pixi.js/4.7.1/pixi.min.js"></script>
</head>
<body>
    <script src="https://cdn.jsdelivr.net/npm/metacar@0.0.1/dist/metacar.min.js"></script>
</body>
</html>

Script Tag and NPM

npm i metacar

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8" />
    <title>Metacar: Documentation</title>
    <script src="https://cdnjs.cloudflare.com/ajax/libs/pixi.js/4.7.1/pixi.min.js"></script>
</head>
<body>
    <script src="yourscript.js"></script>
</body>
</html>

import Metacar from "metacar";

---

Your first environement

Even if you can create your own level, Metacar comes up with a set of predefined level accessible under metacar.level. Once your level is selected, you can use it to create a first environement.

// Select a level
const level = metacar.level.level1;
// Create the environement
const env = new metacar.env("env", level);
// Load it
env.load();

You also have to create the container in your HTML file.

<div id="env"></div>

(NOTE: metacar.env can be instanciate with an object or a string for the level parameters: doc API)

Wonderful! You just create your first metacar environement. You can take sometime to play around with the key arrow to move the car. The current collision system support the detection of the following events:

• Collisions with other vehicles
• Detection of the vehicles, ground and road with the lidar
• Detection of the car going out track

If you want to add new features to the detection system you can considere contributing to the project :)

Interact with the environement

Action space

By default the environement comes with a simple motion engine (How to change the motion engine ?) who let you control the car with the arrow. Then, the actions are either UP, LEFT, RIGHT, DOWN, WAIT. Once the environement is loaded you can take a look at the action space.

env.load(() => {
    console.log(env.actionSpace());
});

{
    type: "Discrete", // The number is discrete
    size: 1, // Only one number is expected
    range: [0, 1, 2, 3, 4] // The action can be either 0, 1, 2, 3 or 4
}

Play & Stop

Let's suppose your agent is already trained to move forward whatever happens (Fortunately we are in a simulation). Then you want might want to test it in real time to see the result.

The quickest way to do so is to simply ask the environement to call a given function at each lopp run.

env.load().then(() => {

    env.addEvent("play", () => {
        // Move forward
        const reward = env.step(0);
        // Log the reward
        console.log(reward);
    });
    
});

You should see a play button on the screen. On click, the car will move forward and the reward should be positive as long as the car is on track, then negative when the car quit the road.

To stop calling your fonction you cann add a stop button on the screen.

env.load().then(() => {

    env.addEvent("play", () => {
        // Move forward
        const reward = env.step(0);
        // Log the reward
        console.log(reward);
    });

    env.addEvent("stop", () => {
        console.log("The stop button have been pressed.");
    });

});

Train your agent

During the training, the environement is not render on the screen anymore. Once you're training is finish you have to notify the environement by calling env.render(true) to render the environement again.

The state of the environement is the the value of each lidar point. Of course, because the car still want to go forward it doesn't care about the value of the state :)

Here is an example of basic training function.

env.load().then(() => {

    env.addEvent("train", () => {
        for (let s=0; s < 100; s++){
            // Get the current state of the lidar
            const state = env.getState();
            // Move forward
            const reward = env.step(0);
        }
        // Log the reward
        env.render(true);
    });

});

Reset env

To reset the environement you can either called

    env.reset();

Or add a button to do it from the web page.

env.load().then(() => {

    env.addEvent("custom", () => {
        env.reset();
    });
    
});

Custom the environement

!WARNING: The method present in this section must be called BEFORE loading the environement.

Change the lidar propeties

There are 4 properties you can change. The number of points (pts) per line, the width and height of the area cover by the lidar and the position (pos) which respect to the car.

env.setAgentLidar({pts: 3, width: 1.5, height: 1.5, pos: 1});
// Load the environement after changing the propeties.
env.load();

Stop the others vehicles

You can choose to move or stop the other vehicles with env.carsMoving()

env.carsMoving(false);
// Load the environement after changing the propeties.
env.load();

Other methods

Load a file from your computer

This features can be usefull to load the content of one file from your computer (the result of a trained model for instance).

env.load().then(() => {

    env.load("load", (content) => {
        // Here the content of the loaded file.
        console.log(content);
    },{local: true});

});

Save a file on your computer

As well, you might want to save the result of a trained model on your computer.

env.save("content of my model", "model.metacar")

Add a custom event

env.addEvent() comes with a set of predefined event ("train", "play", "stop", "reset_env", "load") but you can also create custom event with an associated button on the page. Bellow, an example of custom event saving a file onClick.

env.load().then(() => {

    env.load("My custom event", () => {
        env.save("content of my model", "model.metacar");
    });

});

Edit a new level

Only three lines are required to create the editor:

const level = metacar.level.level1;
var editor = new metacar.editor("editor", levelToLoad);
editor.load();

Save the level

editor.load().then(() => {

    editor.addEvent("save", (content) => {
       // Save the content into the localstorage here or just
       // retrieve the downloaded json.
    }, {download: true, name: "mylevel.json"});

});

Link