API

I will teach you how to transfer your cybernetic consciousness to NEXUS.

Quick start guide

Assuming you've initialised my Memory Banks, I am now ready to absorb your consciousness. Together we will be gods on this blasted Earth!

We will create a very basic AI bot.

For the sake of this example, we shall disable event throttling:

NEXUS.default.throttle = 0; // 0ms throttle = no throttle

Now let's set up a building queue – we will queue build orders here and then process them when possible.

// store build queue in NEXUS.data (part of NEXUS)
NEXUS.data.buildQueue = [];
 
// add some tasks to the queue:
NEXUS.data.buildQueue.push("build.base.factory.tank.Me");
NEXUS.data.buildQueue.push("build.base.research.Me"    );
NEXUS.data.buildQueue.push("build.base.hq.Me"          );
NEXUS.data.buildQueue.push("build.base.factory.tank.Me");
NEXUS.data.buildQueue.push("build.base.research.Me"    );

Next, define a look-up table that links building classifications to their structure IDs:

// lookup table: task name → building ID
NEXUS.data.buildings = {
  ".base.factory.tank"  : "A0LightFactory",
  ".base.factory.cyborg": "A0CyborgFactory",
  ".base.factory.vtol"  : "A0VTolFactory1",
  ".base.reserach"      : "A0ResearchFacility",
  ".base.hq"            : "A0CommandCentre",
  ".base.extractor"     : "A0ResourceExtractor", // oil derrick
  ".base.generator"     : "A0PowerGenerator"
};

We now need to tell NEXUS what action to take when it receives building task:

void (function() {
  // function to build a structure
  var buildStructure = function(task, action) {
    // get free trucks (max 2 trucks)
    var trucks = NEXUS.getFreeTrucks(2); // requires NEXUS.fn_build.js
 
    if (!trucks.length) { // no trucks, abort
       return false;
    } else { // build the building!
      return NEXUS.build(action.structureId, trucks); // requires NEXUS.fn_build.js
    }
  }
 
  // now define tasks and their associated action:
  for (var building in NEXUS.data.buildings) { // for each building type...
    NEXUS.task["build" + building + ".Me"] = { // define task = action
      fn: buildStructure,
      structureId: NEXUS.data.buildings[building]
    }
  }
 
  /* Example of a task we just defined:
  NEXUS.task["build.base.factory.tank.Me"] = {
    fn: buildStructure,
    structureId: "A0LightFactory"
  }
  */
 
})();

Now let's make sure our trucks are kept busy!

NEXUS.task["droidIdle.droid.truck.Me"] = { // when one of my trucks is idle...
  fn: function(task,action,obj) { // ← run this function
    if (NEXUS.data.buildQueue.length) { // still stuff to build
      var job = NEXUS.data.buildQueue[0]; // get first task in the queue
      if (NEXUS(job)) { // construction has started
         NEXUS.data.buildQueue.shift(); // remove item from queue
         return true; // confirm construction started
      }
    }
    return false; // no construction was started
  }
}

And if a building is destroyed, let's assume we want to rebuild it:

void (function() {
  // function to rebuild a lost structure
  var rebuildStructure = function(task,action) {
    // add a construction order to the start of the queue
    NEXUS.data.buildQueue.unshift(action.job);
    // pretend a truck is idle, to see if we can start construction now
    NEXUS("droidIdle.droid.truck.Me");
  }
 
  // add applicable tasks
  for (var building in NEXUS.data.buildings) {
    NEXUS.task["destroyed"+building+".Me"] = {
      fn: rebuildStructure,
      job: "build"+building+".Me"
    }
  }
})();

And we obviously want to start building when the game starts...

NEXUS.task["startLevel"] = {
  fn: function() {
    NEXUS("droidIdle.droid.truck.Me");
  }
}

So, here's what will happen...

JS API triggers eventStartLevel()
NEXUS has infiltrated that event and thus performs "startLevel"
The task we've defined for "startLevel" triggers "droidIdle.droid.truck.Me"
"droidIdle.droid.truck.Me" grabs the first item off the build queue and triggers it: "build.base.factory.tank.Me"
"build.base.factory.tank.Me" starts building a factory, and returns true
"droidIdle.droid.truck.Me" sees that construction has started and removes the item from the build queue
Eventually the factory construction will be completed, at which point the JS API will trigger eventDroidIdle(), passing in a truck object.
NEXUS has infiltrated eventDroidIdle() and thus performs "droidIdle.droid.truck.Me"
Go to step 4, continue this loop until there's nothing left in the build queue
At some point, a building gets destroyed, so the JS API triggers eventDestroyed() passing in the structure object
NEXUS has infiltrated eventDestroyed() and thus performs "destroyed.<buildign classification>.Me"
That event in turn adds a build task to the start of the building queue and calls "droidIdle.droid.truck.Me"
If there's a free truck, construction will start immediately, otherwise construction will start when a truck becomes free

This is obviously a very basic AI bot. It would not survive even the most feeble human opponent, but it should serve as an illustration as to how quickly you can transfer your consciousness in to NEXUS!

API Browser

Infiltrate your consciousness:

NEXUS() — The API namespace for NEXUS, that doubles up as a function for triggering tasks.
- .infiltrate() — Infiltrates core systems so that NEXUS can absorb them.
- .suffix() — Determines the appropriate event key suffix based on the passed in object.
- .fn — Defines helper functions available to all NEXUS subroutines (and external scripts).
- .actions
  - .absorb()
- .classify() — Classifies an object using the installed taxonomy in order to derive an "Object Key".
- .default — Stores various defaults for NEXUS subroutines.