`>_` Screeps ai

_{* Covered files only}

The main goal of this project is to provide a flexible framework for the ai.

Don't know anything about screeps?

Go to screeps.com or you could try 🍕💩.ws/🐯🔮👊🍋😜🐱🍩🐰

Install checklists

First install

Make sure node 2.4 or later is installed.
Open a terminal and install grunt with npm like this: npm install -g grunt-cli.
If you are familiar with git, you can clone from git@github.com:avdg/screeps.git.
- Otherwise you can get the latest code from github.
Make now sure the terminal is pointing to this project. Then run npm install to install dependencies.

Build configuration

Open settings.js in an editor (if the file is not available, run grunt in console), fill in the options and save the file.
In a terminal open in a copy of this project: type grunt deploy
If done properly, this should push the code to screeps.com succesfully.

AI build tricks

grunt codegen: Build generated code
grunt deploy: Pushes code to screeps.com
grunt run: Run the bot in a fake and incomplete simulator
grunt test: To make sure that the code is passing the checks
grunt is currently set to grunt test
mocha is available for testing purposes

`Code` structure

In the current structure there are only 2 files generated for deployment. The first file is an auto generated main.js, which is the compiled version of all the extension directories sticked together. The second file contains settings, allowing to fine tune settings in-game.

scripts/main.js is the boot file and is the first user code to be executed, its being executed once a tick in the screeps sandbox.

Also note that not all code of my current ai are included in this repo. The private ai code I deploy are just other extensions.

Ai rules / Ai constrains

All creeps must have a role, or receive a role after being triggered by the noRole event

AI script files

_settings.js Drain for global AI settings.

AI Object

When the autogenerated main.js gets executed, it will expose an AI object in global scope.

The AI object has _settings included as AI.settings, so there is no need to include this file. It also includes code from extensions accessible from AI.extensions.

_generated is a generated file that only exists in the build/deploy folder when using grunt deploy or grunt codegen

Extensions folder structure

After using require('_generated') it will expose the extensions as AI.extensions.<type>.<plugin>.

These files are coming from the extensions/ directory with a structure as extensions/<package>/<type>/<plugin>.

These include all files ending with .js, excluding the files starting with a . like .thisFileWillBeIgnoredAnyway.js or located in directories starting with a '.'.

When generating the extensions, all packages are virtually merged into a single package. This is how it ends up using the AI.extensions.<type>.<plugin> format.

Current extension types are:

commands
- Located at extensions/<any directory>/commands/
- Executes flag commands
- Used when called by extensions/tools/hooks/flags or AI.exec(<command>, ...)
hooks (replaced units)
- Located at extensions/<any directory>/hooks/
- Events when hooks are called:
  - firstTurn: Called when the AI is doing its first turn
  - preController: Called before giving spawns and creepers orders
  - postController: Called before shutting down the AI
  - noRole: Called when a creep has no role
    - First parameter is creep name
    - Accepts a return value
    - Since an event can trigger multiple hooks, the new role will only be accepted when the received role is non-conflicting (multiple hooks returning the same result is fine, undefined means withold, all undefined means no role).
  - noSpawn: Called when a spawn has nothing to spawn
    - First parameter is spawn
    - Second parameter is a function to spawn something, simply pass a type or a creep memory object
library
- Contains library functions
- Module.exports keys are accessible as AI[key]
roles
- Located at extensions/<any directory>/roles/
- Gives creeps orders
- Called by stage_creeps, the plugin with the corresponding Creep.memory.role will be executed
routines
- Located at extensions/<any directory>/routines/
- Place to store routines that can be shared to multiple roles of creeps
- function routine returns boolean
  - When true it means it has successfully completed its routine
  - When false it means it has not been able to do the routine
targets
- Collects or filters to get certain type of objects
- Usable by AI.get(target, options) or Room.get(target, options) for getting objects
- AI.extensions.target.filter contains customizable filters
scripts
- Used to store scripts, allowing them to be executed later
- module.exports expects to be a function
- AI.extensions.scripts.main will be executed unless extensionsBootstrap is set to false at the code generator

Ai code

scripts/main is the boot file. From there it includes other files in the script/ directory. Most of these scripts (called stages) utilizes code from extensions.

Bonus: run code after turn

Set global.run with a function at wish, and it will be executed after the turn.

For example, this code can be typed or pasted in to the console:

global.run = function() { console.log(JSON.stringify(Object.keys(AI))); }

// Or using the es6 arrow syntax
global.run = () => {console.log(JSON.stringify(Object.keys(AI))); }

Call hierarchy

 `- Start timer
 `- Run extensions/**/scripts/main.js and friends
 |   `- `stage_setup()` Prepares game state for AI
 |   `- `AI.emit("firstTurn") Triggers firstTurn hook if current turn reboots the AI
 |   `- `AI.emit("preController")` Triggers firstTurn hook
 |   `- `stage_creeps()` Iterates over every creep (give orders)
 |   `- `stage_spawners()` Iterates over every spawner (give spawn jobs)
 |   `- `AI.emit("postController")` Shutdown and triggers postController hook
 `- Stop timer

Notes

Current tools don't allow es6 features for deployable code.
- UglifyJS2 simply doesn't support es6 just yet
- Blanket isn't upgraded to a version with es6 support
- Note that test cases and live code can be written using the new es6 syntax as they aren't processed by these tools

avdg/screeps

>_ Screeps ai