Difference between revisions of "Autopilot/ap+"

From #openttdcoop wiki

Jump to: navigation, search
(standard)
(Source (svn): -> hg)
 
(16 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 +
{|
 +
|
 
= ap+ =
 
= ap+ =
== about ==
+
|rowspan=3|__TOC__
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)
+
|-
 +
|
 +
== About ==
 +
ap+ is a branch of [[Autopilot]] - Trying to not lose too many features while providing many more. Development is at version ap+ 3.0-beta (Started counting after AutoPilot's 2.x)
 +
|-
 +
|
  
== license ==
+
== License ==
 
for license information please see [[Autopilot#License]]
 
for license information please see [[Autopilot#License]]
 +
|}
  
 
== features ==
 
== features ==
Line 35: Line 43:
 
* Provides channel and privmsg commands allowing IRC users to learn the current password
 
* Provides channel and privmsg commands allowing IRC users to learn the current password
 
* Supports CTCP VERSION and can identify to IRC services
 
* Supports CTCP VERSION and can identify to IRC services
 +
  
 
features added in ap+:
 
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)
 
* !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|custom !commands]] for more details)
 
* custom !commands (see [[#custom commands|custom !commands]] for more details)
* auto-rejoin after kick
+
* 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)
 
* !leave command (leave the channel, make bot rejoin with /invite)
 +
  
 
features planed for ap+:
 
features planed for ap+:
Line 57: Line 68:
  
 
== custom commands ==
 
== custom commands ==
the custom !commands from irc currently (please not that this will change soon) have following available variables / procedures:
+
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|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]
 
  [who]
(string) returns the name of the nick that called on irc
+
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]
 
  [target]
(string) where was the message picked up from
+
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
 +
<number> may also be end or end-<number> to count from the back
 +
[getArgs [<start=0>] [<end=end>]]
 +
start must be < end, can take any number or end-<number>, defaults to 0 (first element)
 +
end must be > start, can take any nymber or end or end-<number>, defaults to end (last element)
 +
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"
 
  ::ap::say::everywhere "message"
send a message to the game / irc / mysql (if loaded of course)
+
send "message" to all possible outlets (game/irc/mysql)
  ::mod_irc::say::reply $isPrivate [who] "message"
+
::ap::say::fromGame "message"
reply in the same manor the server has been addressed (public chat / privmsg)
+
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"
 
  ::mod_irc::say::public [who] "message"
say publicly to the channel, and highlight the client that addressed the server
+
force say something in the irc channel (only pass [who] if you want to address someone, see above)
::mod_irc::say::public "message"
+
just send a message to the irc channel
+
::mod_irc::say::private [who] message
+
send a privmsg to an irc client
+
 
  ::mod_irc::nickIsOp [who]
 
  ::mod_irc::nickIsOp [who]
(bool) check if [who] is a channel op
+
returns a boolean, check if [who] is op in the irc channel
::mod_irc::chatIsPrivate [target]
+
(boolean) true if we have been addressed in a privmsg
+
::ap::game::console "command\r"
+
execute a console command (please not the \r at the end of each command to issue)
+
::ap::game::pause and ::ap::game::unpause
+
pause / unpause the game
+
::ap::game::save [<name>]
+
save the game (default to game.sav, optionally specify a name)
+
  
 +
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
 
as i am working on a cleaner callback environment please note that these details are bound to change / expand
  
==svn==
+
==useful commands==
svn co http://svn.openttdcoop.org/tools/autopilot/branches/ap+
+
find useful custom commands at http://pub.dihedral.de/openttd/ap+ or http://ps.openttdcoop.org/publicserver/scripts
 +
 
 +
==Development Zone==
 +
http://dev.openttdcoop.org/projects/Autopilot
 +
 
 +
=== Source (Mercurial) ===
 +
hg qclone http://hg.openttdcoop.org/autopilot

Latest revision as of 15:27, 3 September 2010

ap+

About

ap+ is a branch of Autopilot - Trying to not lose too many features while providing 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 <number> may also be end or end-<number> to count from the back

[getArgs [<start=0>] [<end=end>]]

start must be < end, can take any number or end-<number>, defaults to 0 (first element) end must be > start, can take any nymber or end or end-<number>, defaults to end (last element)

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+ or http://ps.openttdcoop.org/publicserver/scripts

Development Zone

http://dev.openttdcoop.org/projects/Autopilot

Source (Mercurial)

hg qclone http://hg.openttdcoop.org/autopilot

Powered by MediaWiki
  • This page was last modified on 3 September 2010, at 15:27.