README.md

>_ Screeps ai

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 0.12 or later or iojs 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 [email protected]: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))); }

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