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
|
|
When SARJ initially loads | none |
|
When the user exits the program | none |
|
When a connection is successfully established to a server | none |
|
When the connection to a server is lost | none |
|
When a player requests to join the server |
PLAYER_IP
- The IP address of the player |
|
When a player has joined the game |
PLAYER_NAME
- The name of the player |
|
When a player has left the game | PLAYER_NAME - The name of the player |
|
When an administrator has connected to the server | none |
|
When an administrator has disconnected from the server | none |
|
When a player speaks in-game | PLAYER_NAME
- The name of the player SPEECH_TEXT - The speech text of the player |
|
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 |
|
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 |
---|
java.lang.String getCurrentMap()
String
containing the name of the current mapjava.lang.String getGameType()
String
containing the name of the current game typeint getTimeLimit()
int getScoreLimit()
int getTimeLeft()
int getNumPlayers()
void setWindowTitle(java.lang.String title)
title
- the new title for the windowjava.lang.String getWindowTitle()
String
containing the title of the main windowjava.lang.String getIPField()
String
containing the value of the IP fieldjava.lang.String getPortField()
String
containing the value of the port fieldjava.lang.String getPasswordField()
java.lang.String getCommandBox()
String
containing the value of the command combo boxvoid setIPField(java.lang.String ip)
ip
- the new IP address valuevoid setPortField(java.lang.String port)
port
- the new port valuevoid setPasswordField(java.lang.String password)
password
- the new password valuevoid setCommandBox(java.lang.String command)
command
- the new value to set the command combo box tovoid clearConsole()
void disconnectClient()
void connectClient(java.lang.String ip, int port)
ip
- the IP address of the serverport
- the port number of the servervoid connectClient()
void writeToConsole(java.lang.String text)
text
- the text to print on the consolevoid sendData(java.lang.String data)
data
- the data to sendjava.lang.String[] getPlayerData(java.lang.String playerName)
playerName
- the name of the player to match
java.lang.String[][] getPlayerData()
String
objects containing the data in the
tablejava.lang.String[] getTeamData(java.lang.String teamName)
teamName
- the name of the team to match
java.lang.String[][] getTeamData()
String
objects containing the data in the table