Spring Host Management Protocol¶
This document outlines a method for on-demand allocation of Spring "autohosts".
Why yet another protocol?¶
The traditional bazaar-style hosting used on Spring lobby servers works, but is not ideal given the player population.
- At any given time, there are likely to be multiple autohosted battles on the main lobby server without any players (waste).
- In most autohosted games the host, not the players, has ultimate control of the settings (per its configuration), and any requests to change those settings must go through a text-chat command interface which is unwieldy for the end user.
Example Implementation¶
To obtain a working implementation written in python, run the following commands:
git clone git://tiz.ath.cx/tasbot.git
git clone git://tiz.ath.cx/relayhost.git
cp tasbot/* relayhost/
Terminology¶
This system is designed to spawn and control an dedicated server. The protocol is being kept as small as possible while still allowing maximum flexibility
The system implies 4 entities to work:
- Spawner - The lobby client requesting a dedicated server instance.
- GlobalManagerLister - Stores a list of officially approved Managers.
- Manager - Handles Spawner requests and creates Hoster instances. This is a lobby 'bot, running on a dedicated hosting machine.
- Hoster - Responsible for setting up and launching the dedicated server process on the host machine, according to commands received from the Spawner. This is also a lobby 'bot.
Communication¶
All communication between the Spawner and the Manager, the Spawner and the Hoster, and the Spawner and GlobalManagerLister is performed over the lobby server's private message (PM) mechanism (SAYPRIVATE and SAIDPRIVATE in the TAS Protocol). This document does not define methods of communication between the Manager and the Hoster.
Control Flow¶
Control managers in the list¶
This task is allowed for only server administrators ( the bot will check the status bitfield in order to determine who is one )
The administrator will perform actions by sending a PM the GlobalManagerLister ( currently hardcoded to be "RelayHostManagerList" ) with the following syntax:
!addmanager nick
to add nick to the officially approved managers list
!removemanager nick
to remove nick from the officially approved managers list
duplicate entries will be rejected
Acquire a manger¶
To acquire a list of officially approved Managers, Spawner sends a PM the GlobalManagerLister ( currently hardcoded to be "RelayHostManagerList" ) with the following syntax:
!listmanagers
the GlobalManagerLister will produce an answer with this syntax:
managerlist name1<tab>name2<tab>name3<tab>
where <tab> represents tabulation character
The user will pick a random user from the list, iterating between the elements if necessary to find for a manager which is currently online, the ingame status of a Manager will indicate that it run out of available hoster slots, away status means it's functionality is temporarily disabled
In order to request an hoster to a manager, the following message will have to be sent to the manager via PM:
!spawn
Manager responses¶
In case of success, the manager will spawn an hoster instance ( number of instances can be limited in the config file ), and communicate to the spawner the nick of the resulting bot; afterwards the bot will connect to the server.
nickname
In case of failure, the manager will reply something in the form of
\001 error_message
Controlling an Hoster¶
Once an hoster will have joined the server, it will be free to be controlled from the spawner, the spawner acts as a raw message relay bot; currently the TAS Server protocol is supported, and only a white list of commands can be relayed.
In order to relay a command, the spawner needs to send it throught a private message in lowercase to the hoster and prefix it with a !mark.
The following commands are whitelisted currently to be relayed:
!openbattle !updatebattleinfo !setscripttags !removestartrect !addstartrect !removestartrect !addstartrect !enableallunits !disableunits !setscripttags !forceteamno !forceallyno !forceteamcolor !forcespectatormode !kickfrombattle !handicap !removebot !updatebot
please note that the nat traversal type and host port values will be overwritten in the OPENBATTLE command by the hoster's params
In order to be able to launch an instance of spring-dedicated, the following commands are necessary:
!appendscriptline line
needs to be called in sequence for every script line that the spawner wants the hoster to include in script.txt
!cleanscript
serves the purpose to flush the currently stored script
to make the bot launch the spring dedicated instance, the required command is:
!startgame
bots only commands¶
the following commands enable redirection of ingame messages and in battleroom, but they will be accepted only if the spawner has a bot flag:
!redirectspring 0/1
will disable/enable spring ingame message redirection to the spawner's PM, all the ingame redirected messages will have the prefix #
!redirectbattleroom 0/1
will disable/enable battleroom message redirection to the spawner's PM, all the battleroom redirected messages will have the prefix !
#anything
will send anything to spring control interface