Starter Rust AI for Screeps: World, the JavaScript-based MMO game.
This uses the screeps-game-api
bindings from the rustyscreeps organization.
wasm-pack
is used for building the Rust code to WebAssembly. This example uses Rollup to
bundle the resulting javascript, Babel to transpile generated code for compatibility with older
Node.js versions running on the Screeps servers, and the screeps-api
Node.js package to deploy.
Documentation for the Rust version of the game APIs is at https://docs.rs/screeps-game-api/.
Almost all crates on https://crates.io/ are usable (only things which interact with OS apis are broken).
# Install rustup: https://rustup.rs/
# Install wasm-pack
cargo install wasm-pack
# Install wasm-opt
cargo install wasm-opt
# Install Node.js for build steps - versions 16 through 22 have been tested, any should work
# nvm is recommended but not required to manage the install, follow instructions at:
# Mac/Linux: https://github.com/nvm-sh/nvm
# Windows: https://github.com/coreybutler/nvm-windows
# Installs Node.js at version 20
# (all versions within LTS support should work;
# 20 is recommended due to some observed problems on Windows systems using 22)
nvm install 20
nvm use 20
# Clone the starter
git clone https://github.com/rustyscreeps/screeps-starter-rust.git
cd screeps-starter-rust
# note: if you customize the name of the crate, you'll need to update the MODULE_NAME
# variable in the js_src/main.js file and the module import with the updated name, as well
# as the "name" in the package.json
# Install dependencies for JS build
npm install
# Copy the example config, and set up at least one deployment mode.
cp .example-screeps.yaml .screeps.yaml
nano .screeps.yaml
# compile for a configured server but don't upload
npm run deploy -- --server ptr --dryrun
# compile and upload to a configured server
npm run deploy -- --server mmo
Versions of screeps-game-api
at 0.22 or higher are no longer compatible with the
cargo-screeps
tool for building and deployment; the transpile step being handled by Babel is
required to transform the generated JS into code that the game servers can load.
To migrate an existing bot to using the new JavaScript translation layer and deploy script:
- Create a
.screeps.yaml
with the relevant settings from yourscreeps.toml
file applied to the new.example-screeps.yaml
example file in this repo. - Add to your
.gitignore
:.screeps.yaml
,node_modules
, anddist
- Create a
package.json
copied from the one in this repo and make appropriate customizations.- Importantly, if you've modified your module name from
screeps-starter-rust
to something else, you need to update thename
field inpackage.json
to be your bot's name.
- Importantly, if you've modified your module name from
- Install Node.js (from the quickstart steps above), then run
npm install
from within the bot directory to install the required packages. - Copy the
deploy.js
script over to a newjs_tools
directory. - Add
main.js
to a newjs_src
directory, either moved from your existingjavascript
dir and updated, or freshly copied.- If updating, you'll need to change:
- Import formatting, particularly for the wasm module.
- wasm module initialization has changed, requiring two calls to first compile the module, then to initialize the instance of the module.
- Whether updating or copying fresh, if you've modified your bot name from
screeps-starter-rust
you'll need to update the bot package import andMODULE_NAME
at the beginning ofmain.js
to be your updated bot name.
- If updating, you'll need to change:
- Update your
Cargo.toml
with version0.22
forscreeps-game-api
- Run
npm run deploy -- --server ptr --dryrun
to compile for PTR, remove the--dryrun
to deploy
If you encounter an error like the following:
Error: Not Authorized
at ScreepsAPI.req (PATH_TO_YOUR_BOT/node_modules/screeps-api/dist/ScreepsAPI.js:1212:17)
at process.processTicksAndRejections (node:internal/process/task_queues:105:5)
at async ScreepsAPI.auth (PATH_TO_YOUR_BOT/node_modules/screeps-api/dist/ScreepsAPI.js:1162:17)
at async ScreepsAPI.fromConfig (PATH_TO_YOUR_BOT/node_modules/screeps-api/dist/ScreepsAPI.js:1394:9)
at async upload (PATH_TO_YOUR_BOT/js_tools/deploy.js:148:17)
at async run (PATH_TO_YOUR_BOT/js_tools/deploy.js:163:3
Then the password in your .screeps.yaml
file is getting picked up as something aside from a string. Passwords sent to the server must be a string. Wrap it in quotes: password: "12345"
If you encounter an error like the following:
Error: Unknown module 'bot-name-here'
at Object.requireFn (<runtime>:20897:23)
at Object.module.exports.loop (main:933:33)
at __mainLoop:1:52
at __mainLoop:2:3
at Object.exports.evalCode (<runtime>:15381:76)
at Object.exports.run (<runtime>:20865:24)
You need to make sure you update your package.json
name
field to be your bot name.
If you encounter an error like the following:
CompileError: WebAssembly.Module(): Compiling wasm function #327:core::unicode::printable::check::h9ddbb57eb721c858 failed: Invalid opcode (enable with --experimental-wasm-se) @+257876
at Object.module.exports.loop (main:934:35)
at __mainLoop:1:52
at __mainLoop:2:3
at Object.exports.evalCode (<runtime>:15381:76)
at Object.exports.run (<runtime>:20865:24)
You need to update your Cargo.toml
to include the --signext-lowering
flag for wasm-opt
. For example:
[package.metadata.wasm-pack.profile.release]
wasm-opt = ["-O4", "--signext-lowering"]