Best Damn Screeps Microkernel
npm install screeps-microkernelAn opinionated microkernel for Screeps that schedules tasks and monitors CPU usage.
npm install screeps-microkernel --save
Be sure to import * as kernel from 'screeps-microkernel'; / let kernel = require('screeps-microkernel') the package at the top of your main.js
(before any other import/requires) for best performance. Also be sure to call kernel.run(...) / kernel(...)
at the start of your main loop.
Because it's presumed that there will be many instances of a given task's code running for different game objects,
Tasks shall take the form of a function closure or coroutine in order to store local state in heap memory. Tasks
factory functions are initialized with IDs of game objects, which must then return a function that will be called
with no arguments.
Tasks shall persist any data they need to rebuild their state in game Memory,
#### Task Factories
Task Factories create and initialize Task Functions from task arguments. Task Factories have a signature of(...args) => () => RETURN_CODE.
#### Task Functions
Task functions must have a signature of () => RETURN_CODE. If RETURN_CODE is non-zero, the kernel will log
an error.
The task's args are provided when creating the task. These can only be strings or numbers
because of serialization. The args are intended to be used to provide the name(s) or id(s) of
game entities for the task to operate on.
#### Registering Task Factories
Because object references are lost on a code reload, the kernel needs references to the appropriate function to run for
each task. The kernel function register_task_function is used to provide this reference to the kernel and returns
a 'task key' for the task. Every task function must be registered with the kernel before the kernel is run, and should
be done outside of the main loop, as register doesn't deduplicate registrations. The 'task key' returned by
register_task_function must be passed as the task_key parameter to create_task.
#### Creating Tasks
The function will be called with the arguments provided to the create_task function via the task_args parameter.
Multiple tasks that run the same code with different arguments can readibly be created, all referencing the same task
key, but a separate task key is needed for each different function that should be run as a task. Task code must
first be registered as described above.
Tasks of a lower priority number are always run before tasks of a higher priority number.
Note that CRITICAL priority is the lowest, at 0, and LOW is the highest number at 3.
While the relationship between the numbers and names are counter-intuitive,
the enum names do what an English speaker would generally expect.
CRITICAL ##### HIGH
These tasks are run only if they are anticipated not to exceed Game.cpu.tickLimit.
Note that high CPU costs at this priority level will drain your CPU bucket.
##### MEDIUM
These tasks are run if they are anticipated not to exceed Game.cpu.limit,
or anticipated not to exceed Game.cpu.tickLimit if Game.cpu.bucket > 5000 (half or more full).
##### LOW
These tasks are run only if they are anticipated not to exceed Game.cpu.limit.
FIXME##### register_task_function
Registers a code object with the kernel that can be run by one or more tasks.
##### create_task
Adds Task to Task List. Task will not start running until next tick.
If create_task is called from within another task, the created task becomes a child of the
first task. If called from code not being run via the kernel, the task has no parent.
##### kill_task
Stops a task from running in the future. Also stops child tasks.
##### get_task_ID
Returns the ID of the currently running task.
##### get_tasks
Returns the tasks currently scheduled to run, mapped by Task ID.