{"id":22770992,"url":"https://github.com/stonet2000/dimensions","last_synced_at":"2025-04-15T05:29:39.127Z","repository":{"id":38768631,"uuid":"250941450","full_name":"StoneT2000/Dimensions","owner":"StoneT2000","description":"A Generalized Artificial Intelligence Competition Framework. And yes, its in Typescript for good reason","archived":false,"fork":false,"pushed_at":"2023-01-24T03:15:22.000Z","size":18887,"stargazers_count":74,"open_issues_count":38,"forks_count":9,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-13T19:46:52.298Z","etag":null,"topics":["ai","ai-competition","framework","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/StoneT2000.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-03-29T02:57:43.000Z","updated_at":"2024-11-30T03:14:03.000Z","dependencies_parsed_at":"2023-02-13T14:30:53.104Z","dependency_job_id":null,"html_url":"https://github.com/StoneT2000/Dimensions","commit_stats":null,"previous_names":[],"tags_count":31,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StoneT2000%2FDimensions","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StoneT2000%2FDimensions/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StoneT2000%2FDimensions/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StoneT2000%2FDimensions/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/StoneT2000","download_url":"https://codeload.github.com/StoneT2000/Dimensions/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249013898,"owners_count":21198479,"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":["ai","ai-competition","framework","typescript"],"created_at":"2024-12-11T16:11:35.695Z","updated_at":"2025-04-15T05:29:39.100Z","avatar_url":"https://github.com/StoneT2000.png","language":"TypeScript","readme":"# Dimensions\n\n[![npm version](https://badge.fury.io/js/dimensions-ai.svg)](https://badge.fury.io/js/dimensions-ai)\n\nThis is an **open sourced** **generic** **Artificial Intelligence competition framework**, intended to provide you the fully scalable infrastructure needed to run your own AI competition with no hassle.\n\nAll you need to do?\n\nCode a **competition design** and code a **bot**\n\nDimensions handles the rest, including match and tournament running, security, scalability and a local API and website through which you can monitor and control the entire system.\n\nThe framework was built with the goals of being **generalizable** and **accessible**. That's why Dimensions utilizes an I/O based model to run competitions and pit AI agents against each other (or themselves!), allowing it to be generic and language agnostic so anyone from any background can compete in your competition design.\n\nIt generalizes to many scenarios, and is able to recreate a range of systems from the [Halite 3 AI competition](https://halite.io/), [Battlecode 2020](https://battlecode.org), to a generalized [Open AI Gym](https://gym.openai.com/) that is open to machine learning in all languages in addition to Python through simple stdio.\n\nThis was inspired by [Battlecode](battlecode.org/) and [Halite](https://halite.io/)\n\nKeep reading to learn how to [get started](#getting-started) and make a tournament like this:\n\n![dimensions-trueskill-RPS](assets/dimensions-trueskill-RPS.gif)\n\nOf which the [AI bots](https://github.com/StoneT2000/Dimensions/blob/master/tests/kits/js/normal/rock.js) are all coded in about 10 lines or less (ignoring the starter kit)\n\n```js\nconst kit = require('./kit');\nconst agent = new kit.Agent();\nagent.initialize().then(async () =\u003e {\n  while (true) {\n    console.log('R'); // tell the match you want to play Rock in the game\n    agent.endTurn(); // end turn\n    await agent.update(); // wait for updates\n  }\n});\n```\n\nAs another proof of concept of how seamless and generalizable this framework is, see [the recreation of Halite 3](https://github.com/StoneT2000/dimensions-halite3) using this framework.\n\nFollow these links to jump straight to [Documentation](https://stonet2000.github.io/Dimensions/index.html), [Contributing](#contributing), [Development](#development) or [Plans](#plans) curated by the owner and the community.\n\nAlso checkout the blog post introducing the motivation for Dimensions and thoughts about it here: https://stonet2000.github.io/blog/posts/Dimensions/index.html\n\n## Features\n\n- Easy to build an AI competition that is language agnostic, allowing any kind of bot in any language to compete in your competition\n- Run many kinds of AI competitions and run different kinds of formats like round robin or using Trueskill in a ladder tournament (like a leaderboard).\n- Wrap your own AI competition built without the dimensions framework to make use of its competition running features such as Trueskill ranking like the [Halite 4 wrapper](https://github.com/StoneT2000/Halite-4-Tournament-Runner) used by competitors in the Halite 4 challenge on Kaggle.\n- Comes with an API served locally that gives access to data on ongoing matches and tournaments and allows for direct control of matches and tournaments through the API. See this page for details on this API: https://github.com/StoneT2000/Dimensions/wiki/Dimensions-Station-API\n- Supports plugins like the [MongoDB](https://github.com/StoneT2000/Dimensions/wiki/Plugin#supported-plugins) plugin that takes three lines of code to automatically integrate and scale up your tournament and integrate an automatic user authentication and login system. See [this](https://github.com/StoneT2000/Dimensions/wiki/Scaling) for complete info on how to scale up.\n- Ensures malicious bots cannot cause harm to your servers through `secureMode`. See [this wiki page](https://github.com/StoneT2000/Dimensions/wiki/Security) for details.\n- Built with Typescript, meaning flexibility in coding any design, and easily integrates into a frontend replay viewer to reconstruct matches for viewing using minimal replay data storage.\n\n## Requirements\n\nAt the moment, MacOS and Linux are 100% supported. Windows platforms might not work and it is highly suggested to install [WSL](https://docs.microsoft.com/en-us/windows/wsl/install-win10). It's also suggested to use Node 12.x or above. Lower versions are untested.\n\n## Getting Started\n\nThis guide will take you through how to start and run a competition built with Javascript/Typescript. To see how to use this framework to run an AI competition built without the dimensions framework, see [this wiki page](https://github.com/StoneT2000/Dimensions/wiki/Custom-Competition-Design).\n\nFirst, install the `dimensions-ai` package\n\n```\nnpm install dimensions-ai\n```\n\nCreate a new file called `run.js` and inside it we need to first `require` the package\n\n```js\nconst Dimension = require('dimensions-ai');\n```\n\nIn order to start writing AI to compete against each other in a competition, you need to do two things.\n\n1. Design the competition\n2. Design an AI starter kit\n\nYou need to design a competition to allow people to compete and facilitate the matches. More info on that soon. it is highly suggested to design an AI starter kit so people can get straight into competing.\n\nIf you already have a design, feel free to skip to the section on running a [match](#run-a-match) and a [tournament](#run-a-tournament)\n\n### Designing The Competition\n\nIt is suggested to design the competition in Javascript / Typescript using the Dimensions framework. See https://github.com/StoneT2000/Dimensions/wiki/Creating-a-Design for a tutorial on creating a design.\n\nYou can also create a custom design outside of the framework, see https://github.com/StoneT2000/Dimensions/wiki/Custom-Competition-Design for a tutorial on that.\n\n### Designing an AI Starter Kit\n\nExample starter kits can be found in the [/templates/starter-kits](https://github.com/StoneT2000/Dimensions/tree/master/templates/starter-kits/) folder and you can just copy these and tweak them accordingly to your own design.\n\nSee https://github.com/StoneT2000/Dimensions/wiki/Creating-a-Starter-kit for a tutorial on creating a starter kit.\n\n### Run a Match\n\nNow with a design done and a starter kit created, all you have to do is write a quick AI that does something and then run a match as follows:\n\nFirst initialize your design and pass it a name. Then create a new `dimension` with `Dimension.create`.\n\n```js\nlet RPSDesign = new RockPaperScissorsDesign('RPS!');\nlet myDimension = Dimension.create(RPSDesign);\n```\n\nWe can now run our first match by passing in an array of paths to the bot codes, each of which will generate into a new agent that participates in the match. You can then also pass in any configurations you want accessible through `match.configs` in the life cycle functions of your `design`.\n\n```js\nlet results = await myDimension.runMatch(\n  [\n    './examples/rock-paper-scissors/bots/paper.js',\n    './examples/rock-paper-scissors/bots/rock.js',\n  ],\n  {\n    bestOf: 5, // a configuration accessible in match through match.configs.bestOf\n  }\n);\n```\n\nYou can now log the results, of which are the same results returned by your `design's` `getResult` function.\n\n```js\nconsole.log(results);\n```\n\nNotice that your console will also print something about a station. It'll give you a link to the `Station`, a local server that gives you access to an API to access and control your Dimension, Matches, Tournaments and more. Check out https://github.com/StoneT2000/Dimensions/wiki/Dimensions-Station-API for details on the API.\n\nIf you want to view the API from a website, see this repo: https://github.com/StoneT2000/Dimensions-web\n\n### Run a Tournament\n\nThis framework also provides tournament running features, which currently include [Elimination](https://stonet2000.github.io/Dimensions/classes/_tournament_elimination_index_.elimination.html), and a flexible [Ladder](https://stonet2000.github.io/Dimensions/classes/_tournament_ladder_index_.ladder.html) type tournaments. Additionally, there are various ranking systems used, such as Win/Tie/Loss and Trueskill. This section takes your through a really brief rundown of how to run a tournament. See [this wiki page](https://github.com/StoneT2000/Dimensions/wiki/Running-Tournaments) for more in depth details on setting up the various kinds of tournaments\n\nHere is how you run a tournament. First, you will need a `resultHandler` function. This function must be given to the tournament to indicate how the results of a `match` should be interpreted. Recall that these results are returned by the `getResult` function in your design class. It is suggested to provide these result handlers in your `Design`.\n\nNext, you need to pass in some required configurations, namely `type, rankSystem, agentsPerMatch, resultHandler`. The following code snippet shows an example.\n\n```js\nlet RPSDesign = new RockPaperScissorsDesign('RPS!');\nlet myDimension = Dimension.create(RPSDesign);\nlet Tournament = Dimension.Tournament;\nlet simpleBot = './bots/rock.js';\nlet botSources = [simpleBot, simpleBot, simpleBot, simpleBot, simpleBot];\n\nlet RPSTournament = myDimension.createTournament(botSources, {\n  name: 'A Best of 329 Rock Paper Scissors Tournament', // give it a name\n  type: Tournament.Type.LADDER, // Create a Ladder Tournament\n  rankSystem: Tournament.RankSystem.TRUESKILL, // Use Trueskill to rank bots\n  agentsPerMatch: [2], // specify how many bots can play at a time\n  defaultMatchConfigs: {\n    bestOf: 329,\n    loggingLevel: Dimension.Logger.Level.NONE, // turn off match logging\n  },\n  resultHandler: (results) =\u003e {\n    let ranks = [];\n    if (results.winner === 'Tie') {\n      ranks = [\n        { rank: 1, agentID: 0 },\n        { rank: 1, agentID: 1 },\n      ];\n    } else {\n      let loserID = (results.winnerID + 1) % 2;\n      ranks = [\n        { rank: 1, agentID: results.winnerID },\n        { rank: 2, agentID: loserID },\n      ];\n    }\n    return {\n      ranks: ranks,\n    };\n  },\n});\n\nRPSTournament.run();\n```\n\nOnce running, the console will display a live leaderboard of the tournament running, showing the current ranks and scores of all the bots, similar to the gif shown at the beginning of this document.\n\nDocumentation / guides on the tournaments and how to use them can be found https://github.com/StoneT2000/Dimensions/wiki/Running-Tournaments. Full documentation on Tournaments can be found [here](https://stonet2000.github.io/Dimensions/interfaces/_tournament_index_.tournament.tournamentconfigsbase.html).\n\nNote that different tournament types have different tournament configurations and different rank systems have different ranking configurations, all of which can be found on the documentation.\n\n### More Stuff!\n\nThe [wiki](https://github.com/StoneT2000/Dimensions/wiki) is populated with more basic and advanced example usages of this framework. This ranges from how to [configure the match engine](https://github.com/StoneT2000/Dimensions/wiki/Configuration#engine-options), [configuring various tournaments and rank systems](https://github.com/StoneT2000/Dimensions/wiki/Running-Tournaments), to tips on designing a successful competition.\n\n### Strong Recommendations\n\nIn a production setting, it is strongly recommended to create a Dimension in `secureMode` to decrease the likelihood of user uploaded bot code of causing any significant harm to a server. By default, `secureMode` is set to false, but you will always get a warning about it. Setting it to true only requires you to install [Docker](https://www.docker.com/get-started).\n\n## Plugins\n\nPlugins intend to be a simple \"drag and drop.\" Dimensions can `use` a plugin and the plugin will automatically configure the dimension as needed. See here for more [info on the available plugins](https://github.com/StoneT2000/Dimensions/wiki/Plugin#supported-plugins). See here for how to [develop a plugin](https://github.com/StoneT2000/Dimensions/wiki/Plugin#developing-a-plugin)\n\nFor example, here's two lines of code that integrate MongoDB as a database:\n\n```js\nlet mongo = new Dimension.MongoDB('mongodb://localhost:27017/dimensions');\nawait myDimension.use(mongo);\n```\n\n## Contributing\n\nEveryone is more than welcome to contribute to this project! You can open an issue or submit a PR\n\nCheck out the issues for this repository to get an idea on something you can help out with!\n\n## Development\n\nThis is all written in [TypeScript](https://www.typescriptlang.org/)\n\nFirst install all necessary packages and pull necessary docker images for testing with\n\n```\nnpm install\n./pull_all_test_docker_images.sh\n```\n\nStart development by running\n\n```\nnpm run watch\n```\n\nto watch for code changes in the `src` folder and reload the build folder.\n\nTests are built with [Mocha](https://mochajs.org/) and [Chai](https://www.chaijs.com/). You will need mongodb setup serving through port `27017` to run database plugin tests.\n\nIf that is setup, run tests with\n\n```\nnpm run test\n```\n\nRun\n\n```\nnpm run build\n```\n\nto build the entire library.\n\nRun\n\n```\nnpm run docs\n```\n\nto generate documentation\n\n## Plans\n\n- Make it easier to create a `Design` (design a competition)\n  - Make README easier to READ, and reduce the initial \"getting-used-to-framework\" curve.\n- Make it easier for users to dive deeper into the `MatchEngine`, `Matches`, `Dimensions` to give them greater flexibility over the backend infrastructure\n  - At the moment, there are plans for a parallel command stream option, where all agents send commands whenever they want and the engine just sends them to the update function\n  - Allow users to tinker the MatchEngine to their needs somehow. (Extend it as a class and pass it to Dimensions)\n- Security Designs to help ensure that users won't create `Designs` susceptible to cheating and match breaking behavior from bots participating in a `Match`\n  - Give some guidelines\n  - Add some options and default values for certain configurations, e.g.\n    - Max command limit per `timeStep` (for a game of rock paper scissors, this would be 1, it wouldn't make sense to flood the `MatchEngine` with several commands, which could break the `Match`)\n- Add visualizers for rock paper scissors example and domination example (and others if possible)\n- Generalize a match visualizer\n- Add more example `Designs` and starter kits for other popular ai games\n  - Recreate Kaggle Simulation's xConnect\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstonet2000%2Fdimensions","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstonet2000%2Fdimensions","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstonet2000%2Fdimensions/lists"}