Editing Relay

Linking together several bots


'''1. The Basics'''

If you want to link several bots together, there are multiple ways to achieve this, each with its benefits and drawbacks. Read the guide thouroughly and decide for yourself, which will suit your needs.

Basically, for your bots to be linked, they need a fast way to communicate with all participating bots. If you only want to link 2 bots together, you can link them via “tells”. It doesn't scale though, linking more than 2 bots together via tells is not possible. If you want to link more than two bots, or might want to do so in the future, there are 3 possibilities: Either you link them together using your bot-database (only works if all bots use the same database), using irc or you use a private channel in the game. If you use IRC, keep in mind that you should secure the channel you use with a password and that, depending on the connection to the irc-server, response-time gets up a bit. Using a private channel in the game is a good alternative, but you will need a dedicated bot (a relay bot) to keep that private channel open and invite all the org/raid bots.


'''2. The different setups'''

Throughout the different setups, we will speak of org-bots, and raid-bots. To make it easier, all bot-names are enclosed in <>, so please make sure you remove them when pasting/replacing with your own bots' names.


'''2.1 Using tells'''

PROS: 	very quick & easy setup, no relay-bot nor other complicated stuff needed

CONS: 	Only works with 2 bots, possibly risky, tells might be dropped by the server if coming in too fast ...

Using tells as relay is discouraged nowadays (and you even run the risk of having your bots banned by funcom without warning), but we will describe it shortly nonetheless. Use at your own risk!

Assuming you have two bots “bot1” and “bot2”, you start by allowing each bot to relay to each other. You could do a “!member add bot2” on bot1 and vice versa, but the member-list of org-bots might get wiped during roster-updates. So rather refer to section 2.4.2 as to how to create a new security group named “relaybots” with SUPERADMIN level on both bots and then make them member on the other bot's group.

If you've done this, you let bot1 relay to bot2:

    /tell bot1 !set Relay StrictNameCheck On
    /tell bot1 !set Relay Type tell
    /tell bot1 !set Relay Relay <bot2>
    /tell bot1 !set Relay Status On

And vice versa:

    /tell bot2 !set Relay StrictNameCheck On
    /tell bot2 !set Relay Type tell
    /tell bot2 !set Relay Relay <bot1>
    /tell bot2 !set Relay Status On

You might also want to change the name of your org's and private-group's messages prefix

    /tell bot1 !set Relay Gcname ORG1
    /tell bot1 !set Relay Pgname org1
    /tell bot2 !set Relay Gcname ORG2
    /tell bot2 !set Relay Pgname org2

And that should do it. If you want to link more than 2 bots, you should think about using a relay-bot.


'''2.2 Using IRC'''

PROS: 	scales well, no relay-bot needed, medium setup, allows linking between different game-servers & even cross-games

CONS: 	increases latency, order of messages not guaranteed, item-refs could be broken, possibly insecure

Before you start, please acknowledge that relaying via IRC is considered deprecated, yet it will still work.

Being a totally different approach, an IRC-link works by letting all participating bots join the same IRC-channel on the same IRC-server. Keep in mind that if you're not using a password-secured channel, everyone who wants to can read everything you are saying on any bot. To setup this link, you can use something like this:

    /tell org1bot !set Irc Server <your irc server>
    /tell org1bot !set Irc Channel #mylinkchannel
    /tell org1bot !set Irc ItemRef AUNO
    /tell org1bot !irc connnect

If you have an IRC-server which supports passwords on channels, you have to specify this as well:

    /tell org1bot !set Irc ChannelKey mysecretpassword

Of yourse you have to do the exact same settings on all bots you want to link via IRC. The main reason you might want to consider IRC ist that you can link bots from RK1, RK2 and RK3 together with bots even from AoC and WoW, it doesn't really matter. But keep in mind that IRC does not guarantee that things you send to it are relayed in the same order. You might actually read the answer to a question before someone asks it.


'''2.3 Using WebSocket'''

PROS: 	scales up to thousand bots, nice speed, possible sharing of online-lists if all bots are using the same protocol

CONS: 	Needs access to a highway websocket that all bots must be able to join & communicate with, complex setup

This is a compatible option available only into most recent bots (Bebot, Tyrbot, Nadybot). Most common choice is to use the websocket publicly provided for Nadybot.
From there, your Nadybot(s) relay should be using websocket+highway+tyrbot layers (aes-gcm-encryption being optionnal) which will maximize the compatiliby with Tyrbot(s). You should check their respective documentation (as detailed lower) if you ever met issues with those 2 bots.
Also beware that, if you use such public websocket, the AES-GCM encryption goes from optionnal to mandatory for privacy protection !

So from version 0.7.21 under PHP 7.0 or more, Bebot(s) will also be able to jump into the room and all bots should speak together, no matter which.

For Bebot hosts, the WebSocket Relay is configured like this:

    /tell org1bot !set websocket Room example2-test0-room9-1234abc-xyz789
    /tell org1bot !set websocket Password C0mpl3x-P4ssW0rD!
    
Assuming that our Org1 is called “The proud and well-known fr00bs of Rubi Ka”, relayed messages from your guildchat would be displayed on Org2 as [Org2] Org2Bot: [The proud and well-known fr00bs of Rubi Ka] [Channel] Pigtail: Test. You might want to shorten that “The proud and well-known fr00bs of Rubi Ka” a bit:

    /tell org1bot !set websocket Label OrgShorten

If you don't want to relay everything & prefer to control sending via a 1st character syntax (e.g. @) :
    /tell org1bot !set websocket nearSyntax @
Therefore you'll send to websocket only while using this 1st letter (in org or private channel) :
    @ Hello to other orgs

Once all is set you can initate the persistent connection by :
    /tell org1bot !ws connect
(then disconnect if you ever need to remove that persistent connection)

Final element to configure, you need to add all other Orgs signing Tags to your bot so it can display those others online lists. Small issue with WebSocket is you couldn't easily discover those Tags before receiving other Orgs messages, eg :
    [Org2Tag] [Priv] Player: hello all!
To include that org into you local bot's online, you'd have to add its Tag exactly as you've seen it as follow (keeping upper example) :
    /tell org1bot !set online OtherBots Org2Tag
And as soon you discover more Org Tags you'd add them separated by commas ',' like this :
    /tell org1bot !set online OtherBots Org2Tag,Org3Tag,Org4Tag
But to help you discover them faster, once your bot is connected into WebSocket & receiving messages, you could rather do :
    /tell org1bot !ws others
This command should provide you with the wanted Tags list formatted to be copy-pasted to upper online set. Just beware that if some new Org joined in, or if any Org changed its Tag, you'd have to update & reset that online OtherBots value by redoing this process.

Few other Websocket options are also into :
    /tell org1bot !settings websocket


'''2.4 Using a private channel'''

PROS: 	scales up to hundred bots, good speed, possible sharing of online-lists if all bots are using the same DB or !gcr/c

CONS: 	Needs a dedicated relay-bot that all bots will easily join, but means few more configuration

The fastest and most flexible solution is relaying via a private group. All bots you want to connect have to join the same private group and exchange messages. For this to work, we need a new type of bot, a relay-bot, which has the job of creating the private group and inviting all other bots into this group whenever necessary. The org/raid-bots on the other hand are configured much like a tell-relay.

CAVEAT: Before setting up everything, create all the bots you will need and make sure that some time passes so every bot has WHOIS-information on every bot involved. This will wipe out any possible problem related to people and bots not seeing each other.


'''2.4.1 Setting up the relay-bot'''

Your most important bot is the relay-bot. Its only task is to be online, create the private channel which is used for the communication between your bots and invite all bots you want to link together to this chat. Nothing more. If your relay-bot is offline, your link will be gone, though your raid/guild-bots will continue to work. Once the relay-bot comes on again and all guild/org-bots are invited, the link will work again.

The relay-bot MUST NOT BE MEMBER OF ANY ORGANISATION. Keep that in mind. It should be a totally stripped-down bot, only there to open the private group and invite the other bots, so make sure to disable as much modules as possible, since you will most likely never use them anyway and they increase the likeliness of a break-in. Stricly speaking, you only need the follwing modules once the bot is set up and all is running well:

    AccessControlUI.php
    BanManagerUI.php
    ColorConfigUI.php
    CommandAliasUI.php
    FlexibleSecurityUI.php
    Logon.php
    ModulesControlUI.php
    Notify.php
    PreferencesUI.php
    Relay.php
    Roster.php
    SettingsUI.php
    ShortCutsUI.php
    Shutdown.php
    ao/AutoInv.php
    ao/PrivGroup.php

Those in italic can also be disabled, but will make like more comfortable.
The basic idea of the relay-bot is that the only members are the bots you want to link together. You will then need to set it up to automatically invite them all, so once the link is down it will setup again automatically. Throughout the setup, I will assume that your relay-bot's name is rbot, as will be its private group.

The first thing to do is to enable AutoInvites for all members of the bot:

    /tell rbot !set Relay Autoinvite On
    /tell rbot !set Autoinv ShowInfo Off
    /tell rbot !preferences default Autoinv receive_auto_invite On
    /tell rbot !set Autoinv Activated On

Then you have to add all org/raid-bots as members to this bot:

    /tell rbot !member add <org1bot>
    /tell rbot !member add <org2bot>
    /tell rbot !member add <org3bot>
    /tell rbot !member add <raidbot1>
    /tell rbot !member add <raidbot2>

To speed up reconnects, you should place all bots on notify:

    /tell rbot !notify on <org1bot>
    /tell rbot !notify on <org2bot>
    /tell rbot !notify on <org3bot>
    /tell rbot !notify on <raidbot1>
    /tell rbot !notify on <raidbot2>

And that's about it for the relay-bot setup, from now on, when any member bot comes online, it will be invited by relay-bot.
Just note that the relay-bot will start inviting few minutes after being brought online, so not immediately to avoid spamming.
If you need to adjust its Startup_Delay :
    /tell rbot !settings Logon_notifies


'''2.4.2 Setting up the org/raid-bots'''

On your org-bots and raid-bots, you will need to make them use the relaybot's private group as their private group for relaying. 

Those hosts can be other Bebots, but also possibly any compatible other bots like Tyr or Buda/Nady, as long those also support at least agcr protocol (very minimal with just chat link) or ideally gcr protocol (better with chat + online list shared).
This guide involves Relay module with best protocol of both, namely gcr, but you may find an agcr option within Custom/Modules, in case you ever need to use a more limited protocol.

For Bebot hosts, the gcr Relay is configured like this:

    /tell org1bot !set Relay StrictNameCheck On
    /tell org1bot !set Relay Type Pgroup
    /tell org1bot !set Relay Relay <rbot>
    /tell org1bot !set Relay Status On

“rbot” being the name of your relay-bot. Assuming that our Org1 is called “The proud and well-known fr00bs of Rubi Ka”, relayed messages from your guildchat would be displayed on Org2 as [Org2] Org2Bot: [The proud and well-known fr00bs of Rubi Ka] Pigtail: Test. You might want to shorten that “The proud and well-known fr00bs of Rubi Ka” a bit:

    /tell org1bot !set Relay Gcname PWF
    /tell org1bot !set Relay Pgname pwf

The first is the name to displayed for messages relayed from your guildchat, the second one the name displayed for the private group (a.k.a. guest-chat).

If you don't want to relay everything & prefer to control sending via a 1st character syntax (e.g. @) :
    /tell org1bot !set Relay nearSyntax @
Therefore you'll send to relay-bot only while using this 1st letter (in org or private channel) :
    @ Hello to other orgs
Note : this syntax will be bypassed by bot's org <-> local private relay.

You also have to think about how your own bot will speak with other bots in the relay channel.
The bot will first only see other's commands sent with same command_prefix it uses itself (check its Conf/ file) being ! by default.
If you have some bots in the relay channel that use various prefixes and you cannot unify them, you can set your bot flexibly :
    /tell org1bot !set Relay OtherPrefixs #;.
(in this example, it means some external bots into relay channel are using #gcr/c and .gcr/c and your bot could see them now)

If all bots use the same syntax, you could also can change your own bot command_prefix in its Conf/ file (check Configuration page of this wiki) but it will affect all other commands readability from your bot point of view.
So an alternative way if you only want to change command far syntax for sending to relay only :
    /tell org1bot !set Relay farSyntax .
And if other bots also use this far syntax :
    /tell org1bot !set Relay OtherPrefixs .

Now that it's done, every org/raid-bot host configured like this should be in the private chat of the relaybot. If they aren't there already, either wait a bit, or join the relay-bot's private group and !invite them one by one. The only thing missing is to configure those bots to allow all linked bots to send them relay-messages via !gcr (or !agcr). Per default for security, only member with the access level MEMBER is allowed to do this.
This is the most sensible part of your setup as with this configuration every org or raidgroup can decide for themselves FROM which they want to receive messages (but sadly they can't limit TO whom they want to send). 

Usually every org/raid-bot wants to allow every other bot to send messages. Of course we could just add every bot with “!member add”, but that could become quite messy. To keep things a bit more organized, we advise to create a new security group with the access level MEMBER. For simplicity, we call it “relaybots” and give it a good description.

    /tell org1bot !addgroup relaybots All bots from which we want to receive messages

This will create the new security group “relaybots” with access level ANONYMOUS. We need to promote our new group to access level MEMBER. Sadly, the command for this depends on the internal number of the newly created security group, so here's what you need to do:

    /tell org1bot !security levels

You will see that our security group has access level ANONYMOUS. If you're going for a private channel type of relay, click on the [MEMBER] next to “relaybots” to promote it to MEMBER access level. But if you're going for a direct tell type of relay, click on the [SUPERADMIN] next to “relaybots” to promote it to SUPERADMIN access level.

Now that it's done, we just need to add all bots we want to receive messages from to our new security group. With our current example of 3 orgbots and 2 raidbots, we'd do something like this:

    /tell org1bot !adduser <org2bot> relaybots
    /tell org1bot !adduser <org3bot> relaybots
    /tell org1bot !adduser <raidbot1> relaybots
    /tell org1bot !adduser <raidbot2> relaybots

Of course you need to do this on all 5 bots (but NOT on the relay-bot which we already configured earlier!), so it will take some time. After every bot has access to every bot, your link should work as expected and reconfigure itself after disconnects.
Congratulations, you are done!


'''2.4.3 Scalability'''

If you understood what we've just configured, you might have noticed that you can use a single relay-bot to manage different guild-links. If, for example, you now decide that you want to seperate your org-link and your raid-link you can achive this by making all org-bots member of the relaybots security-group on all org-bots (but not on any raid-bot) and all raid-bots members of the security-group relaybots on all raid-bots (but not on any org-bot). This way, you can use a single relay for several totally different relay-groups. The only proble being that the bot-admin can only decide from which bot he/she wants to receive messages, but not to which bots messages should be relayed. So you have to trust each other if you really plan such a weird setup.

Anyway, the big advantage from this whole setup we just did is that it scales nicely. No matter how many bots you add, the delay doesn't increase. The traffic depends solely on the amount of text sent, which should be totally neglectable.


'''2.4.4 Sharing the online-list across several bots'''

If you are building a bot-network, you will most likely be interested in knowing who is online. And this includes all linked orgs, not just your own. Luckily, this is possible. There are two cases to consider:


'''2.4.4.1 All bots use the same DB'''

If you want to share the online-list of all your bots, you need all org/raid-bots to use the same database. Then you only need to tell each bot about all the other bots:

    /tell org1bot !set online OtherBots <org2bot>,<org3bot>,<raidbot1>,<raidbot2>
    /tell org2bot !set online OtherBots <org1bot>,<org3bot>,<raidbot1>,<raidbot2>
    /tell org3bot !set online OtherBots <org1bot>,<org2bot>,<raidbot1>,<raidbot2>
    /tell raidbot1 !set online OtherBots <org1bot>,<org2bot>,<org3bot>,<raidbot2>
    /tell raidbot2 !set online OtherBots <org1bot>,<org2bot>,<org3bot>,<raidbot1>

Now every bot lists all the members of all bots involved. Problem solved.


'''2.4.4.2 At least one bot not using the same DB'''

Starting from 0.6.3, the online-list of linked bots are automatically syncronized within !gcr protocol (not within !agcr), but all bots have to run at least 0.6.3 or higher for this to work. When you meet these requirements, proceed to set OtherBots as described in 2.4.4.1.

For other bots than Bebot, like Tyr or Buda/Nad, they have their own particular settings, so you have to read their documentation :

Bud: should only support agcr unless custom module

Nad: supports both gcrc & agcr as explained here https://github.com/Nadybot/Nadybot/wiki/Relaying-(from-5.2-onward)

Tyr: may support agcr natively, requires extra module for !gcr https://github.com/Budabot/Tyrbot/tree/master/modules/extra/relay_gcr

Or do !help in tell with the host bot to check the way to set it up well for !gcr protocol (or !agcr without online lists).

NB : beware that most recent bots (Bebot, Nadybot, Tyrbot) can be set to share online list via websocket as detailed upper.


'''2.5 Using a shared database'''

PROS: 	ok speed (2s delay max), sharing of online-lists, no relay-bot needed

CONS: 	All bots need to be using the same database

I haven't tried this myself yet, but here is how it should work:

Keep in mind that this setup only works if all your bots are using the same database. It's can't work elsewise.
First, make sure to grant each of the bots involved in your network access to each other (either by using “!member add botX” or creating a special security group for this as described in 2.4.2. Now do the following (assuming there are three bots, named bot1, bot2 and bot3):

    /tell bot1 !set Relay StrictNameCheck On
    /tell bot1 !set Relay Type db
    /tell bot1 !set Online Otherbots <bot2>,<bot3>
    /tell bot2 !set Relay StrictNameCheck On
    /tell bot2 !set Relay Type db
    /tell bot2 !set Online Otherbots <bot1>,<bot3>
    /tell bot3 !set Relay StrictNameCheck On
    /tell bot3 !set Relay Type db
    /tell bot3 !set Online Otherbots <bot1>,<bot2>
    /tell bot1 !set Relay Status On
    /tell bot2 !set Relay Status On
    /tell bot3 !set Relay Status On

Don't forget to set Pgname and Gcname to something reasonable

    /tell bot1 !set Relay Pgname org1
    /tell bot1 !set Relay Gcname ORG1
...

And that's about it. The relaying of messages is not instant though since every bot will check for new messages to relay only once every 2 seconds. But in return you will get a shared online-list and no hassle setting it up. Enjoy!


'''3. Conclusion'''

There is a solution to nearly every problem. All different approaches have pros and cons and in the end it's up to you to decide which path you chose. Linking bots is not an easy task and you should try to understand what you are doing before you actually let people use your setup. Play around a bit, experiment and only when you are happy and sure you understand what happens, let other people join your bots. Don't let people push you to do something you don't understand or even want. After all, these bots are your bots and you are to take care of them. Be proud of your work and enjoy it!

1) Meaning that if you send several tells in rapid succession, you will see tells being slowed down by the chatserver. After x tells in x seconds, the chatserver starts simply dropping tells. In any org with say more than 5 events every 10 seconds this means you will have loss of information occuring.

2) Strictly speaking, it may be the member of an org, but since the relaying is done using the private group of your org-bot, you have to make sure no one besides you can access the bot's private group. So if you really know what you are doing and absolutely want to, you can actually use your org-bot as a relay, yes. I just totally not recommend it.


'''4. Extension'''

PROS : can connect to more than one relay at the time

CONS : uses !agcr protocol without online list sharing (so if you need it, check upper for grc/c, websocket or DB method)

You may have to connect your bot to more than one relay channel, several networks at the same time.
Since recent patches of the 0.7.x serie, you have the multiple "_Alliance_Relay_07" solution within Custom/Modules.
Simply remove its initial underscore to name it "Alliance_Relay_07" and restart the bot so it loads it.

Then you'll have upto five "Hrelay" (HRelay1, HRelay2, HRelay3, HRelay4 and HRelay5) available in the !settings menu.
You can edit any by its number, for example with number 1 you do :
    !settings HRelay1
It's then up to you to setup on the same model than described upper.
Usually you'd use Channel mode, as Tells will be risky with many bots, & DB mode quite unusable for bots hosted separately.

Just make sure you don't use same triggered syntax for more than one relay.
Otherwise you may send unwanted messages on wrong network, or not sent wanted message into wanted network.
For example you may use # for relay 1, § for relay 2, + for relay 3, @ for relay 4, * for relay 5 (choices are up to you).
That way you're guaranteed that the message lands where you aim for.