cargo-screeps
Build tool for deploying Rust WASM code to Screeps game servers.
Best used with screeps-game-api
.
This implements type-safe WASM bindings to the Screeps in-game API.
This is not fully tested, but feel free to use! Issues are welcome.
Build Options
build
:
Configured in [build]
config section. No required settings.
- run https://github.com/koute/cargo-web to actually build rust source
- strip off header / surrounding function
cargo-web
generates for a generic JS file to load from web or from local filesystem - append initialization call using bytes from
require('<compiled module name>')
- put processed JS into
target/main.js
copy compiled WASM intotarget/compiled.wasm
upload
:
Requires [upload]
config section with at minimum username, password and branch.
- run build
- read
target/*.js
andtarget/*.wasm
, keeping track of filenames - read
screeps.toml
for upload options - upload all read files to server, using filenames as the filenames on the server
copy
:
Requires [copy]
config section with at minimum destination and branch.
- run build
- copy compiled main file and WASM file (default
main.js
andcompiled.wasm
) fromtarget/
to<destination directory>/<branch name>/
- if pruning is enabled, delete all other files in
<destination directory>/<branch name>/
deploy
:
Requires default_deploy_mode
configuration setting.
- run build
- run
upload
orcopy
depending on thedefault_deploy_mode
configuration option
check
:
Does not require configuration.
- perform type checking / lifetime checking without compiling code
- runs
cargo web --check --target=wasm32-unknown-unknown
which is fairly similar tocargo check
.
Configuration Options
No namespace
-
default_deploy_mode
: controls whatcargo screeps deploy
doesThis configuration is required for
cargo screeps deploy
. Possible values are"copy"
and"upload"
.
[upload]
Options for the upload
deploy mode.
This section is required to use cargo screeps upload
.
-
username
: your Screeps username or email -
password
: your Screeps passwordFor private servers set a password using screepsmod-auth.
-
branch
: the branch on the server to upload files to -
ptr
: if true, upload to the "ptr" realm -
hostname
: the hostname to upload toFor example, this could be
screeps.com
,localhost
orserver1.screepsplu.us
. -
ssl
: whether to connect to the server using sslThis should generally be true for the main server and false for private servers.
-
port
: port to connect to server withThis should generally be set to
21025
for private servers.
[copy]
Options for the copy
deploy mode.
This section is required to use cargo screeps copy
.
-
destination
: the directory to copy files intoIf this path is not absolute, it is interpreted as relative to
screeps.toml
-
branch
: the "branch" to copy intoThis is the subdirectory of
destination
which the js/wasm files will be copied into. -
prune
: if true, extra files found in the destination/branch directory will be deleted
[build]
This configures general build options.
output_js_file
: the javascript file to export bindings and bootstrapping as (default"main.js"
)output_wasm_file
: the WASM file to rename compile WASM to (default"compiled.wasm"
)initialize_header_file
: a file containing the JavaScript for starting the WASM instance. See overriding the default initialization header
Overriding the default initialization header
cargo-screeps
tries to make a reasonable main.js
file to load the WASM. However, it's pretty
basic, and you might find you want to do some things in JavaScript before loading the WASM module.
Luckily, you can override this initialization! Set build.initialize_header_file
to a file
containing the JavaScript initialization code.
Two utility functions wasm_fetch_module_bytes
and wasm_create_stdweb_vars
will always be
created, but the initialization header controls what actually runs.
See [docs/initialization-header.md] for more information on this.
Updating cargo screeps
As it parses the unstable output of cargo-web
, cargo-screeps
is highly dependent on cargo-web
version. It is recommended to upgrade both together.
Installing a version of cargo-web
newer than what cargo-screeps
supports will cause it to
output an error on build. If this happens, please create an issue on this repository and we can
update cargo-screeps
. Updating it is simple, but it needs to be done every time cargo-web
changes the output format, and we might not realize that has happened.
After updating, you'll want to do a full cargo clean
to remove any old artifacts which were built
using the older version of cargo-web
.