Crate mcinterface

Wrapper library for wasmcraft2 datapacks written in Rust.

wasmcraft2 is a WebAssembly to Minecraft datapack transpiler. This library provides safe access to wasmcraft’s API, containing all functions present in wasmcraft’s mcinterface.h as well as some additional helper functions and macros.

When writing programs for wasmcraft2, it is important to note its limitations - notably, floating point operations are not supported, so using the fixed crate is recommended if integers are not enough. Minecraft programs must be #![no_main] and #![no_std]; this crate provides a Minecraft-compatible panic handler but there is no allocator. Decreasing the default stack size is recommended - you can do this by adding the following to your .cargo/config:

[target.wasm32-unknown-unknown]
rustflags = [ "-C", "link-args=-z stack-size=4096" ]

If more stack space is required, you can change 4096 to some greater number.

While you’re in .cargo/config, you should also set the default target to wasm32-unknown-unknown

[build]
target = "wasm32-unknown-unknown"

Enabling some optimisation even in debug builds is recommended, since Minecraft commands are not the fastest compilation target ever - add the following to your Cargo.toml:

[profile.dev]
opt-level = 1

wasmcraft2 does not support the main function - your entrypoint must be declared as follows:

#[no_mangle]
pub extern fn _start() -> i32 {
    // Your code goes here...
    return 0;
}

Modules

fmt

Utilities for string formatting.

Macros

env_i32_default

Get an i32 value from the compile-time environment, or if the environment variable is not present or is not an i32, use the provided default value.

print

An implementation of print! using MciWriteStream. Should behave similarly to std::print!, with the caveat that no text will be printed until a newline is printed (due to the fact that Minecraft has no way of modifying a line of text in the chat once it has been sent), and any characters that are not printable ASCII characters will appear as �.

println

An implementation of println! using MciWriteStream. Should behave similarly to std::println!, with the caveat that any characters that are not printable ASCII characters will appear as �.

Enums

Block

An enum representing a Minecraft block. This contains all the block types currently supported by wasmcraft2, which is a very limited subset of Minecraft’s block selection. There is currently no way to place any other blocks through wasmcraft2.

Functions

mc_putc

Write a character to the game chat. Characters will not appear until a newline ('\n') is written.

mc_sleep

Pauses execution until the next game tick.

memset^⚠

Set all bytes in a region of memory (with length length, starting from ptr) to value.

print

Print an integer to the Minecraft chat.

print_str

Print a string to the game chat. Any printed characters will not appear until a newline ('\n') is written. Only ASCII printable characters will be printed; any other characters will appear as a � symbol.

println

Print a string to the game chat, with a newline. Only ASCII printable characters will be printed; any other characters will appear as a � symbol.

turtle_check

Check if the given block is present at the turtle’s position.

turtle_copy

Copy the block at the turtle’s position.

turtle_copy_region

Copy a given region from the turtle’s position.

turtle_fill

Fills a volume relative to the turtle’s postion. The x, y, and z span arguments are effectively the size of the region minus one, so turtle_fill(block, 0, 0, 0) is equivalent to turtle_set(block)

turtle_get

Get the block at the turtle’s position.

turtle_paste

Place the previously copied block at the turtle’s position.

turtle_paste_region_masked

Paste the previously copied region from the turtle’s position, ignoring air blocks.

turtle_pos

Set the position of the turtle. This will call turtle_x, turtle_y and turtle_z, so it is more efficient to call those individually if you do not need to change all 3 coordinates.

turtle_set

Set the block at the turtle’s position.

turtle_x

Set the x position of the turtle

turtle_y

Set the y position of the turtle.

turtle_z

Set the z position of the turtle.