Creating a Bot for CollabVM: Difference between revisions

no edit summary
No edit summary
No edit summary
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? ==
 
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%207Tqxiu6w/viewform?usp=sf%20link 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 ===
 
==== 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:
 
<pre>
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);
</pre>
 
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.