Struct spn_rust_bot::api::Api

pub struct Api<'a> {
    mmap: MmapRaw,
    ipcdata: &'a mut IpcSharedMemory,
}

Your bot’s interface to the game data.

This class provides a safe interface to the shared memory used for fast communication with the gameserver. Use the provided methods to obtain information about your snake’s surroundings or the server configuration, and to access persistent memory.

Please note that most methods return direct references to the shared memory structures. These are specified and documented in the ipc module.

Fields

mmap: MmapRaw

ipcdata: &'a mut IpcSharedMemory

Implementations

impl<'i> Api<'i>

pub fn new(shmfilename: &str) -> Result<Api<'_>, String>

Construct a new Api instance from the given shared memory file.

This function is used internally by the bot framework. Do not worry about it.

pub fn get_server_config(&self) -> &IpcServerConfig

Get a reference to the server config data.

The returned structure contains information about the server configuration and static world information.

pub fn get_self_info(&self) -> &IpcSelfInfo

Get a pointer to the self information.

The returned structure contains information about your snake and parameters of the world.

pub fn get_food(&self) -> &[IpcFoodInfo]

Get a reference to the array of food items around your snake’s head.

The items are sorted by the distance from your snake’s head, so the first entry is the closest item.

Only the valid entries in the shared memory are returned.

pub fn get_segments(&self) -> &[IpcSegmentInfo]

Get a reference to the array of snake segments around your snake’s head.

The items are sorted by the distance from your snake’s head, so the first entry is the closest item.

Only the valid entries in the shared memory are returned.

pub fn get_bot_info(&self) -> &[IpcBotInfo]

Get a reference to the array of bot information structures.

Only the valid entries in the shared memory are returned.

pub fn clear_colors(&mut self)

Remove all color entries from the shared memory.

This must be called in your crate::usercode::init() function to remove the default color in case you want to set your own.

pub fn add_color(&mut self, r: u8, g: u8, b: u8)

Add a color to your snake’s color sequence.

Call this multiple times from crate::usercode::init() to set up your snake’s colors. The provided sequence will be repeated along your snake if it has more sequence than colors were specified. You can set up to ipc::IPC_COLOR_MAX_COUNT colors.

pub fn get_persistent_memory(&mut self) -> &mut [u8]

Get a reference to the persistent memory.

You can use persistent memory to remember things across multiple lives of your snake. It is saved after your snake dies (even when your code crashes) and restored when it respawns.

Note that the size this memory is very limited (given by the ipc::IPC_PERSISTENT_MAX_BYTES constant). Use it wisely.

pub fn log(&mut self, text: &str) -> Result<(), String>

Send a log message.

These messages will appear on the web interface and in the World update stream when you provide your viewer key to the server.

Rate limiting is enforced by the gameserver, so messages are dropped when you send too many of them.