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.