ap+

about

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)

license

for license information please see Autopilot#License

features

standard

features from autopilot:

• 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

features introduced in ap+:

• callback environment (used for all !commands and callbacks)
• custom in-game !commands (see custom !commands for more details)
• callback on client joining the game (MOTD now takes place in here and can be sent to the new client privately)
• callback on changed server password

irc

requires: tcllib features from autopilot:

• 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

features added in ap+:

•  !rcon command can now be used by channel op's (from channel or privmsg) without rcon password (e.g. !rcon pause)
• custom !commands (see custom !commands for more details)
• callback on kick (autopilot/scripts/callback/on_irc_kick.tcl) auto-rejoin after kick now takes place here
• callback on irc connection established (autopilot/scripts/callback/on_irc_connect.tcl) (after MOTD)
•  !leave command (leave the channel, make bot rejoin with /invite)

features planed for ap+:

• capture console output and return to the command issueing irc client
• private chat between irc client and game client

mysql

unchanged, see Autopilot#MySQL module

signals

requires tclx ap+ provides kill signal catching and sourcing files from autopilot/signals/ appropriately please note that not all os's support all the signals that ap+ has support for. ap+ will filter the unsupported signals out of the list and output a warning. bin/ap-signal.sh links the kill signals to actions their respective signal tcl script performes (making it easier to determin what signal to send) (e.g. bin/ap-signal.sh IRC_QUIT will disconnect form the irc server)

custom commands

custom commands are sourced on every call, meanting they can be edited without needing ap+ to be restarted / rehashed. they are executed in the callback namespace (see callbacks for more details)

ap+
`-- autopilot
    `-- scripts
        |-- callback (callback files, creating your own has no affect)
        |-- game     (!commands, only accessible from the game)
        |-- global   (!commands, accessible from game and irc)
        `-- irc      (!commands, only accessible from irc)

place your custom <command>.tcl script into the appropriate folder, and note - currently a script can cause ap+ to crasch or lose irc connection - so test them well before going live ;-)

callbacks

custom !commands and callbacks all take place in the same namespace, namely ::ap::callback. dont overwrite it, dont create child namespaces - unless you know what you are doing ;-)

direct callbacks (executed on a certain event) are the following:

autopilot/scripts/callback/on_irc_connect.tcl

when the irc connection has been established (rfc conform, after end of /MOTD has been received)

autopilot/scripts/callback/on_irc_kick.tcl

when the bot has been kicked (default is to rejoin the channel immediately)

autopilot/scripts/callback/on_game_join.tcl

when a client joins the game, this allows to send an in-game MOTD to the client privately

autopilot/scripts/callback/on_game_serverpw.tcl

when autopilot changes the server password (not when the password is changed manually)

callback environment commands

[who]

returns a string, nick of who called the command

[private]

returns a boolean (true or false) depending on the command being issued in private or public chat (callback files - as in those in autopilot/scripts/callback - all are set to public)

[target]

returns a string, the namespace of the calling environment (e.g. ::mod_irc::say or ::ap::game::say) mainly for internal use only

[numArgs]

number of args passed to the callback

[getArg <number>]

get the argument numbered <number> 0 is the name of the command itself, so your script arguments will most likely be startig with 1 if you fetch an argument that does not exist, an empty string is returned

say::public "message"

sends "message" to the public chat of the originating call e.g. if !command was issued in irc, say::public will chat to the public irc channel

say::private "message"

send "message" to [who] in private

say::reply "message"

will reply to [who] (if command was issued publicly, reply in public. if command was issued privately reply privately)

global ap+ commands

::ap::say::everywhere "message"

send "message" to all possible outlets (game/irc/mysql)

::ap::say::fromGame "message"

same as ::ap::say::everywyere, jsut dont send "message" to the game

::ap::game::pause

pause the game

::ap::game::unpause

unpause the game

::ap::game::save <savename>

save the game to the file <savename>.sav (if <savename> is not specified, it saves to game.sav)

::ap::game::console "command\r"

send command to the dedicated console (please note the \r it gives the console command it's life!)

::ap::game::say::public [who] "message"

say "message" publicly in the game (use this if say::public would send to irc for example) only use [who] if you want to address [who] prefixing your message with "[who]: "

::ap::func::map_string "string"

map certain strings to values

::ap::func::getClientId [who]

get the in-game client id from a nick name (returns 0 if [who] is not found in the clients list)

irc related commands

::mod_irc::say::public [who] "message"

force say something in the irc channel (only pass [who] if you want to address someone, see above)

::mod_irc::nickIsOp [who]

returns a boolean, check if [who] is op in the irc channel

NOTE: only use irc related commands from irc commands (e.g. files in autopilot/scripts/irc/<command>.tcl) or wrap them in namespace checks

if {[namespace exists ::mod_irc]} {
    # your code here
}

Note: as i am working on a cleaner callback environment please note that these details are bound to change / expand

useful commands

find useful custom commands at http://pub.dihedral.de/openttd/ap+

svn

svn co http://svn.openttdcoop.org/tools/autopilot/branches/ap+