Bot scripting guide

Development
#1

This text will only explain the basics of how to create bot scripts using bot tokens.
There are currently no resources that describing the full API. Instead, one can try to learn from looking at the mucklet-bot or the mucklet-client repositories.

Create bot token

(Only available for supporter and pioneer accounts)

Bot tokens are are used for authentication when connecting to the API with a script to control the character.

To issue a bot token, go to Character Settings (click the cog-icon for the character on the Character Select page). A new section, Bot token, lets you issue, delete, and copy (to clipboard) tokens:

image

Connect to the API

Once a token is issued, it can be used as authentication when connecting to the API.

Example using node.js

import ResClient from 'resclient';

// ResClient is used to connect to the Resgate based API.
// The mucklet test server can be used for bot development.
let client = new ResClient('wss://api.test.mucklet.com');

// Configure client to authenticate using the issued bot token
client.setOnConnect(client => client.authenticate('auth', 'authenticateBot', {
	token: 'OMUGQPU5A5JX3OUPO74TIE2UJO5H7BOU',
}));

// Connect to the API to:
//   1) get the bot model
//   2) control the bot character
//   3) wake up the character
//   4) say "Hello" to the room
//   5) sleep and release control of the character
client.call('core', 'getBot')
	.then(bot => bot.call('controlChar'))
	.then(char => char.call('wakeup')
		.then(() => char.call('say', { msg: "Hello!" }))
		.then(() => char.call('release'))
	);

Note

The above example is simplified, untested, and doesn’t handle any errors.

Difference between client API and bot API

When using a bot token to authenticate, the API will be slightly different than the one used by the client. Some of the main differences are as follows.

Authentication

When authenticating with a bot token, the auth.authenticateBot authentication method is used instead of the auth.authenticate method that is used by the client.

Bot model instead of player model

Instead of calling core.getPlayer to get the player model, a bot script calls core.getBot to get the bot model.

The bot model is simpler and only contains two properties.

Property Description
char The owned character model with basic character info for owner.
controlled The controlled character model with detailed info about the room, who they are looking at, etc. The value is null if the character is not controlled by the bot script.

Call cooldown instead of flood filter

Unlike the client API, the bot API will not return an error on command flooding. Instead, the bot API will add a short cooldown to a command execution. Any subsequent command will be delayed until the cooldown duration has passed.

The cooldown is usually 500 milliseconds, but may be longer for certain commands.

No user/player info

It is not possible to access any information about the user when accessing the API using a bot token.

Restricted access

A bot script have restricted access to player level features such as:

  • read or manage player notes
  • read or send mail
  • read or manage the watch list
  • read or manage player requests
  • call player level methods, such as createChar, deleteChar, or setPreference

No dual control

It is not possible to simultaneously control a character using both the client and a bot script.

API Questions

If you have questions regarding the API, feel free to post questions in the #development category.

Mucklet-bot repository

The mucklet-bot repository is a project mainly created for the purpose of stress testing the server. It has now been updated to connect using bot tokens instead of using the client API.

Release v1.45.0 - Bot tokens
Seeking Documentation for Platform Features