Blocktrix Tcl Commands:

In addition to the standard Tcl commands, Blocktrix also provides the commands
listed in this document.


plinemsg <text>

	Description: sends a partyline message to server

	Returns: nothing on success,
                 error if not connected and not serving



plineact <text>

	Description: sends a partyline action to server

	Returns: nothing on success,
		 error if not connected and not serving


splinemsg <text>

	Description: sends a partyline message to server
                     but does not display it locally

	Returns: nothing on success,
                 error if not connected and not serving



splineact <text>

	Description: sends a partyline action to server
                     but does not display it locally

	Returns: nothing on success,
		 error if not connected and not serving



glinemsg <text>

	Description: sends a gameline message to server

	Returns: nothing on success,
	         error if not connected and not serving, or if game not in progress



glineact <text>

	Description: sends a gameline action to server

	Returns: nothing on success,
		 error if not connected and not serving, or if game not in progress



lobbymsg <text>

	Description: sends a message to the lobby

	Returns: nothing on success,
		 error if not connected to lobby



lobbyact <text>

	Description: sends an action to the lobby

	Returns: nothing on success,
		 error if not connected to lobby



plinelog <text>

	Description: Displays text in the Partyline chat box

	Returns: nothing



glinelog <text>

	Description: Displays text in the Gameline chat box

	Returns: nothing



lobbylog <text>

	Description: Displays text in the Lobby chat box

	Returns: nothing



privmsg <nick> <text>

	Description: sends a private message to the specified nick.
		     (command available only in Blocktrix mode)

	Returns: Error if not in Blocktrix Mode, nothing returned on success.


privact <nick> <text>

	Description: sends a private action to the specified nick.
		     (command available only in Blocktrix mode)

	Returns: Error if not in Blocktrix Mode, nothing returned on success.



lobbyprivmsg <nick> <text>

	Description: sends a private message to the specified nick on the lobby

	Returns: Error if not connected to lobby, nothing returned on success.



lobbysmsg <text>

	Description: sends a silent message over the Lobby, it is not displayed on
		     any user's screen.  Useful for script developers.

	Returns: Error if not connected to lobby, nothing returned on success.



ignore <nick>

	Description: adds nick to client ignore list

	Returns: nothing



unignore <nick>

	Description: removes nick from client ignore list



ban <IP Mask>

	Description: adds IP Mask to the server ban list

	Returns: nothing



unban <IP Mask>

	Description: removes IP Mask from the server ban list

	Returns: nothing



inprogress

	Returns: 1 if game is in progress, 0 if game is NOT in progress



playerlist

	Returns: a list of players (in current channel, for multichannel servers)



banlist

	Returns: a list of banned ip masks in the user's blocktrix server banlist
                 box



ignorelist

	Returns: a list of nicknames in the user's ignore list



winlist

	Returns: the winner list in raw format



lobbylist

	Returns: a list of users in the lobby



isconnected

	Returns: 1 if user is connected to a server,
		 0 if user is not connected to a server



isserver

	Returns: 1 if user has server up,
		 0 if user does not have server up.



isplayerdead <player>

	Description: Determines if player has lost the game

	Returns: 1 if player has lost, 0 if player is alive
                 error if no such player



nick2slot <player>

	Returns: Slot number of player, 0 if no such player



slot2nick <slot number>

	Returns: Nickname of player at specified slot position (a value
                 between 1 and 6), returns an error if an invalid slot
                 value specified, returns an empty string if no player
                 at specified slot position.



ppm <slot number>

	Returns: Current speed (pieces per minute) that the player in the specified
                 slot position is playing at.



kick <player>

	Description: Removes a player from the server

	Returns: nothing on success,
		 error if program is not in server mode, 
                 or if no such player



isop <player>

	Returns: 1 if player is the current operator of the game,
		 0 if player is not the current operator of the game,
		 error if no such player



lobbyisop <player>

	Returns: 1 if player is a lobby operator,
		 0 if player is not a lobby operator,
		 error if no such player



lobbyisguide <player>

	Returns: 1 if player is a lobby guide,
		 0 if player is not a lobby guide,
		 error if no such player



lobbyisaway <player>

	Returns: 1 if player is marked as away,
		 0 if player is not marked as away,
		 error if no such player



lobbyonserver <player>

	Returns: Game server player is on, empty string if player is not playing,
                 error if no such player



lobbysetaway

	Description: Makes the client change their status to 'away' in the lobby

	Returns: nothing on success,
		 error if not connected to lobby,
		 or if already marked as away



lobbysetback

	Description: Makes the client change their status to 'here' in the lobby

	Returns: nothing on success,
		 error if not connected to lobby,
		 or if not marked as being away



connect

	Description: Makes the client connect to the current server in the
		     server field in client settings

	Returns: nothing on success,
		 error if client is already connected 
                 or if program is in server mode



disconnect

	Description: Makes the client disconnect from a server

	Returns: nothing on success,
		 error if client is not connected to a server



lobbyconnect

	Description: Makes the client connect to the lobby

	Returns: nothing on success,
		 error if client is already connected to lobby



lobbyquit

	Description: Makes the client disconnect from the lobby

	Returns: nothing on success,
		 error if client is not connected to the lobby




startserver

	Description: Turns on the server mode of Blocktrix

	Returns: nothing on success,
		 error if a socket is already open,
	         or if serverplaying is checked and no nickname specified


stopserver

	Description: Turns off the server mode of Blocktrix

	Returns: nothing on success,
		 error if server is already disabled


setnick ?<nick>?

	Description: Used to set and retrieve the Nickname field under
		     Client Settings

	Returns: If no nick is specified, returns the current text in the
                   Nickname field

		 If nick is specified and already connected to a server,
		   an error is returned

		 If nick is specified and not connected to a server, the
                   new nickname is returned



lobbysetnick ?<nick>?

	Description: Used to set and retrieve the Lobby Nickname for user

	Returns: If no nick is specified, returns the current nickname the user
		 is using in the Lobby, else returns nothing



setserver ?<server>?

	Description: Used to set and retrieve the Server field under
		     Client Settings

	Returns: If no server is specified, returns the current text in the
		   Server field

		 If server is specified and already connected to a server,
		   an error is returned

		 If server is specified and not connected to a server, the
		   new server text is returned



setservernick ?<nick>?

	Description: Used to set and retrieve the Nickname field under
		       Server Settings

	Returns: If no nick is specified, returns the current text in the
		  Nickname field of Server Settings

		 If nick is specified and already serving, and server playing,
                   an error is returned

		 On success, the new nickname text is returned



setteam ?<team>?

	Description: Used to set and retrieve the user's Team field entry.
		     Will also send the update through to the server if
                     connected and no game in progress, and will send
                     updated team through to all clients if the program
                     is in server mode and game is not in progress.

	Returns: If no team is specified, returns the current text in the
		 Team field entry

		 If team is specified, and connected to a server while game
		 is in progress, an error is returned

		 If team is specified, and program is in server mode,
                 and server playing is checked, and game is in progress,
                 an error is returned

		 On success, the new teamname of the user is returned



setpass <password>

	Description: Used to set the password to be used to connect to a 
                     TSpec server.

	Returns: Nothing



getteam <player>

	Description: Used to retrieve the current team for player.

	Returns: The team that the specified player is on, or
                 an error if no such player.



setmode ?<blocktrix/tetrinet/tetrifast/TSpec>?

	Description: Used to set and retrieve the chosen client mode
                     under Client Settings

	Returns: If no mode specified, returns the current selected mode

		 If mode specified, and connected to a server,
		 an error is returned

		 If mode specified, and not a valid client mode,
		 an error is returned

		 On success, the new client mode is returned



startgame

	Description: Used to start a game

	Returns: Error if not connected to a server, and not in server mode

		 Error if connected to a server and not currently operator

		 Error if game is already in progress

		 Returns nothing on success



stopgame

	Description: Used to stop a game

	Returns: Error if game is not in progress

		 Error if connected to a server and not currently operator

		 Returns nothing on success



pausegame

	Description: Used to pause a game

	Returns: Error if no game in progress or if game is already paused

		 Error if client is not operator

		 Returns nothing on success



unpausegame

	Description: Used to unpause a game

	Returns: Error if no game in progress or if game is not paused

		 Error if client is not operator

		 Returns nothing on success




putraw <text>

	Description: Sends out text over the socket connection(s).
		     Useful for Server and script developers to create
                     new commands and functionality.

	Returns: nothing

	Note: 'raw' will be prepended to the text, and all occurances
              of the protocol delimiter will be removed to prevent
              cheats.




version

	Returns: The current version of Blocktrix being used




selectedplayer

	Returns: The Currently selected player in the PlayerList box in the
                 Partyline, or an emptystring if no selection.



lobbyplayerselected

	Returns: The Currently selected player in the Lobby Userlist box, or
                 an emptystring if no selection.




addmenuitem <item> <script>

	Description: Adds a menu item to the PartyLine popup menu (Right-Click)
		     and associates the script action for when it is clicked.

	Returns: nothing

	Notes:  Use Caret's (^'s) in the item name to specify the usage of
                sub-menus. (ie. Using Commands^Server^List would add the item
                'List' to the Sub-menu 'Server' contained within the menu
                'Commands').

                To insert a seperator bar into a menu, use a hyphen (-) as the item.



addplayeritem <item> <script>

	Description: Adds a menu item to the Player List popup menu (Right-Click)
		     and associates the script action for when it is clicked.

	Returns: nothing

	Notes:  Use Caret's (^'s) in the item name to specify the usage of
                sub-menus. (ie. Using Commands^Server^List would add the item
                'List' to the Sub-menu 'Server' contained within the menu
                'Commands').

                To insert a seperator bar into a menu, use a hyphen (-) as the item.



addlobbychatmenu <item> <script>
	
	Description: Adds a menu item to the Lobby Chat popup menu (Right-Click)
		     and associates the script action for when it is clicked.

	Returns: nothing

	Notes:  Use Caret's (^'s) in the item name to specify the usage of
                sub-menus. (ie. Using Commands^Server^List would add the item
                'List' to the Sub-menu 'Server' contained within the menu
                'Commands').

                To insert a seperator bar into a menu, use a hyphen (-) as the item.



addlobbyusermenu <item> <script>

	Description: Adds a menu item to the Lobby Userlist popup menu (Right-Click)
		     and associates the script action for when it is clicked.

	Returns: nothing

	Notes:  Use Caret's (^'s) in the item name to specify the usage of
                sub-menus. (ie. Using Commands^Server^List would add the item
                'List' to the Sub-menu 'Server' contained within the menu
                'Commands').

                To insert a seperator bar into a menu, use a hyphen (-) as the item.



stripcodes <text>

	Description: Strips all colour/bold/italics/underline codes from the specified
                     text.

	Returns: The text with all the codes removed.



addtab <tab>

	Description: Adds a Tab Window to the partyline with the caption 
                     specified by <tab>.

	Returns: nothing



closetab <tab>

	Description: Closes a Tab Window on the partyline with the caption
		     specified by <tab>.

	Returns: nothing


cleartab <tab>

	Description: Clears the Text display from the specified tab window.

	Returns: nothing


tablog <tab> <text>

	Description: Displays text in the Tab Window specified by <tab>.

	Returns: nothing



tabfont <tab> <font name> <font size>

	Description: Changes the Font and fontsize to use when displaying
		     the text in the specified tab.

	Returns: nothing



tab ?<tab>?

	Description: Used to switch Tab windows, or return the current
                     visible Tab Window if no tab specified.

	Returns: The Tab that has been switched to, or the current visible
                 Tab if no tab change specified.  Returns an Error if
                 Tab is specified and no such Tab exists.



playsound <file>

	Description: Used to play a wav sound file.

	Returns: nothing



startrecording <file>

	Description: Starts recording all games and chat to the specified file.

	Returns: Error if already recording, nothing on success



stoprecording

	Description: Stops recording game and chat data

	Returns: Error if recording not in progress, nothing on success	



sockconnect <host> <port> <proc-name>

	Description: Used to create simple outgoing Tcp connections.
		     Upon receiving incoming data, proc-name is called with
		     two arguments, the socket descriptor, and the data being read.

		     The callback procedure would be declared, for example as such:
			
		     proc proc-name {sock data} { # process data }

		     Upon connection, the callback procedure is called with "###connect###",
                     and upon disconnection, the callback procedure is called with "###eof###".


	Returns: an integer known as the socket descriptor



sockdisconnect <socket descriptor>

	Description: Used to close a connection opened using sockconnect (see above.)

	Returns: nothing



putsock <socket descriptor> <text>

	Description: Used to send text to a connection previously opened by sockconnect (see above.)

	Returns: nothing


describe <text>

	Description: Used to set a description for the current script the command is being
		     called from.  The description is displayed under Misc. Settings->Scripts


dns <ip/host>

	Description: Used to resolve an IP address to its Hostname, or a Hostname to
		     its IP address.

	Returns: Hostname for a resolved IP, or an IP for a resolved Hostname.
		 Returns a blank string if a hostname is not resolvable, or returns
		 the IP address itself if it is not resolvable.

clearfields

	Description: Used to clear all the fields when in TSPec mode, and game is not
		     in progress.

	Returns: nothing on success, error if not in TSPec mode, or game is in progress


addbind <type> <proc-name>

	Description: You can use the 'addbind' command to attach Tcl procedures
		     to certain events.

	Returns: Error if proc is already bound to type

		 Returns nothing on success



unbind <type> <proc-name>

	Description: Removes a previously created binding

	Returns: Error if proc is not bound to type

		 Returns nothing on success



Bind Types:

	1. CONNECT

		addbind connect <proc>
		procname

		Description:  Used after successfully connecting to and
			      logging in to a server.  Calls proc with
			      no arguments.


	2. DISCONNECT

		addbind disconnect <proc>
		procname

		Description:  Used upon disconnecting from a server.
			      Calls proc with no arguments.


	3. SERVERSTART

		addbind serverstart <proc>
		procname

		Description:  Used after starting up server mode.
			      Calls proc with no arguments.

	
	4. SERVERSTOP

		addbind serverstop <proc>
		procname

		Description:  Used upon stopping server mode.
			      Calls proc with no arguments.


	5. JOIN

		addbind join <proc>
		procname <player>

		Description:  Used for when a player joins the game.
			      Calls proc with a single argument, the
			      nickname of the player that joined.


	6. LEAVE

		addbind leave <proc>
		procname <player>

		Description:  Used for when a player leaves the game.
			      Calls proc with a single argument, the
			      nickname of the player that left.


	7. TEAMCHANGE

		addbind teamchange <proc>
		procname <player> <old team> <new team>

		Description:  Used for when a player changes team names.
			      Calls proc with 3 arguments, the
			      nickname of the player, the player's old
			      team name, and the player's new team name.


	8. PLINEMSG

		addbind plinemsg <proc>
		procname <player> <text>

		Description:  Used for when a player sends a partyline
			      message.  Calls proc with 2 arguments,
			      the nickname of the player, and the
			      message the player has sent.

		Note: Return 1 to stop further processing of the message.
			(ie. To prevent the message from being displayed)



	9. PLINEACT

		addbind plineact <proc>
		procname <player> <text>

		Description:  Used for when a player sends a partyline
			      action.  Calls proc with 2 arguments,
			      the nickname of the player, and the
			      action the player has sent.

		Note: Return 1 to stop further processing of the message.
			(ie. To prevent the action from being displayed)



	10. GLINEMSG

		addbind glinemsg <proc>
		procname <player> <text>

		Description:  Used for when a player sends a gameline
			      message.  Calls proc with 2 arguments,
			      the nickname of the player, and the
			      message the player has sent.

		Note: Return 1 to stop further processing of the message.
			(ie. To prevent the message from being displayed)



	11. GLINEACT

		addbind glineact <proc>
		procname <player> <text>

		Description:  Used for when a player sends a gameline
			      action.  Calls proc with 2 arguments,
			      the nickname of the player, and the
			      action the player has sent.


		Note: Return 1 to stop further processing of the message.
			(ie. To prevent the action from being displayed)



	12. STARTGAME

		addbind startgame <proc>
		procname

		Description:  Used for when a game is started.  Calls
			      proc with no arguments.



	13. ENDGAME

		addbind endgame <proc>
		procname <winner>

		Description:  Used for when a game is ended.  Calls proc
			      with one argument, the game winner, or a
			      blank string if game explicitly stopped.



	14. PAUSEGAME

		addbind pausegame <proc>
		procname

		Description:  Used for when a game is paused.  Calls proc
			      with no arguments.



	15. UNPAUSEGAME

		addbind unpausegame <proc>
		procname

		Description:  Used for when a game is unpaused.  Calls proc
			      with no arguments.



	16. KICK

		addbind kick <proc>
		procname <player>

		Description:  Used for when a player is kicked from the game.
			      Calls proc with one argument, the nickname of
			      the player kicked.



	17. PMSGOUT

		addbind pmsgout <proc>
		procname <text>

		Description:  Used for when sending a message over the partyline.
			      Calls proc with one argument, the text to be
			      sent out.

		Note: Return 1 to stop further processing of the message.
			(ie. To prevent the message from being sent out)



	18. PACTOUT

		addbind pactout <proc>
		procname <text>

		Description:  Used for when sending an action over the partyline.
			      Calls proc with one argument, the text to be
			      sent out.

		Note: Return 1 to stop further processing of the action.
			(ie. To prevent the action from being sent out)



	19. GMSGOUT

		addbind gmsgout <proc>
		procname <text>

		Description:  Used for when sending a message over the gameline.
			      Calls proc with one argument, the text to be
			      sent out.

		Note: Return 1 to stop further processing of the message.
			(ie. To prevent the message from being sent out)



	20.  GACTOUT

		addbind gactout <proc>
		procname <text>

		Description:  Used for when sending an action over the gameline.
			      Calls proc with one argument, the text to be
			      sent out.

		Note: Return 1 to stop further processing of the action.
			(ie. To prevent the action from being sent out)




	21. RAW

		addbind raw <proc>
		procname <text>

		Description:  Used to catch raw text sent from a putraw send.
			      Calls proc with one argument, the text received.

		Note: The prepended 'raw' from the putraw command is stripped
		      before calling the proc.



	22. CLOSE

		addbind close <proc>
		procname <text>

		Description:  Used for when program is being exitted by user.
			      Calls procedure with no arguments.



	23. PRIVMSGOUT

		addbind privmsgout <proc>
		procname <destination nick> <text>

		Description:  Used for when sending a private message to
			      another user.
			      Calls proc with two arguments, the nickname
			      of the receiver of the message, and the text
			      to be sent to the user.

		Note: Return 1 to stop further processing of the message.
		      (ie. To prevent the message from being sent out)
		      This binding is only triggered in Blocktrix mode.



	24. PRIVACTOUT

		addbind privactout <proc>
		procname <destination nick> <text>

		Description:  Used for when sending a private action to
			      another user.
			      Calls proc with two arguments, the nickname
			      of the receiver of the action, and the text
			      to be sent to the user.

		Note: Return 1 to stop further processing of the action.
		      (ie. To prevent the action from being sent out)
		      This binding is only triggered in Blocktrix mode.



	25. PRIVMSG

		addbind privmsg <proc>
		procname <player> <text>

		Description:  Used for when a player sends a private
			      message.  Calls proc with 2 arguments,
			      the nickname of the player, and the
			      message the player has sent.

		Note: Return 1 to stop further processing of the message.
		      (ie. To prevent the message from being displayed)
		      This binding is only triggered in Blocktrix mode.



	26. PRIVACT

		addbind privact <proc>
		procname <player> <text>

		Description:  Used for when a player sends a private
			      action.  Calls proc with 2 arguments,
			      the nickname of the player, and the
			      action the player has sent.

		Note: Return 1 to stop further processing of the action.
		      (ie. To prevent the action from being displayed)
		      This binding is only triggered in Blocktrix mode.



	27. LOBBYCONNECT

		addbind lobbyconnect <proc>
		procname

		Description:  Used for when the client connects to the lobby.
			      Calls proc with no arguments.



	28. LOBBYDISCONNECT

		addbind lobbydisconnect <proc>
		procname

		Description:  Used for when the client has disconnected from the lobby.
			      Calls proc with no arguments.



	29. LOBBYJOIN

		addbind lobbyjoin <proc>
		procname <player>

		Description:  Used for when a player joins the lobby.
			      Calls proc with 1 argument, the nickname
			      of the joining player.



	30. LOBBYQUIT

		addbind lobbyquit <proc>
		procname <player>

		Description:  Used for when a player leaves the lobby.
			      Calls proc with 1 argument, the nickname
			      of the leaving player.



	31. LOBBYMSG

		addbind lobbymsg <proc>
		procname <player> <text>

		Description:  Used for when a player has sent a message to
		              the lobby.  Calls proc with 2 arguments, the
			      nickname of the player, and the text that was
			      sent.

		Note: Return 1 to stop further processing of the message.
		      (ie. To prevent the message from being displayed)



	32. LOBBYMSGOUT

		addbind lobbymsgout <proc>
		procname <text>

		Description:  Used for when the local client is sending out text
			      to the lobby.  Calls proc with 1 argument, the
			      text that the client is sending.

		Note: Return 1 to stop further processing of the message.
		      (ie. To prevent the message from being sent)



	33. LOBBYACT

		addbind lobbyact <proc>
		procname <player> <text>

		Description:  Used for when a player has sent an action to
		              the lobby.  Calls proc with 2 arguments, the
			      nickname of the player, and the text that was
			      sent.

		Note: Return 1 to stop further processing of the action.
		      (ie. To prevent the action from being displayed)



	34. LOBBYACTOUT

		addbind lobbyactout <proc>
		procname <text>

		Description:  Used for when the local client is sending out an
			      action to the lobby.  Calls proc with 1 argument, 
			      the text that the client is sending.

		Note: Return 1 to stop further processing of the action.
		      (ie. To prevent the action from being sent)



	35. LOBBYPRIVMSG

		addbind lobbyprivmsg <proc>
		procname <player> <text>

		Description:  Used for when the local client receives a private
			      message from another player.  Calls proc with 2
			      arguments, the nickname of the player sending the
			      message, and the text that is being received.

		Note: Return 1 to stop further processing of the message.
		      (ie. To prevent the message from being displayed)



	36. LOBBYPRIVMSGOUT

		addbind lobbyprivmsgout <proc>
		procname <text>

		Description:  Used for when the local client is sending a private
			      message to another player.  Calls proc with 1
			      argument, the text being sent out.

		Note: Return 1 to prevent message from being locally displayed.



	37. LOBBYKICK

		addbind lobbykick <proc>
		procname <player> <reason>

		Description:  Used for when a player has been kicked from the
			      lobby by an operator.  Calls proc with 2 arguments,
			      the nickname of the kicked player, and the reason
			      for the kick.



	38. LOBBYNICK

		addbind lobbynick <proc>
		procname <oldnick> <newnick>

		Description:  Used for when a player changes their nickname on the lobby.
			      Calls proc with 2 arguments, the old nickname, and the new
			      nickname.



	39. LOBBYSMSG

		addbind lobbysmsg <proc>
		procname <player> <text>

		Description:  Used for when a player as sent a silent message over the lobby.
			      Calls proc with 2 arguments, the nickname of the player, and
			      the text the player has sent.



	40. GAMELOG

		addbind gamelog \'3Cproc\'3E
		procname \'3Cfrom\'3E \'3Con\'3E \'3Cmessage\'3E

		Description:  Used for when an attack/defense is performed and displayed to
                  the attack/defense log area.  Calls proc with 3 arguments, the player name
                  that the attack/defense came from, the player name of the target, and the
                  attack/defense that was performed.




Variables:

		$lastgamestats
		
		Description: A list of all the player statistics from the previous
			     game, each element consisting of the player name,
                             their Pieces Per Minute, Lines Cleared, Lines Added,
                             Specials Used, Player Level, Pieces Dropped, Seconds Lasted



		$lastpiecestats

		Description: A list of the player's piece statistics for the previous
			     game, each element consisting of an ascii of the figure, 
                             the number of times that piece occured in the game,
			     the percent of the occurancy of that piece for the game,
			     and the probability of that figure for the game



		$lastspecstats

		Description: A list of the player's specials statistics for the previous
			     game, each element consisting of the letter representing
			     the special, the number of times that special occured in the
			     game, the percent of the occurancy of that special for the 
			     game, and the probability of that special for the game



		$lastholestats

		Description: A list of the hole distribution count (and percentages) in
			     each of the 12 columns for added lines to the player


-- See the scripts included in the scripts directory of Blocktrix for
   examples.
