{"id":13647991,"url":"https://github.com/thibo73800/metacar","last_synced_at":"2025-04-22T06:32:41.147Z","repository":{"id":201816882,"uuid":"136301857","full_name":"thibo73800/metacar","owner":"thibo73800","description":"A reinforcement learning environment for self-driving cars in the browser.","archived":false,"fork":false,"pushed_at":"2020-05-14T17:52:22.000Z","size":919,"stargazers_count":372,"open_issues_count":11,"forks_count":77,"subscribers_count":12,"default_branch":"master","last_synced_at":"2024-11-09T22:36:44.336Z","etag":null,"topics":["autonomous-vehicles","browser","pixijs","reinforcement-learning","self-driving-car","tensorflowjs"],"latest_commit_sha":null,"homepage":"https://www.metacar-project.com/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/thibo73800.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2018-06-06T09:00:41.000Z","updated_at":"2024-11-07T14:24:36.000Z","dependencies_parsed_at":null,"dependency_job_id":"ba4d7494-1c47-4fdc-8695-dd97ac546d89","html_url":"https://github.com/thibo73800/metacar","commit_stats":null,"previous_names":["thibo73800/metacar"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thibo73800%2Fmetacar","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thibo73800%2Fmetacar/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thibo73800%2Fmetacar/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thibo73800%2Fmetacar/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thibo73800","download_url":"https://codeload.github.com/thibo73800/metacar/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250183402,"owners_count":21388712,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["autonomous-vehicles","browser","pixijs","reinforcement-learning","self-driving-car","tensorflowjs"],"created_at":"2024-08-02T01:03:52.981Z","updated_at":"2025-04-22T06:32:40.456Z","avatar_url":"https://github.com/thibo73800.png","language":"TypeScript","funding_links":[],"categories":["TypeScript","小游戏"],"sub_categories":["其他"],"readme":"# Metacar: A reinforcement learning environment for self-driving cars in the browser.\n\n[\u003cimg style=\"display: block; width: 100%; margin: auto;\" src=\"https://github.com/thibo73800/metacar/blob/master/img/header_github.png\" /\u003e](https://www.metacar-project.com)\n\n[![Contributions welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=plastic)](CONTRIBUTING.md)\n\n\n\u003cb\u003eMetacar\u003c/b\u003e is a 2D reinforcement learning environment for autonomous vehicles running in the browser. The project aims to let reinforcement learning be more accessible to everyone through solving fun problems. Metacar comes with a set of a predefined levels, some harder to address than others. More levels and possibile scenarios will be added soon (pedestrian, bikes...). Furthermore, the library let you create your own levels and personalize the environment to create your desired scenario.\n\nIf you want to be part of the project, whether to implement features in the environment or demonstrate algorithms, feel free to join\nthe [slack channel](https://join.slack.com/t/metacar/shared_invite/enQtMzgyODI4NDMzMDc0LTY1MjIwNzk1MTAzOTBiZjJlOGUwM2YyYjA3MzBmNjQyNjUyMDZkOGNkYmU0MmUyYzUzNGRhNGJhZDE1M2EzNzM) to ask questions and talk about all your fantastic ideas!\n\nTo start developing with metacar check out the Documentation and the [API Reference](http://metacar-project.com/docs/modules/_index_.html)\n\nYou can also take a look at the \u003cb\u003e[online demo](https://www.metacar-project.com).\u003c/b\u003e\n\n# Documentation\n\n### Table of contents:\n1. [Getting Started](#getting-started)\n2. [Your first environment](#first-env)\n3. [Interact with the environment](#interact-env)\n4. [Custom the environment](#configure-env)\n5. [Edit your own level](#create-level)\n\n\u003ca id='getting-started'\u003e\u003c/a\u003e\nGetting started\n------------\n\n### Installing Metacar\n\nYou can use Metacar with a direct link in your HTML file or install it from NPM. However, metacar is based on [Pixi.js](http://www.pixijs.com/): 4.7.1, then you need to include pixi.js as a global dependency in your HTML.\n\n\u003ca id='script-tag'\u003e\u003c/a\u003e\n#### Script Tag\n\n```html\n\u003c!DOCTYPE html\u003e\n\u003chtml\u003e\n\u003chead\u003e\n    \u003cmeta charset=\"utf-8\" /\u003e\n    \u003ctitle\u003eMetacar: Documentation\u003c/title\u003e\n    \u003cscript src=\"https://cdnjs.cloudflare.com/ajax/libs/pixi.js/4.7.1/pixi.min.js\"\u003e\u003c/script\u003e\n\u003c/head\u003e\n\u003cbody\u003e\n    \u003cscript src=\"https://cdn.jsdelivr.net/combine/npm/metacar@0.1.1,npm/metacar@0.1.1\"\u003e\u003c/script\u003e\n\u003c/body\u003e\n\u003c/html\u003e\n```\n\n#### OR Script Tag and NPM\n\n```shell\nnpm i metacar\n```\n\n```html\n\u003c!DOCTYPE html\u003e\n\u003chtml\u003e\n\u003chead\u003e\n    \u003cmeta charset=\"utf-8\" /\u003e\n    \u003ctitle\u003eMetacar: Documentation\u003c/title\u003e\n    \u003cscript src=\"https://cdnjs.cloudflare.com/ajax/libs/pixi.js/4.7.1/pixi.min.js\"\u003e\u003c/script\u003e\n\u003c/head\u003e\n\u003cbody\u003e\n    \u003cscript src=\"yourscript.js\"\u003e\u003c/script\u003e\n\u003c/body\u003e\n\u003c/html\u003e\n```\n```javascript\nimport Metacar from \"metacar\";\n```\n\n------------\n\n\u003ca id='first-env'\u003e\u003c/a\u003e\nYour first environment\n------------\n\nEven if you can [create your own level](#create-level), Metacar comes up with a set of predefined levels accessible under [metacar.level](#). Once your level is selected, you can use it to create a first environment. \u003cbr\u003e\n\n```javascript\n// Select a level\nconst level = metacar.level.level1;\n// Create the environement\nconst env = new metacar.env(\"env\", level);\n// Load it\nenv.load();\n```\n\nYou also have to create the container in your HTML file.\n```html\n\u003cdiv id=\"env\"\u003e\u003c/div\u003e\n```\n(NOTE: metacar.env can be instantiated with an object or a string for the level parameters: [doc API](http://metacar-project.com/docs/classes/_metacar_.metacar.html#constructor))\n\n\u003cb\u003eWonderful! You just created your first metacar environment. \u003c/b\u003e You can take some time to play around with the arrow keys to move the car. The current collision system supports the detection of the following events:\n\n* Collisions with other vehicles.\n* Detection of the vehicles, ground, and road with the lidar.\n* Detection of the car going out track.\n\nIf you want to add new features to the detection system, you can consider [contributing to the project](https://github.com/thibo73800/metacar/blob/master/CONTRIBUTE.md) :)\n\n\u003ca id='interact-env'\u003e\u003c/a\u003e\nInteract with the environment\n------------\n\n### Action space\n\nBy default, the environment comes with a simple motion engine ([How to change the motion engine ?](#change-motion))  which lets you control the car with the arrow. Then, the actions are either UP, LEFT, RIGHT, DOWN, WAIT. Once the environment is loaded, you can take a look at the action space.\n\n```javascript\nenv.load().then(() =\u003e {\n    console.log(env.actionSpace());\n});\n```\n\n```\n{\n    type: \"Discrete\", // The number is discrete\n    size: 1, // Only one number is expected\n    range: [0, 1, 2, 3, 4] // The action can be either 0, 1, 2, 3 or 4\n}\n```\n\n### Play \u0026 Stop\n\nLet's suppose your agent is already trained to move forward whatever happens (Fortunately we are in a simulation). Then you might want to test it in real time to see the result.\n\nThe quickest way to do so is to just ask the environment to call a given function at each loop turn.\n\n```javascript\nenv.load().then(() =\u003e {\n\n    env.addEvent(\"play\", () =\u003e {\n        // Move forward\n        const reward = env.step(0);\n        // Log the reward\n        console.log(reward);\n    });\n\n});\n```\n\nYou should see a \u003cb\u003eplay\u003c/b\u003e 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 leaves the road.\u003cbr\u003e\n\nTo stop calling your function, you can add a stop button on the screen.\n\n```javascript\nenv.load().then(() =\u003e {\n\n    env.addEvent(\"play\", () =\u003e {\n        // Move forward\n        const reward = env.step(0);\n        // Log the reward\n        console.log(reward);\n    });\n\n    env.addEvent(\"stop\", () =\u003e {\n        console.log(\"The stop button have been pressed.\");\n    });\n\n});\n```\n\n### Train your agent\n\nDuring the training, the environment is not rendering on the screen anymore. Once your training is finish you have to notify the environment by calling env.render(true) to render the environment again. \u003cbr\u003e\n\nThe state of the environment is made of four fields:\n\n```\n{\n    a: number|undefined // Acceleration of the car (if any)\n    lidar: number[][] // Lidar points values\n    linear: number[] // The flatten lidar values + the current speed of the car\n    steering: number|undefined // Steering angle of the car (if any)\n}\n```\n\nHere is an example of simple training loop.\n\n```javascript\nenv.load().then(() =\u003e {\n\n    env.addEvent(\"train\", () =\u003e {\n        for (let s=0; s \u003c 100; s++){\n            // Get the current state of the lidar\n            const state = env.getState();\n            // Move forward\n            const reward = env.step(0);\n        }\n        // Log the reward\n        env.render(true);\n    });\n\n});\n```\n\n### Reset and shuffle env\n\nTo reset the environment, you can either call\n\n```javascript\n    env.reset();\n```\n\nOr add a button to do it from the web page.\n\n```javascript\nenv.load().then(() =\u003e {\n\n    env.addEvent(\"custom\", () =\u003e {\n        env.reset();\n    });\n\n});\n```\n\nYou can also shuffle the position of vehicles (agent and other cars) on the map.\n\n\n```javascript\nenv.load().then(() =\u003e {\n\n    env.addEvent(\"Shuffle only the agent\", () =\u003e {\n        env.shuffle({cars: false});\n    });\n\n    env.addEvent(\"Shuffle all\", () =\u003e {\n        env.shuffle();\n    });\n\n});\n```\n\n\n\u003ca id='configure-env'\u003e\u003c/a\u003e\nCustom the environement\n------------\n\n\u003cb\u003e!WARNING:\u003c/b\u003e The method presented in this section must be called \u003cb\u003eBEFORE\u003c/b\u003e loading the environment.\n\n\u003ca id='change-motion'\u003e\u003c/a\u003e\n### Change the motion engine\n\nThere are two motion engine available: BasicMotion and ControlMotion.\n\n#### BasicMotion\n\nThis is the default motion engine. Movement of the car is either up, down, left, right or wait. The car turns from a given angle for the left and right action.\n\nYou can change the parameters of the motion engine using the setMotion method.\n\n```javascript\nenv.setAgentMotion(metacar.motion.BasicMotion, {rotationStep: 0.25});\n// Load the environment after having changed the properties.\nenv.load();\n```\n\n#### ControlMotion\n\nThe motion control is based on two continuous values for the throttle and steering angle of the car. Then the action is an array of two floating values. (see [actionSpace](http://metacar-project.com/docs/classes/_metacar_.metacar.html#actionspace))\n\n```javascript\nenv.setAgentMotion(metacar.motion.ControlMotion);\n// Load the environment after having changed the properties.\nenv.load();\n```\n\n### Change the lidar properties\n\nThere are four properties you can change. The number of points (pts) per line, the width and height of the area covered by the lidar and the position (pos) with respect to the car.\n\n```javascript\nenv.setAgentLidar({pts: 3, width: 1.5, height: 1.5, pos: 1});\n// Load the environment after having changed the properties.\nenv.load();\n```\n\n### Stop the others vehicles\n\nYou can choose to move or stop the other vehicles with env.carsMoving()\n\n```javascript\nenv.carsMoving(false);\n// Load the environement after changing the propeties.\nenv.load();\n```\n\n\u003ca id='other-methods'\u003e\u003c/a\u003e\nOther methods\n------------\n\n### Load a file from your computer\n\nThis features can be useful to load the content of one file from your computer (the result of a trained model for\ninstance).\n\n```javascript\nenv.load().then(() =\u003e {\n\n    env.addEvent(\"load\", (content) =\u003e {\n        // Here the content of the loaded file.\n        console.log(content);\n    },{local: true});\n\n});\n```\n\n### Save a file on your computer\n\nAlso, you might want to save the result of a trained model on your computer.\n\n```javascript\nenv.save(\"content of my model\", \"model.metacar\")\n```\n\n### Add a custom event\n\nenv.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.\n\n```javascript\nenv.load().then(() =\u003e {\n\n    env.addEvent(\"My custom event\", () =\u003e {\n        env.save(\"content of my model\", \"model.metacar\");\n    });\n\n});\n```\n\n\u003ca id='create-level'\u003e\u003c/a\u003e\nEdit a new level\n------------\n\nOnly three lines are required to create the editor:\n\n```javascript\nconst level = metacar.level.level1;\nvar editor = new metacar.editor(\"env\", level);\neditor.load();\n```\n\n\u003cb\u003eLeft click\u003c/b\u003e on one item to select it. Then Left click on the map to set the item.\n\u003cb\u003eRight click\u003c/b\u003e is used to remove an item.\n\n### Save the level\n\n```javascript\neditor.load().then(() =\u003e {\n\n    editor.addEvent(\"save\", (content) =\u003e {\n       // Save the content into the localstorage here or just\n       // retrieve the downloaded json.\n    }, {download: true, name: \"mylevel.json\"});\n\n});\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthibo73800%2Fmetacar","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthibo73800%2Fmetacar","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthibo73800%2Fmetacar/lists"}