View source for Creating a Bot for CollabVM

So, you want to create a bot for CollabVM? This guide will take you through the process of doing so. I'll go through available libraries, and also briefly explain how to implement the protocol yourself.

= Before you start =

== Do you really need a bot? ==

Before you start creating your bot, ask yourself if you '''really''' need it to exist. We've had our fair share of useless bots, and usually end up banning them pretty quickly once they get annoying. Three general criteria can be:

* Does a bot with the same function already exist
* Is your bot idea practically useless and unentertaining
* Does your bot idea break the [https://computernewb.com/collab-vm/rules/ rules]?

If the answer to any of those questions is yes, you should probably come up with a better idea. Note that mods will ban bots at their discretion if they are perceived to be breaking the rules, or are generally annoying to have.

The following is a list of things that are '''not''' good ideas for bots:

* A bot whose sole purpose is to encode and decode ROT13
* A bot that just sends "facts" about one random guest that you really dislike
* A bot that is just a shitty notsobot clone and filled with useless commands
* A bot that "bans" users from the VM by locking it up using a RAT when they take a turn (Rule 9)

If you make any of these things, we will ban it.

== Getting developer status ==

To create a CollabVM bot, you'll need a bot token, which requires being manually approved for developer status. [https://docs.google.com/forms/d/e/1FAIpQLSdtRf2cYMDyBRueuDW8pCpJP9En0iv95Tr8ht6zS_7Tqxiu6w/viewform?usp=sf_link Fill out the form here], and wait for us to e-mail you. We tend to approve most requests as long as they follow the guidelines above.

Once you've been granted developer status, generate a bot token as follows:

# Navigate to [https://computernewb.com/collab-vm-admin/ the panel] and log in if you aren't. You should be greeted with the bot panel
# Enter the username for your bot at the bottom and click Create
# You will be given a token. Save it somewhere safe as it won't be shown again!

And that's it! You now have a valid CollabVM bot

= Development =

== Bot Libraries ==

There are a few existing libraries which allow you to easily create a bot. Here are some of those. If you have a library not in this list feel free to add it.

=== C# - CollabVMSharp ===

Written by Elijah. Supports most functions including mod tools. Requires .NET Core 6.0 or higher.

[https://git.computernewb.com/Elijah/CollabVMSharp Link]

=== NodeJS - libcvm.ts ===

Written by MDMCK10.

[https://github.com/MDMCK10/libcvm.ts Link]

== Implementing the protocol ==

If there are no libraries available for your preferred language, or you don't like the one available, and you're feeling brave, you can implement the protocol yourself.

The entire CollabVM protocol is documented at [[CollabVM 1.2 Protocol Reference]].

== Writing your bot ==

With a library selected, you can now get started writing your bot. Refer to the README of the library you chose and the example section below for help with this.

Some tips in no particular order:

* The main VMs REQUIRE the <code>Origin</code> HTTP header to be set to <code>https://computernewb.com</code>. While some libraries handle this on their own, some may not.
* Make sure you're logging into the VM using your token before doing anything else. Some libraries may have a method for this while some may have it as part of the initial connection parameters.
* If you plan to have your bot on multiple VMs, consider wrapping your entire bot in a class. (A good thing to remember when programming in general is that, if you're copying the same lines of code over and over, you're doing it wrong).

= Examples =
== CollabVMSharp ==

The following is a simple CollabVMSharp example to show how to do basic things:

<syntaxhighlight lang="c#" line>
using CollabVMSharp;
CollabVMClient cvm = new CollabVMClient(
    "wss://computernewb.com/collab-vm/vm0", // WebSocket URI
    "Example Bot", // Requested username. On the main VMs and others that use account authentication, this will be ignored.
    "vm0b0t" // VM node ID. You can omit this parameter and use cvm.ConnectToVM() to connect to a VM later.
);
// Connect to the server
await cvm.Connect();
// Login with our token
await cvm.LoginAccount("your_token_goes_here");
// Send a message to the VM
await cvm.SendChat("Hello, world!");
// Log all chat messages
cvm.Chat += (_, msg) =>
{
  Console.WriteLine($"{msg.Username}: {msg.Message}");
};
// Register a command
// msg can also be a string[], in which case it will be split into arguments by whitespace with double quote support
cvm.RegisterCommand("!echo", (string username, string msg) =>
{
    cvm.SendChat($"@{username}: {msg}");
});
// Wait for a turn
await cvm.GetTurn();
// Type a message
await cvm.TypeString("Hello, World");
// Drop the turn
await cvm.Turn(false);
// Block until the program is closed
await Task.Delay(-1);
</syntaxhighlight>

If you have any questions about usage, feel free to contact me on discord (@elijahr.dev)! CollabVMSharp is fully featured and supports anything the webapp can do.