Autopilot

From #openttdcoop wiki

Revision as of 10:56, 18 May 2009 by Ammler (Talk | contribs)

Jump to: navigation, search

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.

Branches

AP+

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

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

Homepage: http://www.codecubes.org/wiki/Avignon

License

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.

Overview

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.

Base module

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.

IRC module

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

MySQL module

The MySQL module consists of autopilot-mysql.tcl, and requires that mysqltcl is installed. When enabled, it provides the following additional features:

  • 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.

Language

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).

Configuration

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.

IRC

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.

MySQL

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.

openttd.cfg

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.

network section

In the [network] section, the following commands are added:

max_companies
Set to an integer (maximum of 8 is the default). Specify the maximum number of companies allowed in the game.
max_players
Set to an integer (10 is the default, maximum is 11). Specify the maximum number of players allowed to connect to the game.
max_spectators
Set to an integer (maximum of 10 is the default). Specify the maximum number of spectators allowed to connect to the game.
net_frame_freq
Set to an integer. Usual default is 1, autopilot changes the default to 2. See openttd documentation for effect.

autopilot section

In the [autopilot] section, the following commands are added:

command
String value. Specifies the filename of the openttd executable (./openttd for Linux, openttd.exe for Windows, etc)
language
String value. Selects the language file lang_language.tcl where language is the content of this setting.
responsiveness
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.
email
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.
url
String value. Specifies a URL which can be used in variable subsitution.
use_irc
Boolean value. Specifies whether to load the IRC module.
use_mysql
Boolean value. Specifies whether to load the MySQL module.
use_console
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.
randomize_password
Boolean value. Enables the periodic password change feature.
password_list
String value. Filename of a text file containing a list of possible passwords to choose from. The format should be one password per line.
password_frequency
Boolean value. Number of milliseconds between password changes. 300000 is 5 minutes.
pause_level
Integer value. autopilot will pause the game if this many clients, or less, are connected to the server.
irc_server
String value, used only by the IRC module. The domain name or IP address of the IRC server.
irc_port
Integer value, used only by the IRC module. The port on which to connect to the IRC server.
irc_user
String value, used only by the IRC module. The IRC username to connect with.
irc_channel
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.
irc_bridge
Boolean value, used only by the IRC module. Specifies whether autopilot will show the game chat in the IRC channel, and vice versa.
irc_explicit_say
Boolean value, used only by the IRC module. If set, IRC users must use !say to communicate with game players.
irc_rcon
Boolean value, used only by the IRC module. Enables use of the rcon command from IRC.
irc_nickserv
String value, used only by the IRC module. A string to be quoted to the server in order to authenticate to services.
motd1
String value. A string to be sent to game chat when a player joins the server. Uses variable substitution.
motd2
as motd1
motd3
as motd1
recount_frequency
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).
mysql_server
String value, used only by the MySQL module. The domain name or IP address of the MySQL server.
mysql_database
String value, used only by the MySQL module. The name of the databse which contains the database tables.
mysql_user
String value, used only by the MySQL module. The user with which to log in to the database.
mysql_pass
String value, used only by the MySQL module. The password associated with the user.
mysql_prefix
String value, used only by the MySQL module. The table prefix used to distinguish autopilot's tables in the database.
mysql_gameserver
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.
smtp_server
String value. SMTP relay server used for the admin pager command. leave empty to disable.

responses section

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 substitutions

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.

NAME
Only used in motd1, motd2 and motd3. This is replaced with the name of the client that has joined the server.
COMPANIES
Replaced with an integer, being the number of companies in the game the last time that autopilot counted them.
EMAIL
Replaced with the email address specified in the emailsetting in the [autopilot] section.
LICENSE
Replaced with the license string, as defined in the language file.
PASSWORD
Replaced with the current server password.
PLAYERS
Replaced with an integer, being the number of connected clients.
URL
Replaced with the URL specified in the urlsetting in the [autopilot] section.
VERSION
Replaced with the current autopilot version string
OTTD
Replaced with the current OpenTTD revision or release number.

Use

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:

./autopilot.tcl

This starts a new game according to what's defined in openttd.cfg

./autopilot.tcl load

This loads and continues save/game.sav

./autopilot.tcl load save/special.sav

This loads and continues save/special.sav

Chat commands

From within the game chat, three commands are acted upon by autopilot.

!page admin

This command will attempt to send an email to the admin email address.

!version

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).

MySQL module

Use of the MySQL server requires a little more preparation. The following steps must be taken:

  1. The server must be named in the server table, and its key specified in openttd.cfg
  2. 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
  3. 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.

IRC module

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:

version
shows the autopilot version
newgrf
lists the newgrf lines you’d need in your openttd.cfg
companies
lists the companies that are in the game
players
lists the players and spectators that are in the game
url
gives the #openttdcoop web site address
wiki
gives the URL of the wiki
blog
gives the URL of this blog
email
gives the email address of an admin (er, mine, as it happens…)
revision
shows the revision number of the openttd server
playercount
shows you the number of players inthe game
companycount
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.

Windows

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.

Support

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.

Powered by MediaWiki