Difference between revisions of "Autopilot"
From #openttdcoop wiki
(→Windows: Fixed link to post)
(Link to Avignon's wiki)
|Line 6:||Line 6:|
Avignon is a new ground-up approach of the known autopilot or ap+
Avignonis a new ground-up approach of the known autopilot or ap+
it is written in TCL8.5 using some (slightly modified) modules from tcllib
it is written in TCL8.5 using some (slightly modified) modules from tcllib
Revision as of 20:10, 6 April 2010
autopilot is a Tcl script which uses Tcl's Expect package to interface with OpenTTD's dedicated server console to provide network games with additional features not normally available with the game alone. This is the operator's manual for version 2.0 of autopilot.
- 1 Branches
- 2 License
- 3 Overview
- 4 Configuration
- 5 Use
- 6 Windows
- 7 Support
ap+ is a branch of Autopilot - trying to not lose too many features and to provide many more. development is at version ap+ 3.0 beta (started counting after autopilot's 2.x)
Avignon is a new ground-up approach of the known autopilot or ap+ it is written in TCL8.5 using some (slightly modified) modules from tcllib
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
Additionally, this operator's manual is Copyright © 2006 Brian Ronald.
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is available here.
autopilot is a modular script. It comes as a set of Tcl source files. Some of these require that additional Tcl packages be installed in order to run.
The base module consists of autopilot.tcl, autopilot-lib.tcl and a language file. Alone, it provides the following features:
- Periodic automatic server password changes
- Implementation of max_clients, max_companies and max_spectators settings in openttd.cfg (not normally available in OpenTTD revision 6280 and earlier)
- Implementation of net_frame_freq setting in openttd.cfg
- Automatic pausing of the server when the number of connected clients is below a user-defined threshold
- Greeting of players, by name, as they join the server (up to three chat lines)
- Changes behaviour of exit console command to save the game to game.sav before closing the server
- Changes behaviour of save console command to use a default of game.sav if no file is specified
- adds version and license commands to console
- adds an admin pager facility to the game
autopilot takes control of the server's dedicated console. Optionally, it can allow pass-through commands so that the server's operator can use the console as normal, although this comes at the price of slightly reduced responsiveness.
The IRC module consists of autopilot-irc.tcl, and requires that tcllib is installed. When enabled, it provides the following additional features:
- Bridging of in-game chat with IRC channel, allowing IRC users to converse with players, and vice-versa.
- Provides channel and privmsg commands to query the players and companies on the server
- Provides channel and privmsg commands to show server version and newgrf settings
- Provides privmsg rcon commands, allowing IRC users with the rcon password to control the server
- Provides channel and privmsg commands allowing IRC users to learn the current password
- Supports CTCP VERSION and can identify to IRC services
- Storage of the current server password in the database, to allow database aware applications to reveal it
- Logging of in-game chat, client joins, quits and name changes to a database, including logical separation of games and servers to allow for many servers to log to the same database
The module supports database table prefixing, to allow easy co-existence with other database applications.
autopilot's messages can be easily translated to other languages by including additional language files. Version 2.0 comes with one language file, lang_english.tcl, which can be copied and modified to facilitate translation. The server requires that openttd be in English (at present).
autopilot is configured through openttd.cfg. If a different configuration file is to be used, it must be specified to autopilot through the OTTD_CONFIG environment variable. Included with autopilot is the file openttd_additional.cfg, which contains the additional sections required to operate the script. autopilot will fail to run without this configuration.
If you wish autopilot to have its IRC nickname identified with services on your chosen network, it is necessary for the nickname to be registered in advance.
In order to use the MySQL module, the script must have access to a properly configured MySQL server in which the tables can be found. Such configuration is beyond the scope of this document, except to say that the file autopilot.sql contains the necessary CREATE TABLE commands for a MySQL 5.0 server.
Here follows a line by line description of all the new openttd.cfg options used by autopilot. They are all specified in the form of option = value. Boolean values can be yes, true or on to set a feature, and anything else to un-set it.
In the [network] section, the following commands are added:
- Set to an integer (maximum of 8 is the default). Specify the maximum number of companies allowed in the game.
- Set to an integer (10 is the default, maximum is 11). Specify the maximum number of players allowed to connect to the game.
- Set to an integer (maximum of 10 is the default). Specify the maximum number of spectators allowed to connect to the game.
- Set to an integer. Usual default is 1, autopilot changes the default to 2. See openttd documentation for effect.
In the [autopilot] section, the following commands are added:
- String value. Specifies the filename of the openttd executable (./openttd for Linux, openttd.exe for Windows, etc)
- String value. Selects the language file lang_language.tcl where language is the content of this setting.
- Integer value. Used when the console is enabled (see below). Amount of time, in seconds, between autopilot switching its attention between the console (for command entry) and the server. Lower numbers make the server more responsive to commands and events, higher numbers decrease CPU use slightly.
- String value. Specifies the email address of the admin. This can be used in variable substitution and is the email address used by the admin pager.
- String value. Specifies a URL which can be used in variable subsitution.
- Boolean value. Specifies whether to load the IRC module.
- Boolean value. Specifies whether to load the MySQL module.
- Boolean value. Specifies whether to enable pass-through commands to the user of the console. If turned off, the server ismuch more responsive, but control can only be taken through the server's rcon facility.
- Boolean value. Enables the periodic password change feature.
- String value. Filename of a text file containing a list of possible passwords to choose from. The format should be one password per line.
- Boolean value. Number of milliseconds between password changes. 300000 is 5 minutes.
- Integer value. autopilot will pause the game if this many clients, or less, are connected to the server.
- String value, used only by the IRC module. The domain name or IP address of the IRC server.
- Integer value, used only by the IRC module. The port on which to connect to the IRC server.
- String value, used only by the IRC module. The IRC username to connect with.
- String value, used only by the IRC module. The IRC channel to join after connecting. Must use one of # for global channels, and @ for local channels.
- Boolean value, used only by the IRC module. Specifies whether autopilot will show the game chat in the IRC channel, and vice versa.
- Boolean value, used only by the IRC module. If set, IRC users must use !say to communicate with game players.
- Boolean value, used only by the IRC module. Enables use of the rcon command from IRC.
- String value, used only by the IRC module. A string to be quoted to the server in order to authenticate to services.
- String value. A string to be sent to game chat when a player joins the server. Uses variable substitution.
- as motd1
- as motd1
- Integer value. Number of milliseconds between client recounts (300000 is 5 minutes). Used to maintain an accurate count for the pause_level setting in the event that clients join or quit without messages (rare, but does happen).
- String value, used only by the MySQL module. The domain name or IP address of the MySQL server.
- String value, used only by the MySQL module. The name of the databse which contains the database tables.
- String value, used only by the MySQL module. The user with which to log in to the database.
- String value, used only by the MySQL module. The password associated with the user.
- String value, used only by the MySQL module. The table prefix used to distinguish autopilot's tables in the database.
- Integer value, used only by the MySQL module. The integer value of this server, which must be a key in the server table in the database.
- String value. SMTP relay server used for the admin pager command. leave empty to disable.
The [responses] section is used for keyword = response style command definitions. These responses are used solely by the IRC module to provide (and override) commands in the channel and by private message. Variable substitutions are supported in the responses.
Variable substitution is a means of making responses more dynamic. They are supported in the motd1, motd2 and motd3 settings, as well as in the [responses] section. The variables are specified as all-capital keywords. Wherever one o fthese keywords is found in these settings, the keyword is replaced with a substituted string. The substitutions are as follows.
- Only used in motd1, motd2 and motd3. This is replaced with the name of the client that has joined the server.
- Replaced with an integer, being the number of companies in the game the last time that autopilot counted them.
- Replaced with the email address specified in the emailsetting in the [autopilot] section.
- Replaced with the license string, as defined in the language file.
- Replaced with the current server password.
- Replaced with an integer, being the number of connected clients.
- Replaced with the URL specified in the urlsetting in the [autopilot] section.
- Replaced with the current autopilot version string
- Replaced with the current OpenTTD revision or release number.
Once configured, starting autopilot is simply a matter of running the file autopilot.tcl from a terminal. Optionally, the command line parameter load will load the game in save/game.sav. An optional second parameter is the name of a specific saved game to load:
This starts a new game according to what's defined in openttd.cfg
This loads and continues save/game.sav
./autopilot.tcl load save/special.sav
This loads and continues save/special.sav
From within the game chat, three commands are acted upon by autopilot.
This command will attempt to send an email to the admin email address.
This command will show the autopilot version to players.
show autopilot version
This command will show the autopilot version to players (and has been supported since the very first version).
Use of the MySQL server requires a little more preparation. The following steps must be taken:
- The server must be named in the server table, and its key specified in openttd.cfg
- The game must have a name in the game table, and the server's key must be inserted in the server field as a foreign key
- A record must be inserted into the setup table specifying the setting of current_game, the server's key in th server field and the key of the game in the game table as a foreign key in the value field.
There is currently no tool to do this included with autopilot. Once this is done, autopilot will automatically log the game's chat to the chatlog table (if enabled) and will write the server password to the setup table whenever it has changed. The password will be the value field in a record where setting is password and server is the server's key, as specified in openttd.cfg.
The autopilot will use it's own playername as its IRC nickname. It will attempt to join its channel. If kicked, it will not rejoin unless invited. If it is invited (to anywhere, by anybody) it will take that as its cue to attempt to join its own channel.
All commands are sent by private message or in the channel. If sent in the channel, they are preceded with an exclamation mark (!).
If IRC bridging is enabled, players can converse with the IRC channel simply by using the in-game chat. If irc_explicit_say is disabled, IRC users can converse with players simply by talking in the IRC channel. If it is enabled, they must use the !say command in the channel to be seen in the game:
!say Hi there.
This command must also be used, even if irc_explicit_say is disabled, if an IRC user wishes what they said to be logged with the in-game chat by the MySQL module.
If irc_enable_rcon is on, then any IRC user with the rcon password can execute rcon commands on the OpenTTD server by sending a private message to the autopilot:
/msg autopilot rcon password net_frame_freq 1
This command would set the OpenTTD variable net_frame_freq to 1 if autopilot's rcon password was password. rcon cannot be used in the channel.
Other commands which can be used by default, either by private message or in channel:
- shows the autopilot version
- lists the newgrf lines you’d need in your openttd.cfg
- lists the companies that are in the game
- lists the players and spectators that are in the game
- gives the #openttdcoop web site address
- gives the URL of the wiki
- gives the URL of this blog
- gives the email address of an admin (er, mine, as it happens…)
- shows the revision number of the openttd server
- shows you the number of players inthe game
- shows you the number of companies in the game
Most of these are defined in the [responses] section of openttd.cfg and can be altered or removed by autopilot's operator. New commands can be added the same way.
The newgrf command, if disabled, will still work by private message. This is by design, and allows players to request the newgrf list from the server whilst still allowing the option of not dumping huge amounts of text into the channel.
Whilst autopilot works perfectly with ActiveTcl, it is unfortunate that its Expect package is unable to take control over a Windows based openttd dedicated server without modification of the latter. A modification tool is available in this post on tt-forums.net which will convert the Windows openttd.exe to a console application capable of being controlled.
Because autopilot is free software, it is provided without any warranty. That said, the author (Brian Ronald, aka Brianetta) is normally happy to provide help with autopilot to those who ask nicely.