SARJ scripting

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