updated documentation

README.md

@@ -6,6 +6,7 @@
 * [Hive Node-Webkit UI Guide](doc/hive-node-webkit.md)
 * [Hive Rules Core Implementation Details](doc/hive-core.md)
 
+
 ####Legal
 
 This work is licensed under the [Research License 1.0](LICENSE.md) strictly for academic research and/or educational purposes *only*.

doc/hive-ai-js.md

@@ -0,0 +1,13 @@
+#Hive AI in Node.js
+
+This is the easiest way to get started quickly. 
+
+1. Look at [this reference implementation](../ai/her/hive-ai-her.js) and [accompanying package.json](../ai/her/package.json) to get a feel for the basic structure.
+2. Create a new folder in the `ai` directory at the root of the project
+3. In your new folder (I'll call it new-ai) create a **new-ai.js** and a **package.json**
+4. In the **package.json**, the following fields should be considered required: *name*, *active*, *version*, *long_name*, *module*, *description*
+5. In the **new-ai.js**, you must *export* a `function` called `process_message`, taking one argument: the `message` object.
+6. Your AI will be expected to return a response message, just like the ones in [this API specification document](../api/hive_api_v0.1.0_doc.js).
+7. Before trying to run your AI, make sure the *active* property in the *package.json* is set to true.
+8. Now it should be all ready to go. You can either run it through the [hive-cli](hive-cli.md) to pit it against other AI and see how it fares, or play against it yourself in the [node-webkit-ui](hive-node-webkit.md). In either mode, it is recommended you use **Local** mode as communications have less overhead, but feel free to test with **Remote** (TCP) as well, if you're curious. 
+

doc/hive-ai-tcp.md

@@ -0,0 +1,202 @@
+#The Hive API Interface Specification
+
+##Basics
+* Both the Hive CLI and the Hive Node-Webkit UI communicate with remote AI modules over TCP sockets.
+* All messages are UTF-8 strings.
+* All message payloads are valid JSON strings.
+* All messages are prefixed with a content-length header (the String.prototype.length() of the payload string as reported by node-js)
+* Message header and payload are always separated with a delimiter, "#"
+* The content-length does not include the length of the header or the delimiter, only the content itself
+
+##Examples
+Here is an example of a data transmission:
+`15#{"type":"ping"}`
+
+Which the receiving end would then split into two parts.
+* The content-length: 15
+* The content: '{"type":"ping"}'
+
+The content could then be parsed into the following JSON object:
+```js
+{
+  "type": "ping"
+}
+```
+
+##Reference Implementations
+There are reference implementations of this API in the following modules:
+* [Node AI-TCP-Server](../ai/ai-tcp-server.js)
+* [He[u]r[istic] AI](../ai/her/hive-ai-her.js)
+* [Rando[m] AI](../ai/rando/hive-ai-rando.js)
+
+More information about running these AI modules can be found [here](hive-cli.md)
+
+##API Specification by Example
+(Taken from [/api/hive_api_v0.1.0_doc.js](../api/hive_api_v0.1.0_doc.js)) Here are some examples of actual messages (request-response pairs) sent from a control program to an AI module and back again:
+
+```js
+// HIVE API VERSION 0.1.0
+
+/*
+"Greetings" request
+  this request type is used to establish the identity of a remote AI module
+  and also to inform the module about the semantic version string of the system.
+*/
+
+// example request structure sent from the game core to an AI module
+{
+  request_type: "Greetings",
+  request_id: "n6Vvi",
+  system_version: "0.1.0"
+}
+// example response structure sent back to the requestor
+// Note: this is the same format as the package.json files bundled with the AI in this, the main Hive project.
+{
+  response_type: "Greetings",
+  response_id: "n6Vvi",
+  name: "rando", // short name / code-name internally used to identify in records involving this module
+  active: true, // whether this AI is considered to be in a usable state by its owner
+  version: "0.0.1", // version of the AI code
+  long_name: "Rando[m]", // display name
+  module: "hive-ai-rando", // [optional] currently only used to locate local AI modules
+  description: "The random monkey AI", // short description; displayed to user
+  author: "Trylobot", // [optional] author(s) of the AI module code
+  project_url: "https://github.com/Trylobot/hive/tree/master/ai/rando", // [optional] url to a project page
+  language: "Javascript" // [optional] primary language used to write the AI module
+}
+
+// ----------------------------------------------------------------------------
+
+/*
+"Choose Turn" request
+  this request type is used to request turns from remote AI modules.
+  the possible turns are enumerated in advance, and the AI is expected to choose one.
+  the board state and the contents of each players' hand is also given.
+  there is no explicit limit on think-time.
+*/
+
+// example request structure sent from the game core to an AI module
+{
+  request_type: "Choose Turn",
+  request_id: "7pNQ4",
+  game_id: "KqwSQ", // used to identify game among multiple simultaneous ongoing games
+  request_timestamp: 1405582952293, // a reference point for the receiver
+  response_deadline: 1405583012293, // response not received by this time? game is thrown in favor of opponent (+/- 5 seconds)
+  game_state: { // intended for direct deserialization (see core/domain/game.js load_game)
+    board: { // (see core/domain/board.js)
+      pieces: { // map<string,array<piece>>: keys are occupied positions, values are piece-stacks
+        "0,0": [ // position at 0,0 contains one piece
+          { // (see core/domain/piece.js)
+            color: "White", // (see core/domain/piece.js colors_enum)
+            type: "Queen Bee" // (see core/domain/piece.js types_enum)
+          }
+        ],
+        "1,1": [ // position at 1,1 contains a stack two pieces high
+          { // ... with the black queen bee on bottom
+            color: "Black",
+            type: "Queen Bee"
+          },
+          { // ... covered by a black beetle
+            color: "Black",
+            type: "Beetle"
+          }
+        ]
+      }
+    },
+    hands: { // hands for both players; keys are piece-type names (see core/domain/piece.js)
+      "White": {
+        "Soldier Ant": 2, // white has two soldier ants
+        "Grasshopper": 1
+      },
+      "Black": {} // omitted keys can be thought of as zero pieces of that type available
+    },
+    player_turn: "White",
+    turn_number: 2,
+    game_over: false,
+    winner: null,
+    is_draw: false,
+    creation_parameters: {
+      use_mosquito: false,
+      use_ladybug: false,
+      use_pillbug: false
+    },
+    turn_history: [
+      { // (see core/domain/turn.js)
+        turn_type: "Placement",
+        piece_type: "Beetle",
+        destination: "0,0"
+      }, 
+      {
+        turn_type: "Placement",
+        piece_type: "Queen Bee",
+        destination: "1,-1"
+      }, 
+      {
+        turn_type: "Movement",
+        source: "1,-1",
+        destination: "-1,-1"
+      }
+    ],
+    possible_turns: {
+      "Placement": { // all data in here is related to placement of new pieces
+        piece_types: [ // list of piece types valid to place this turn
+          "Soldier Ant" 
+        ],
+        positions: [ // list of valid placement positions for any of the above piece types
+          "-2,0",
+          "-1,-1", 
+          "1,-1"
+        ]
+      },
+      "Movement": { // all data in here is related to normal movement of existing pieces
+        "0,0": [ // this lists the valid movement destinations for the piece at this position
+          "2,0",
+          "-1,1"
+        ]
+      },
+      "Special Ability": { // all data in here is related to special abilities (currently pillbug)
+        "0,0": { // pillbug's (or mosquito mimicking pillbug)'s location
+          "1,1": [ // list of valid destinations for the piece at this position, moved by the above pillbug
+            "2,0"
+          ]
+        }
+      }
+    }
+  }
+}
+// example response structure sent back to the requestor
+{
+  response_type: "Choose Turn",
+  request_id: "7pNQ4",
+  game_id: "KqwSQ",
+  turn_type: "Placement",
+  piece_type: "Soldier Ant",
+  destination: "-1,-1"
+}
+// another example
+{
+  response_type: "Choose Turn",
+  request_id: "7pNQ4",
+  game_id: "KqwSQ",
+  turn_type: "Movement",
+  source: "0,0",
+  destination: "2,0"
+}
+// special ability usage
+{
+  response_type: "Choose Turn",
+  request_id: "7pNQ4",
+  game_id: "KqwSQ",
+  turn_type: "Special Ability",
+  ability_user: "0,0",
+  source: "1,1",
+  destination: "2,0"
+}
+// forfeit turn
+{
+  response_type: "Choose Turn",
+  request_id: "7pNQ4",
+  game_id: "KqwSQ",
+  turn_type: "Forfeit"
+}
+```

doc/hive-cli.md

@@ -0,0 +1,37 @@
+#The Hive CLI
+
+  Usage: `$ node hive-cli.js [options] [command]`
+
+  Commands:
+
+    list-ai
+       List all registered Hive AI modules and their statuses
+
+    add-local-ai [name] [local-path]
+       Register a new local AI module (javascript/node.js only) (names must be globally unique)
+
+    add-remote-ai [name] [remote-host-port]
+       Register a new remote AI endpoint (host:port) (names must be globally unique)
+
+    remove-ai [name]
+       Remove a previously-registered AI of any type
+
+    play-single-random
+       Run a single match between two random AI participants selected from the available Hive AI modules
+
+    tournament [participant-list]
+       Run one full single-elimination round-robin tournament between the listed AI participants
+
+    print-config
+       Print currently resolved config options (diagnostic function)
+
+
+  Options:
+
+    -h, --help           output usage information
+    -V, --version        output the version number
+    -m, --use-mosquito   Use the Mosquito
+    -l, --use-ladybug    Use the Ladybug
+    -p, --use-pillbug    Use the Pillbug
+    -d, --turn-deadline  Set the maximum turn time for any single AI turn, in milliseconds
+

doc/hive-node-webkit.md

@@ -0,0 +1,20 @@
+#Hive Node-Webkit UI
+
+* https://www.npmjs.org/package/nodewebkit
+* https://github.com/rogerwang/node-webkit
+
+##Install
+
+```
+$ npm install -g nodewebkit`
+$ cd nw/
+$ npm install
+```
+
+##Run
+
+```
+$ cd nw/
+$ nodewebkit .
+```
+

package.json

@@ -17,7 +17,8 @@
 	},
 	"homepage": "https://github.com/Trylobot/hive",
 	"scripts": {
-		"test": "node test/all-tests.js"
+		"test": "node test/all-tests.js",
+		"start": "nodewebkit nw/."
 	},
 	"engines": {
 		"node": "~0.10.28",
@@ -30,6 +31,7 @@
 		"json-socket": "~0.1.2"
 	},
 	"devDependencies": {
-		"test": "~0.6.0"
+		"test": "~0.6.0",
+		"nodewebkit": "~0.10.4"
 	}
 }