SmartFoxServer 2X JavaScript server API Global

Members

BanMode

The BanMode enum lists all possible user banning modes.

Available BanMode values are:

BY_ADDRESS: ban by IP address
BY_NAME: ban by user name

Notes:

For members of the BanMode enum, please refer to its Javadoc.

Notes:

For members of the BoolMatch enum, please refer to its Javadoc.

Notes:

For members of the ClientDisconnectionReason enum, please refer to its Javadoc.

Notes:

For members of the InvitationResponse enum, please refer to its Javadoc.

Notes:

For members of the NumberMatch enum, please refer to its Javadoc.

Notes:

For members of the RoomProperties object, please refer to its Javadoc.

Notes:

For members of the SFSEventType object, please refer to its Javadoc.

Notes:

For members of the SFSRoomRemoveMode enum, please refer to its Javadoc.

SFSRoomSettings

The SFSRoomSettings enum lists all valid data types for User, Room, Buddy and MMOItem Variables.

Available SFSRoomSettings values are:

ROOM_NAME_CHANGE: toggles the ability to change the name of the Room at runtime
CAPACITY_CHANGE: toggles the ability to change the capacity of the Room at runtime
PASSWORD_STATE_CHANGE: toggles the ability to change the password of the Room at runtime
PUBLIC_MESSAGES: toggles the ability to send public messages in the Room
USER_COUNT_CHANGE_EVENT: toggles the notification of changes in the count of users and spectators in the Room
USER_ENTER_EVENT: toggles the notification of users entering the Room
USER_EXIT_EVENT: toggles the notification of users leaving the Room
USER_VARIABLES_UPDATE_EVENT: toggles the notification of User Variables changes the Room

Notes:

For members of the SFSRoomSettings enum, please refer to its Javadoc.

StringMatch

The StringMatch enum lists all string-related conditions that can be used in a Match Expression.

Available StringMatch values are:

CONTAINS: the str1.indexOf(str2) > -1 condition
ENDS_WITH: the str1.endsWith(str2) condition
EQUALS: the str1.equals(str2) condition
NOT_EQUALS: the !str1.equals(str2) condition
STARTS_WITH: the str1.startsWith(str2) condition

Notes:

For members of the StringMatch enum, please refer to its Javadoc.

Notes:

For members of the UserProperties object, please refer to its Javadoc.

Notes:

For members of the VariableType enum, please refer to its Javadoc.

Methods

addEventHandler(eventType, evtHandlerFn)

Registers an handler for an inner server event.

All available event types fired by the server are listed in the SFSEventType enum.
Event handlers can be registered in the Extension's init method; they receive an SFSEvent object as the only parameter.

Parameters:

Name	Type	Description
`eventType`	SFSEventType	One of the event types listed in the SFSEventType enum.
`evtHandlerFn`	evtHandlerFn	The function that will handle the event.

Example

In this example we register an handler for the SERVER_READY event type during the Extension initialization.

function init()
{
	// Register event handlers
	addEventHandler(SFSEventType.SERVER_READY, onExtensionReady);
}

function onExtensionReady(event)
{
	trace("Extension is ready");
}

addRequestHandler(cmdName, reqHandlerFn)

Registers a request handler for a specific command.

Request handlers can be registered in the Extension's init method.

Parameters:

Name	Type	Description
`cmdName`	string	The name of the command, which identifies the request sent by the client.
`reqHandlerFn`	reqHandlerFn	The function that will handle the incoming request.

Example

In this example we register a request handler for command "sum" during the Extension initialization. The Extension can then receive the "sum" request containing two integers from any client, calculate their sum and send it back to the requester.

function init()
{
	// Register client request handlers
	addRequestHandler("sum", onSumRequest);
}

function onSumRequest(inParams, sender)
{
	var n1 = inParams.getInt("n1");
	var n2 = inParams.getInt("n2");

	var outParams = new SFSObject();
	outParams.putInt("s", n1+n2);

	// Send response
	send("sum", outParams, [sender]);
}

getApi()

Returns a reference to the SFSApi class instance, providing access to the main SmartFoxServer 2X server side API.

Returns:

A reference to the SFSApi class instance.

Type: SFSApi

getBuddyApi()

Returns a reference to the BuddyApi class instance, providing access to the specialized server side API related to Buddy List features.

Returns:

A reference to the BuddyApi class instance.

Type: BuddyApi

getCurrentFolder()

Returns the relative path to the current Extension folder.

Typically this method will return a string like "extensions/{name-of-extension}/". The path is relative to the server root folder and it can be used to load external data files that are stored together with the Extension's JavaScript file(s).

Returns:

The path of the current Extension folder.

Type: string

getDBManager()

Returns a reference to the

SFSDBManager class instance attached to the Zone to which the Extension belongs.

The Database Manager takes care of the connection to a database using either JDBC native drivers or JDBC-ODBC bridge; it provides configurable connection pooling for optimal performance and resource usage.
Each Zone runs its own Database Manager, which can be configured via the Zone Configurator module in the SmartFoxServer 2X Administration Tool.

Returns:

A reference to the

SFSDBManager class instance.

Type: SFSDBManager

getFileApi()

Returns a reference to the FileApi class instance, providing access to the specialized server side API related to files management.

Returns:

A reference to the FileApi class instance.

Type: FileApi

getGameApi()

Returns a reference to the GameApi class instance, providing access to the specialized server side API related to SFSGame features.

Returns:

A reference to the GameApi class instance.

Type: GameApi

getMMOApi()

Returns a reference to the MMOApi class instance, providing access to the specialized server side API related to MMO features.

Returns:

A reference to the MMOApi class instance.

Type: MMOApi

getParentRoom()

Returns the

SFSRoom object to which this Extension is attached (for Room-level Extensions only).

Returns:

The

SFSRoom object to which the Extension is attached, or null if this is not a Room-level Extension.

Type: SFSRoom

getParentZone()

Returns the

SFSZone object which is parent to this Extension.

If case of a Zone-level Extension, this method returns its parent Extension; in case of a Room-level Extension, it returns the Zone to which the Room belongs.

Returns:

The

SFSZone object to which the Extension belongs.

Type: SFSZone

include(scriptPath)

Includes other JavaScript files in the Extension.
This helps writing modular code, where classes, functions and other objects are divided into separate folders and/or files.

Parameters:

Name	Type	Description
`scriptPath`	string	The path of the JavaScript file to be included, relative to the main Extension script's folder.

send(cmdName, params, recipients [, isUdp])

Sends an Extension message/response to a list of recipients.

The Extension response can be sent using the UDP protocol instead of the default TCP protocol. This is an unrealiable network protocol that does not guarantee delivery and ordering of the packets, but it can be useful for fast data transfer speed in real-time type games (typically for position/transformation updates).
UDP messages can be sent to clients if: 1) the client technology supports it (for example HTML5 clients DO NOT support UDP); 2) the client has already initialized the UDP protocol transmission.

Parameters:

Name	Type	Argument	Default	Description
`cmdName`	string			The name of the command, which identifies an action that should be executed by the client, or a response that the client is waiting for.
`params`	SFSObject			An SFSObject containing custom data to be sent to the client. If `null` is passed, no other data than the command name is sent.
`recipients`	Array.<SFSUser>			An array of SFSUser objects identifying the recipients of the message.
`isUdp`	boolean	<optional>	false	If `true`, the message will be sent using the UDP protocol.

Example

function init()
{
	// Register client request handlers
	addRequestHandler("sum", onSumRequest);
}

function onSumRequest(inParams, sender)
{
	var n1 = inParams.getInt("n1");
	var n2 = inParams.getInt("n2");

	var outParams = new SFSObject();
	outParams.putInt("s", n1+n2);

	// Send response
	send("sum", outParams, [sender]);
}

setThreadSafe(value)

Changes the thread safety setting of the current Extension. By default thread-safety is enabled.

Important note:

Disabling the Extension's thread safety can be risky. JavaScript is not a thread-safe language, so disabling the thread safety will introduce concurrency issues that can be solved by using the appropriate Java classes/collections only.
Learn more about concurrency in JavaScript Extensions in this article.

Parameters:

Name	Type	Description
`value`	boolean	If `false`, the Extension will run as non thread-safe.

trace(arguments)

Outputs the passed arguments to the console and log file.
This is useful for remote debugging when developing Extensions.

Parameters:

Name	Type	Argument	Description
`arguments`	*	<repeatable>	Any number of strings or objects to trace.

Type Definitions

evtHandlerFn(event)

This callback function is called when the Extension receives an event fired by the server for which an handler has been registered using the addEventHandler method.

Parameters:

Name	Type	Description
`event`	SFSEvent	The SFSEvent object containing the parameters of the specific event.

httpCallbackFn(result)

This callback function is called when the Extension receives the response to an HTTP request sent using the SFSApi.HttpRequest#execute method.

Parameters:

Name	Type	Description
`result`	object	An object providing the result of the HTTP request. The object contains the following parameters: statusCode (number) - The status code of the request html (string) - The content of the response (it could be HTML, JSON, XML, etc) error (string - The error message (if the request failed)

invCallBackHandler(invObj, params)

This callback handler is an object containing the onAccepted, onRefused and onExpired methods, respectively called when an invitation sent using the GameApi#sendInvitation method is accepted, refused or expires before a reply is received.

Parameters:

Name	Type	Description
`invObj`	Invitation	A SFSInvitation object representing the invitation sent to the recipient(s).
`params`	SFSObject	The SFSObject containing the custom parameters attached to the invitation reply, if any. This parameter is passed to onAccepted and onRefused functions only.

Example

This example shows how to create this callback handler.

var invitationCallBackHandler = {
	onAccepted: function(invObj, params)
	{
		// Handle invitation accepted
		...
	},

	onRefused(invObj, params)
	{
		// Handle invitation refused
		...
	},

	onExpired: function(invObj)
	{
		// Handle invitation expired
		...
	}
};

reqHandlerFn(params, sender)

This callback function is called when the Extension receives a request from a client for which an handler has been registered using the addRequestHandler method.

Parameters:

Name	Type	Description
`params`	SFSObject	The SFSObject containing the parameters attached to the client request.
`sender`	SFSUser	The SFSUser object identifying the sender of the request.

Global

Members

BanMode

Notes:

See also

BoolMatch

Notes:

See also:

ClientDisconnectionReason

Notes:

See also:

InvitationResponse

Notes:

See also:

NumberMatch

Notes:

See also:

RoomProperties

Notes:

See also:

SFSEventType

Notes:

See also:

SFSRoomRemoveMode

Notes:

SFSRoomSettings

Notes:

StringMatch

Notes:

See also:

UserProperties

Notes:

See also:

VariableType

Notes:

Methods

addEventHandler(eventType, evtHandlerFn)

See also:

Parameters:

Example

addRequestHandler(cmdName, reqHandlerFn)

Parameters:

Example

getApi()

See also:

Returns:

getBuddyApi()

Returns:

getCurrentFolder()

Returns:

getDBManager()

Returns:

getFileApi()

Returns:

getGameApi()

Returns:

getMMOApi()

Returns:

getParentRoom()

Returns:

getParentZone()

Returns:

include(scriptPath)

Parameters:

send(cmdName, params, recipients [, isUdp])

Parameters:

Example

setThreadSafe(value)

Important note:

Parameters:

trace(arguments)

Parameters:

Type Definitions

evtHandlerFn(event)

Parameters:

httpCallbackFn(result)

Parameters:

invCallBackHandler(invObj, params)

See also:

Parameters: