clash-of-robots
v1.4.0
Published
[![Build Status](https://travis-ci.org/morten-olsen/clash-of-robots.svg?branch=master)](https://travis-ci.org/morten-olsen/clash-of-robots) [![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github
Downloads
21
Readme
Clash of Robots
A simple engine for creating AI vs. AI games
Getting started
Warning, there has been no proof reading of this text yet, so while the project should be ready to use, the text describing it is still very much a work in progress
Install
npm / yarn
npm install clash-of-robots
# or
yarn add clash-of-robots
Browser/CDN
<script src="https://cdnjs.cloudflare.com/ajax/libs/babel-polyfill/6.26.0/polyfill.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/clash-of-robots/dist/clash-of-robots.min.js"></script>
Creating a games
When creating a game only one things is needed, a redux style reducer
. Other options are available, and will be explained later
const { combineReducers } = require('redux');
const ClashOfRobots = require('clash-of-robots');
const counter = (state = 0, action) => {
switch (action.type) {
case 'INCREMENT':
return state.count + 1;
case 'DECREMENT':
return state.count - 1;
case default:
return state;
}
};
const reducer = combineReducers({
counter,
});
const game = new ClashOfRobots(reducer);
Creating AI types
AI types are basically rulesets round the AI script, which controls the fog of war and validated the output of an AI. These are created as extensions to the AI
class and are registered in the games
Output of AIs are a list of redux
actions
const { AI } = require('clash-of-robots');
class SimpleAI extends AI {
createFogOfWar(world, round) {
return world.counter;
}
validate(outputs, fow, world, round) {
for (let output of outputs) {
if (output.type !== 'INCREMENT' && output.type !== 'DECREMENT') {
return Error('INVALID ACTION');
}
}
}
}
game.registerAI('simple', () => new SimpleAI());
Running AIs
Now that the AI type is registered, it is time to add some actual AIs into the game engine. The best way to do it is using the underlaying redux
store, and dispatch an AI action
const { addAI } = require('clash-of-robots');
game.store.dispatch(addAI('simple', `
if (world < 5) {
return [{ type: 'INCREMENT' }]
}
`));
So the AI above should increment out world.count
until it hits 5 and then stop.
To run a round, dispatch a takeTurn
action, which will cycle through all AIs allowing them to take their turn.
const { takeTurn } = require('clash-of-robots');
game.store.dispatch(takeTurn());
Winning the game
A win condition can be added to the game to be evaluated after an AI run to determine if an AI has won the game.
This function is supplied to the game as an option and should return an identification for the winner which will then be store in state.ais.winner
Once a winner has been found, takeTurn
will no longer change anything in the world.
const findWinner = (world) => {
if (world === 5) {
return 'winner';
}
}
const game = ClashOfRobots(reducer, {
findWinner,
});
Showing the World
As the store behind the game is a regular redux
store, all methods apply, game.store.subscribe
, game.store.getState
are both valid, as well as using a library such as react-redux
for binding to react
components. Be ware that the game reducer is stored inside game
in the store
Advanced topics
Adding AI api
When using the javascript-function
spawner it is possible to supply an additional API, which becomes available to the AI script, this is done by registering it as a new spawner, or reregistering
const { functionSpawner } = require('crash-of-robots');
const api = {
addNumbers: (a, b) => a + b,
};
game.registerSpawner('javascript-function', functionSpawner(api));
game.store.dispatch(addAI('simple', `
module.exports = [{
type: 'ADD_NUMBERS',
payload: addNumbers(5, 10),
}];
`));
Spawners
The game is centered around spawners, which are small units, which get loaded with a code string and then they are responsible for executing that code when invoked. With no modification the spawner used is the javascript-function
spawner, which simply uses new Function(...)
to create a function to be called. This however will not be the ideal solution for many cases, for instance, if running on a server, that would give the AI access to all node APIs. Therefore it is a good idea to opt for another spawner.
These are at the moment a work in progress, but the once that I am working on are:
- fork-vm - forking a new node process, with the code running inside a VM to protect the system
- http - running on an http API, so AI agents can live on completely separate systems
- tcp - same as http, just over an TCP socket instead
- web-worker - create a new browser tread and then uses postMessage to communicate
- stdinout - using a process stdin and stdout to send and receive, which allows for a variety of other languages to act as AIs
And i might create a web-rtc if i get the time.
But as the list shows, pretty much anything which can receive and send JSON can act as an agent.
To create a spawner, simply create a method with loadScript
and execute
below is the javascript-function
for reference
class JavascriptFunctionSpawner {
async loadScript(script) {
this.fn = new Function('module', 'fow', 'round', script)
}
async execute(fow, round) {
const module = { exports: [] };
await this.fn(module, fow, round);
return module.exports;
}
}
game.registerSpawner('javascript-function', () => new JavascriptFunctionSpawner());
game.store.dispatch(addAI('simple', '...', {
spawner: 'javascript-function',
}));