Merge branch 'master' into dev

README.md

@@ -1,4 +1,5 @@
-# factorioClusterio [![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2FDanielv123%2FfactorioClusterio.svg?type=shield)](https://app.fossa.io/projects/git%2Bgithub.com%2FDanielv123%2FfactorioClusterio?ref=badge_shield)
+# factorioClusterio
+[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2FDanielv123%2FfactorioClusterio.svg?type=shield)](https://app.fossa.io/projects/git%2Bgithub.com%2FDanielv123%2FfactorioClusterio?ref=badge_shield)
 
 | Branch | Coverage | Build |
 |--------|----------| ----- |
@@ -7,6 +8,18 @@
 
 If you want to connect to a clusterio cluster, please reffer to the [client](https://github.com/Danielv123/factorioClusterioClient)
 
+### Table of contents
+
+* [Introduction & methodology](#introduction)
+
+* [Ubuntu setup](#ubuntu-setup)
+
+* [Windows setup](#windows-setup)
+
+* [Command cheatsheet](#cheatsheet)
+
+## Introduction
+
 Features:
 
 - Entities to send/recieve items
@@ -17,13 +30,41 @@ Features:
 
 - Sending of circuit network signals
 
+- Inventory combinator to display item levels in the cluster (and epoch time)
+
+- Reporting of graphs and UPS on master interface
+
 Connection diagram:
 
 ![http://i.imgur.com/7FdVfgB.png](http://i.imgur.com/7FdVfgB.png)
 
-There can be any number of clients connected to each slave, and any sumber of slaves connected to a master but there can only be one master server.
+There can be any number of clients connected to each slave, and any number of slaves connected to a master but there can only be one master server in each cluster.
 
-# Ubuntu setup
+**How does it work?**
+
+Traditional factorio mods have always been limited by the games deterministic design. This gives us a very bug free and predictable game, but doesn't allow us cool stuff such as internet communication.
+Clusterio exploits one of the games logging features, game.write_file and RCON to communicate between servers. Sending an item from one server to another takes this path:
+
+1. server1: Chest has stuff in it, write the contents to a file and delete them from the game world
+
+2. client.js on server1: File has stuff in it, parse and send to the master for storage
+
+3. master: server1 gave us stuff, store it in the storage and write some statistics
+
+4. server2: get-chest is empty, write a request to file
+
+5. client.js on server2: Request file has stuff in it, parse and send a request to master for more items of that type
+
+6. master: server2 asked for stuff, check if we have enough and how much demand there is, then send however much is appropriate back
+
+7. client.js on server2: We were allowed to import x of item y, run command /c remote.call("clusterio", "importMany", "{'copper-plate':120}")
+
+This process works the same for both items and liquids, independant on what mods are used. Yes, modded items are fully supported.
+
+Clusterio also handles a few other neat things, such as giving you access to epoch time, transmitting combinator signals between worlds (and any other application who wants to) and 
+creating graphs on the master web interface.
+
+## Ubuntu setup
 
 NodeJS does not support EOL ubuntu releases. Make sure you are on the most recent LTS release or newer.
 
@@ -65,7 +106,7 @@ Clusterio has limited support for using docker.
 
 The -v flag is used to specify the instance directory. Your instances (save files etc) will be stored there.
 
-# Windows setup
+## Windows setup
 
 Clusterio is built up of multiple parts. Here is a quick guide:
 
@@ -120,3 +161,31 @@ Fancy game client that does the following steps automatically: [clusterioClient]
 2. Drop it into ./factorio/mods
 
 3. Run factorio and connect to slave as a normal MP game. You will find the port number to connect to at http://[masterAddress]:8080
+
+## Cheatsheet
+
+**To create a new instance/start it**
+
+    node client.js start [instanceName]
+
+**Other instance management tools:**
+```
+node client.js delete [instanceName]
+node client.js list
+```
+**To update clusterio to the latest version:**
+
+1. Download the latest zip version of factorio for your platform manually from factorio.com. Place it in the project root folder and call it "factorio" (folder name is specified in config.json)
+
+2. Grab the latest version of the repo
+
+```
+git pull
+
+npm install
+```
+
+3. Download the latest version of the factorioClusterioMod from its github repo
+```
+node client.js download
+```