Mucklet Python API Release Notes

#1

I’ve made a few bot api’s in the past.

However they were all bodged together and have their own bugs and lack of features.

I am proposing to build a new API that has all the required features to build feature rich bots with high and low level features to use.

I’ve made a base API so far, but it has a long way to go before it is ready for production ^w^

So please could you answer these polls so I can have a better idea of what needs to be added ^w^

Are you a supporter?
  • Yes
  • No

0 voters

Would you use the API to build a bot?
  • Yes
  • No

0 voters

What features would you want implemented?
  • Bot traveling (being able to move around the world)
  • Bot summoning (being able to summon the not)
  • Multiple bot support (have multiple bots being run from the same script)
  • Low level Access to all incoming and outgoing traffic
  • Website linking (be able to construct links to html pages hosted within the script)

0 voters

Comment any other features you may want, obviously the bot will have the common support for communication.

#2

What I really want is bot omnipresence, them being able to remotely know who is in certain rooms, read all tagged messages in multiple controlled rooms and post descriptions remotely.

I guess it could be implemented with scripts that are hinted as a future update by Accipiter.

1 Like
#3

Hmm, wouldn’t that be a privacy concern?

1 Like
#4

I don’t think so. Bots already exist and can possibly log whatever is going on in rooms they are in. The main difference would be increasing their range of operations to multiple rooms. Of course, technical implementation is probably more complicated than that.

  1. Room owner has to allow every unique bot to have presence in the room. That way you won’t have to worry about bots logging your rooms without permission.

  2. Bots that are allowed to operate remotely in a room should be listed in room occupant list, but not count as active players. You will always know if a bot can read your messages.

  3. If reasons above are not enough to ease your concern, there may be some system in place that will allow a player’s posts to become invisible to bots. Personally I don’t think it’s necessary.

  4. Bots are already only available to supporters and higher ranks. That surely has to lift some concerns.

1 Like
#5

Hmm, I will think about this, the main problem is that the server will not tell you or bots what is going on outside of the room your in. (There may be some clever work around). I think the best way of doing this would be to have a bot in every room all controlled by the same script that communicates to a main bot.

I will try subscribing to rooms the bot isn’t in, but with how secure wolfery already is, I doubt it will work without some higher access to the server.

1 Like
#6

That is why I have high hopes for future realms and scripting updates. If scripts can’t neatly connect multiple rooms into a single hidden network bots will be able to use, then maybe realm owners will have the necessary access.

So far my little knowledge of how this site works isn’t enough to guess how hard would technical implementation be.

1 Like
#7

What would you actually use it for?

1 Like
#8

I have certain plans for when I can create my own realm. Bots will be used as tools for features like property and inventory. While I know how I can do this with existing functionality, the requested feature would help me a lot.

I don’t want to give any more details here publicly before I have something concrete to present.

1 Like
#9

Hmmm, I’ll look into it when the custom realms are released. Although I don’t know if it’s even possible.

1 Like
#10

yawn I’ve finished the majority of the client already…

All that’s left is the following:

  1. ResClient needs to keep track of direct and indirect subscriptions (idk why it needs to but apparently it does) [Deprecated]
  2. Experiment with running multiple bots off the same ResClient to prevent multiple caches of the same data [Deprecated]
  3. Improve the Character class to automatically assign data from just an id [Done]
  4. Learn how rooms work within the client and re-write it like so. [Done]
  5. Add the access request [Not required]
  6. Add the set request [Not required]
  7. Tidy the code so that it’s easier to learn about how it works. [Done]
  8. Write tests and test the code [Semi Done, more to do after release]
  9. Fix any bugs [Fixed those found]
  10. Write docs [Done]
  11. Release it to all ya cuties ^w^ [Done]
1 Like
#11

Completed :partying_face:

For any problems, let me know here and I will try and address them as fast as I can.

1 Like
#12

Mucklet Bot - Docs (V1.0)

This documentation provides a brief overview of the Mucklet Bot library and demonstrates how to use it to create
and manage a bot for Mucklet’s text-based virtual world.

Instalation

simply download the repository as a zip file then extract it. (pip install will be availble in a future release)

Then run the following

pip install json
pip install websocket-client

you may need to uninsatll any other websocket library if any errors occur

Getting Started

To create a bot follow these steps to get set up

1 - Import the neccesarry modules

from Mucklet import Bot, ResClient, Logger
import random

2 - Setup are a logger (not neccesarry)

log_message = Logger((200, 200, 50)) # These are RGB values

3 - Create the client, this is like the communication between the server and the bot.

client = ResClient("wss://api.test.mucklet.com", "https://test.mucklet.com") # host, origin

It is advised to test a bot on the testing realm, failure to do so could result in being banned.

4 - Initiate the bot.

bot = Bot("< Put Your Bot Token Here >", client) # Your bot token, the client connection

Make sure to replace < Put Your Bot Token Here > with your bot token or the bot will crash

5 - add a listener

@bot.on("say") # when the bot hears a say message
def on_say(message):
    log_message(message.event.message) # we will log the message we recieved
    bot.say(message.event.message) # then have the bot say the message that it recieved (it will not respond to itself)

6 - boot the bot

bot.boot() # start the bot
# any code below will be run after the bot has finished booting

Event Handling

The Mucklet Bot library allows you to handle various in-game events by attaching event handlers. Below is a list of all the events that can be listened for:

  • say: Triggered when a character says something.
  • pose: Triggered when a character poses.
  • wakeup: Triggered when a character wakes up.
  • sleep: Triggered when a character goes to sleep.
  • leave: Triggered when a character leaves a room.
  • arrive: Triggered when a character arrives in a room.
  • describe: Triggered when a character describes something.
  • action: Triggered when a character performs an action.
  • ooc: Triggered when a character sends an out-of-character message.
  • whisper: Triggered when a character whispers to another character.
  • message: Triggered when a character sends a message to the bot.
  • warn: Triggered when a character warns the bot.
  • mail: Triggered when the bot receives mail.
  • address: Triggered when a character addresses another character.
  • controlRequest: Triggered when the bot receives a control request.
  • travel: Triggered when the bot starts traveling to another room.
  • leadRequest: Triggered when the bot receives a lead request.
  • followRequest: Triggered when the bot receives a follow request.
  • follow: Triggered when the bot starts following a character.
  • stopFollow: Triggered when the bot stops following a character.
  • stopLead: Triggered when the bot stops leading a character.
  • summon: Triggered when a character summons another character.
  • join: Triggered when a character joins another character.

You can attach event handlers to these events using the on method of the Bot class, as shown below:

@bot.on("say")
def on_say(message):
    # Handle the "say" event
    # ...

Here are some examples of event handlers that demonstrate how to respond to specific events:

1 - Say example

@bot.on("say")
def on_say(message):
    log_message(f"{message.event.character} says \"{message.event.message}\"")
    bot.say(message.event.message)

2 - Summon Example

@bot.on("summon")
def on_summon(message):
    log_message(f"{message.event.character} summons {message.event.target}")
    message.event.character.join()

3 - Multiple listeners example

@bot.on("whisper", "address", "message")
def on_target(message):
    log_message(f"{message.event.character} targets {message.event.target} with \"{message.event.message}\"")
    message.event.character.message(message.event.message)

Bot methods:

  • Bot.__init__(self, token: str, client: ResClient) -> None
  • Bot.get_error(self, response: Request, kill: bool = True) -> bool:
  • Bot.get_version(self) -> str:
  • Bot.authenticate(self) -> None:
  • Bot.get_bot(self) -> None:
  • Bot.control_bot(self) -> None:
  • Bot.subscribe_to_all(self) -> None:
  • Bot.on(self, *event: str):
  • Bot.boot(self):
  • Bot.wake_up(self) -> None:
  • Bot.say(self, message: any) -> Request:
  • Bot.pose(self, message: any) -> Request:
  • Bot.ooc(self, message: any) -> Request:
  • Bot.describe(self, message: any) -> Request:
  • Bot.message(self, target: Character, message: any, pose: bool = False, ooc: bool = False) -> Request:
  • Bot.address(self, target: Character, message: any, pose: bool = False, ooc: bool = False) -> Request:
  • Bot.whisper(self, target: Character, message: any, pose: bool = False, ooc: bool = False) -> Request:
  • Bot.mail(self, target: Character, message: any, pose: bool = False, ooc: bool = False) -> None:
  • Bot.summon(self, target: Character) -> Request:
  • Bot.join(self, target: Character) -> Request:
  • Bot.lead(self, target: Character):
  • Bot.follow(self, target: Character):
  • Bot.stop_lead(self, target: Character):
  • Bot.stop_follow(self):
  • Bot.sleep(self) -> Request:
  • Bot.ping(self) -> Request:
  • Bot.wait_for(self, character: Character, timeout: int = 10) -> str:
  • Bot.look_up_characters(self, character_name: str) -> list[Character]:
  • Bot.use_exit(self, exit: Exit):
  • Bot.get_room(self) -> Room:
  • Bot.kill(self) -> None:

ResClient methods:

  • ResClient.__init__(self, host: str, origin: str):
  • ResClient.on_message(self, ws, response):
  • ResClient.process_response(self, response: dict) -> None:
  • ResClient.display_errors(self, errors: dict) -> None:
  • ResClient.cache_dict(self, values: dict) -> None:
  • ResClient.version(self, protocol: str) -> Request:
  • ResClient.subscribe(self, *rid):
  • ResClient.unsubscribe(self, *rid, count = 1):
  • ResClient.get(self, *rid):
  • ResClient.call(self, *rid: str, **kwargs):
  • ResClient.auth(self, *rid, **params):
  • ResClient.on(self, event: str):
  • ResClient.close(self):
  • ResClient.new(self):

Request methods:

  • Request.__init__(self, _connection, *method, notification: bool = False, **params):
  • Request.send(self) -> "Request":
  • Request.resend(self) -> None:
  • Request.receive(self, data: dict) -> None:
  • Request.wait(self, time_out_period: int = None) -> "Request":
  • Request.kill(self) -> None:
  • Request.value(self) -> dict:

Cache methods:

  • Cache.__init__(self, client: "ResClient", data: any = None):
  • Cache.get(self, *rids: str, default: any = None) -> any:
  • Cache.set(self, rid: str, value: any) -> None:
  • Cache.change(self, rid: str, values: dict) -> None:
  • Cache.add(self, rid: str, index: int, value: dict) -> None:
  • Cache.remove(self, rid: str, index: int) -> None:
  • Cache.__getitem__(self, item: any) -> any:
  • Cache.__setitem__(self, key: str, value: any) -> None:
  • Cache.__delitem__(self, key: str) -> None:
  • Cache.__str__(self) -> str:
  • Cache.__repr__(self) -> str:
  • Cache.__contains__(self, item: str) -> bool:

Logger methods

  • Logger.__init__(self, format_color: tuple[int, int, int] = (255, 50, 50), bold: bool = True):
  • Logger.__call__(self, _message: any, _raise: bool = False) -> None:
  • Logger.reset(cls) -> None: (classmethod)
  • Logger.hide(cls) -> None: (classmethod)
  • Logger.show(cls) -> None: (classmethod)
  • Logger.toggle(cls) -> None: (classmethod)
  • Logger.log_if_not_shown(cls, _message: str, color = (255, 255, 255)) -> None: (classmethod)
  • Logger.iteration = 0 (class attribute)
  • Logger.shown = True (class attribute)

Character methods:

  • Character.__init__(self, bot: "Bot", id: str) -> None:

  • Character.__str__(self):

  • Character.__repr__(self):

  • Character.message(self, message: str, pose: bool = False, ooc: bool = False) -> Request:

  • Character.whisper(self, message: str, pose: bool = False, ooc: bool = False) -> Request:

  • Character.address(self, message: str, pose: bool = False, ooc: bool = False) -> Request:

  • Character.summon(self):

  • Character.join(self):

  • Character.get_avatar(self): (accessed by property)

  • Character.get_awake(self): (accessed by property)

  • Character.get_gender(self): (accessed by property)

  • Character.get_idle(self): (accessed by property)

  • Character.get_last_awake(self): (accessed by property)

  • Character.get_name(self): (accessed by property)

  • Character.get_species(self): (accessed by property)

  • Character.get_state(self): (accessed by property)

  • Character.get_status(self): (accessed by property)

  • Character.get_surname(self): (accessed by property)

  • Character.get_tags(self): (accessed by property)

  • Character.get_type(self): (accessed by property)

  • Character.get_full_name(self): (accessed by property)

  • name = property(get_name) (property)

  • surname = property(get_surname) (property)

  • avatar = property(get_avatar) (property)

  • awake = property(get_awake) (property)

  • gender = property(get_gender) (property)

  • idle = property(get_idle) (property)

  • last_awake = property(get_last_awake) (property)

  • species = property(get_species) (property)

  • state = property(get_state) (property)

  • status = property(get_status) (property)

  • tags = property(get_tags) (property)

  • type = property(get_type) (property)

  • full_name = property(get_full_name) (property)

Area methods

  • Area.__init__(self, bot: "Bot", id: str):
  • Area.__str__(self):
  • Area.__repr__(self):
  • Area.get_about(self): (accessed by property)
  • Area.get_children(self): (accessed by property)
  • Area.get_image(self): (accessed by property)
  • Area.get_map_x(self): (accessed by property)
  • Area.get_map_y(self): (accessed by property)
  • Area.get_owner(self): (accessed by property)
  • Area.get_parent(self): (accessed by property)
  • Area.get_pop(self): (accessed by property)
  • Area.get_private(self): (accessed by property)
  • Area.get_prv(self): (accessed by property)
  • Area.get_rules(self): (accessed by property)
  • Area.get_short_description(self): (accessed by property)
  • Area.get_name(self): (accessed by property)
  • Area.about = property(get_about) (property)
  • Area.children = property(get_children) (property)
  • Area.image = property(get_image) (property)
  • Area.map_x = property(get_map_x) (property)
  • Area.map_y = property(get_map_y) (property)
  • Area.name = property(get_name) (property)
  • Area.owner = property(get_owner) (property)
  • Area.parent = property(get_parent) (property)
  • Area.pop = property(get_pop) (property)
  • Area.private = property(get_private) (property)
  • Area.prv = property(get_prv) (property)
  • Area.rules = property(get_rules) (property)
  • Area.short_description = property(get_short_description) (property)

Room methods:

  • Area.__init__(self, bot: "Bot", id: str) -> None:

  • Area.__str__(self):

  • Area.__repr__(self):

  • Area.get_area(self): (accessed by property)

  • Area.get_autosweep(self): (accessed by property)

  • Area.get_autosweep_delay(self): (accessed by property)

  • Area.get_characters(self): (accessed by property)

  • Area.get_description(self) -> str: (accessed by property)

  • Area.get_exits(self) -> list["Exit"]: (accessed by property)

  • Area.get_image(self): (accessed by property)

  • Area.get_is_dark(self): (accessed by property)

  • Area.get_is_home(self): (accessed by property)

  • Area.get_is_quiet(self): (accessed by property)

  • Area.get_is_teleport(self): (accessed by property)

  • Area.get_map_x(self): (accessed by property)

  • Area.get_map_y(self): (accessed by property)

  • Area.get_name(self): (accessed by property)

  • Area.get_owner(self): (accessed by property)

  • Area.get_pop(self): (accessed by property)

  • Area.get_private(self): (accessed by property)

  • Area.area = property(get_area) (property)

  • Area.autosweep = property(get_autosweep) (property)

  • Area.autosweep_delay = property(get_autosweep) (property)

  • Area.characters = property(get_characters) (property)

  • Area.description = property(get_description) (property)

  • Area.exits = property(get_exits) (property)

  • Area.image = property(get_image) (property)

  • Area.is_dark = property(get_is_dark) (property)

  • Area.is_home = property(get_is_home) (property)

  • Area.is_quiet = property(get_is_quiet) (property)

  • Area.is_teleport = property(get_is_teleport) (property)

  • Area.map_x = property(get_map_x) (property)

  • Area.map_y = property(get_map_y) (property)

  • Area.name = property(get_name) (property)

  • Area.owner = property(get_owner) (property)

  • Area.pop = property(get_pop) (property)

  • Area.private = property(get_private) (property)

Exit methods:

  • Exit.__init__(self, bot: "Bot", id: str):

  • Exit.__str__(self):

  • Exit.__repr__(self):

  • Exit.get_keys(self):

  • Exit.get_name(self):

  • Exit.get_arrive_message(self):

  • Exit.get_leave_message(self):

  • Exit.get_created(self):

  • Exit.get_hidden(self):

  • Exit.get_target_room(self):

  • Exit.get_travel_message(self):

  • Exit.s = property(get_keys)

  • Exit.name = property(get_name)

  • Exit.arrive_message = property(get_arrive_message)

  • Exit.leave_message = property(get_leave_message)

  • Exit.created = property(get_created)

  • Exit.hidden = property(get_hidden)

  • Exit.target_room = property(get_target_room)

  • Exit.travel_message = property(get_travel_message)

EventBase methods:

  • EventBase.__init__(self, id: int, type: str, time: float, sig: str):
  • EventBase.__str__(self):

CharacterMessageEvent methods:

  • CharacterMessageEvent.__init__(self, character: Character, message: str, puppeteer: Character | None = None):
  • CharacterMessageEvent.__str__(self):

CharacterPoseableMessageEvent methods:

  • CharacterPoseableMessageEvent__init__(self, character: Character, message: str, pose: bool = False, puppeteer: Character | None = None):
  • CharacterPoseableMessageEvent__str__(self):

TargetedCharacterMessageEvent methods:

  • TargetedCharacterMessageEvent.__init__(self, character: Character, message: str, target: Character, ooc: bool = False, pose: bool = False, puppeteer: Character | None = None, targets: list[Character] | None = None):
  • TargetedCharacterMessageEvent.__str__(self):

TargetRoomMessageEvent methods:

  • TargetRoomMessageEvent.__init__(self, character: Character, message: str, target_room: Room, puppeteer: Character | None = None):
  • TargetRoomMessageEvent.__str__(self):

TargetedCharacterEvents methods:

  • __init__(self, character: Character, target: Character, puppeteer: Character | None = None):
  • __str__(self):
#13

As you can see from the docs above there has already been quite a lot of work on the bot API, however I was wondering if anyone had any specific requests for what should be added?

For example allowing the bot to be made without a bot Token (means that the bot will have more access to different features, slower rate limits but also be accessible for non supporter players)

I would love to know what ideas and features you would like to see bots be able to do, so please let me know so I can add them in.

#14

I’m now also proud to announce that the Mucklet bot API is now on PyPI and can be installed as easily as pip install mucklet :partying_face:

To see how simple it is to make a bot now lets make one here ^w^

client = ResClient("wss://api.test.mucklet.com", "https://test.mucklet.com")

bot = Bot("<Your Token Here>", client)

@bot.on("say", "pose")
def respond(message):
    bot.pose("nods their head mutually")

bot.boot()
1 Like
#15

Note: due to another “life” situation I am without my computer once again.

There is currently a bug with the pip install where the code is referencing non-exsitant code. For now you can just download the Mucklet folder and import it from the same directory.

#16

The Mucklet API Is finally on pypi.org

Run pip install mucklet to install the library, the docs are available at GitHub and PyPi

For any help making bots and/or issues with bugs, you can either message me here on the forums or attempt to fix it on the repo.

1 Like
#17

New feature

Each character has their own backed-up and scaleable database system stored locally, this can be accessed via the Character.local_storage and currently only supports the following
value assignments:

message.event.character.local_storage["foo"] = "bar"
message.event.character.local_storage["foo2"] = {"foo": "bar"}

value retrival:

message.event.character.local_storage["foo"]
message.event.character.local_storage["foo2"]

get method:

message.event.character.local_storage.get("foo")
message.event.character.local_storage.get("foo2")

clear method

message.event.character.local_storage.clear()

The data added, edited, or deleted will be automatically synced between the cache and the bot’s local storage.

The player using the bot has full transparency to the data stored on them via 2 new commands that are built into the API.

  • By sending !get local cache the character will receive a message with all their cached data
  • By sending !revoke local cache the cached data on that character will be removed completely.

Repo changes: