SARJ Scripting

This page is designed to be a very brief 'getting started' guide for scripting, as well as a quick reference for the main methods used to manipulate the client. It is not meant to be a guide to programming in Java or JavaScript. The reader is assumed to already have a basic knowledge of JavaScript (also known as 'EcmaScript'), but tutorials should be widely available on the internet for anyone not familiar. The reader is also recommended to refer to the documentation and examples on the FESI web site for help.

Each script should be contained within a file labelled with a '.js' or '.es' extension to be interpreted correctly. Scripts should contain only legal JavaScript code. Most scripts begin interpretation with no parameters, with the exception of the event-triggered scripts which contain parameters relating to the event (for example, the onPlayerSpeak script will have PLAYER_NAME and SPEECH_TEXT variables to contain the name and text of the speaker, respectively). A full list of events and parameters passed to related scripts is given below:

 

Event name
Called
Parameters passed

onLoad

When SARJ initially loads none

onExit

When the user exits the program none

onConnect

When a connection is successfully established to a server none

onDisconnect

When the connection to a server is lost none

onJoinRequest

When a player requests to join the server

PLAYER_IP - The IP address of the player
PLAYER_PORT - The port of the player

onPlayerJoin

When a player has joined the game

PLAYER_NAME - The name of the player
PLAYER_IP - The IP address of the player
PLAYER_PORT - The port of the player

onPlayerLeave

When a player has left the game PLAYER_NAME - The name of the player

onAdminConnect

When an administrator has connected to the server none

onAdminDisconnect

When an administrator has disconnected from the server none

onPlayerSpeak

When a player speaks in-game PLAYER_NAME - The name of the player
SPEECH_TEXT - The speech text of the player

onTimeLeftNotify

When a notification of the time left on the current map is sent from the server TIME_LEFT - The time, in minutes, remaining on the current map

onDataReceived

When any data is received from the server DATA_STRING - The data received from the server

 

Interacting with SARJ
To interact with the SARJ client, a script must first obtain a reference to it. This is done by specifying the path of the SARJ class and invoking the instance() method, as shown below:

mainProgram = Packages.sarj.Sarj.instance();

mainProgram.writeToConsole("Hello, World!\n");

Using the same method, a script can access all classes in the Java API. For example:

swing = Packages.javax.swing;

swing.JOptionPane.showMessageDialog(null, "This is a message dialog", "Title", swing.JOptionPane.OK_OPTION);

Debugging
All debugging and error messages are sent to the standard error output, and should be seen in a console window if running SARJ from a command line. If you are running directly from a JAR file, you can press ALT+S (or right click and select from the popup menu) to hide/show a log console that will display the same data.

Reference
A list of the most common scripting methods are provided below. For a complete reference, please download the SARJ source code and consult the documentation directory.

 

Method Summary
 void clearConsole()
          Clears the console on the main window
 void connectClient()
          Connects the client to the IP and port displayed on the main window
 void connectClient(java.lang.String ip, int port)
          Connects the client to the specified IP and port
 void disconnectClient()
          Disconnects the client from any connected server
 java.lang.String getCommandBox()
          Returns the value of the command combo box on the main window
 java.lang.String getCurrentMap()
          Returns the name of the map currently being played on the server
 java.lang.String getGameType()
          Returns the type of game running on the server
 java.lang.String getIPField()
          Returns the value of the IP field on the main window
 int getNumPlayers()
          Returns the number of players connected to the server
 java.lang.String getPasswordField()
          Returns the current value stored in the password field on the main window
 java.lang.String[][] getPlayerData()
          Returns all data within the player table on the main window
 java.lang.String[] getPlayerData(java.lang.String playerName)
          Returns the row of the player table with the player name matching that provided
 java.lang.String getPortField()
          Returns the value of the port field on the main window
 int getScoreLimit()
          Returns the score limit of the game
 java.lang.String[][] getTeamData()
          Returns all data within the team table on the main window
 java.lang.String[] getTeamData(java.lang.String teamName)
          Returns the row of the team table with the team name matching that provided
 int getTimeLeft()
          Returns the time left within the current game
 int getTimeLimit()
          Returns the time limit of the current game
 java.lang.String getWindowTitle()
          Returns the main SARJ window title
 void sendData(java.lang.String data)
          Sends data to a connected server
 void setCommandBox(java.lang.String command)
          Sets the command combo box field on the main window
 void setIPField(java.lang.String ip)
          Sets the IP field on the main window
 void setPasswordField(java.lang.String password)
          Sets the password field on the main window
 void setPortField(java.lang.String port)
          Sets the port field on the main window
 void setWindowTitle(java.lang.String title)
          Sets the main SARJ window title to that specified
 void writeToConsole(java.lang.String text)
          Writes text to the main command console
 

Method Detail

getCurrentMap

java.lang.String getCurrentMap()
Returns the name of the map currently being played on the server

Returns:
a String containing the name of the current map

getGameType

java.lang.String getGameType()
Returns the type of game running on the server

Returns:
a String containing the name of the current game type

getTimeLimit

int getTimeLimit()
Returns the time limit of the current game

Returns:
the current time limit, in seconds

getScoreLimit

int getScoreLimit()
Returns the score limit of the game

Returns:
the score limit

getTimeLeft

int getTimeLeft()
Returns the time left within the current game

Returns:
the time remaining, in seconds

getNumPlayers

int getNumPlayers()
Returns the number of players connected to the server

Returns:
the number of players currently connected

setWindowTitle

void setWindowTitle(java.lang.String title)
Sets the main SARJ window title to that specified

Parameters:
title - the new title for the window

getWindowTitle

java.lang.String getWindowTitle()
Returns the main SARJ window title

Returns:
a String containing the title of the main window

getIPField

java.lang.String getIPField()
Returns the value of the IP field on the main window

Returns:
a String containing the value of the IP field

getPortField

java.lang.String getPortField()
Returns the value of the port field on the main window

Returns:
a String containing the value of the port field

getPasswordField

java.lang.String getPasswordField()
Returns the current value stored in the password field on the main window

Returns:
a String object containing the unmasked value of the password field

getCommandBox

java.lang.String getCommandBox()
Returns the value of the command combo box on the main window

Returns:
a String containing the value of the command combo box

setIPField

void setIPField(java.lang.String ip)
Sets the IP field on the main window

Parameters:
ip - the new IP address value

setPortField

void setPortField(java.lang.String port)
Sets the port field on the main window

Parameters:
port - the new port value

setPasswordField

void setPasswordField(java.lang.String password)
Sets the password field on the main window

Parameters:
password - the new password value

setCommandBox

void setCommandBox(java.lang.String command)
Sets the command combo box field on the main window

Parameters:
command - the new value to set the command combo box to

clearConsole

void clearConsole()
Clears the console on the main window


disconnectClient

void disconnectClient()
Disconnects the client from any connected server


connectClient

void connectClient(java.lang.String ip,
                   int port)
Connects the client to the specified IP and port

Parameters:
ip - the IP address of the server
port - the port number of the server

connectClient

void connectClient()
Connects the client to the IP and port displayed on the main window


writeToConsole

void writeToConsole(java.lang.String text)
Writes text to the main command console

Parameters:
text - the text to print on the console

sendData

void sendData(java.lang.String data)
Sends data to a connected server

Parameters:
data - the data to send

getPlayerData

java.lang.String[] getPlayerData(java.lang.String playerName)
Returns the row of the player table with the player name matching that provided

Parameters:
playerName - the name of the player to match
Returns:
the data contained in the table relating to the player

getPlayerData

java.lang.String[][] getPlayerData()
Returns all data within the player table on the main window

Returns:
a 2D array of String objects containing the data in the table

getTeamData

java.lang.String[] getTeamData(java.lang.String teamName)
Returns the row of the team table with the team name matching that provided

Parameters:
teamName - the name of the team to match
Returns:
the data contained in the table relating to the team

getTeamData

java.lang.String[][] getTeamData()
Returns all data within the team table on the main window

Returns:
a 2D array of String objects containing the data in the table

 


Copyright © 2005 Richard Davies