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:
See also

BoolMatch


The BoolMatch enum lists all boolean conditions that can be used in a Match Expression.

Available BoolMatch values are:

  • EQUALS: the bool1 == bool2 condition
  • NOT_EQUALS: the bool1 != bool2 condition
Notes:
See also:

ClientDisconnectionReason


The ClientDisconnectionReason enum lists all possible disconnection reasons provided by the USER_DISCONNECT event.

Possible ClientDisconnectionReason values are:

  • IDLE: the client was disconnected because he was idle for longer than the time configured in the Zone as (maxUserIdleTime setting)
  • KICK: the client was kicked
  • BAN: the client was banned
  • UNKNOWN: the disconnection reason was not detected
Notes:
See also:

InvitationResponse


The InvitationResponse enum lists all possible replies to an invitation.

Possible InvitationResponse values are:

  • ACCEPT: accept the invitation
  • REFUSE: refuse the invitation
  • EXPIRED: the invitation expired before a reply was sent
Notes:
See also:

NumberMatch


The NumberMatch enum lists all numeric conditions that can be used in a Match Expression.

Available NumberMatch values are:

  • EQUALS: the num1 == num2 condition
  • GREATER_THAN: the num1 > num2 condition
  • GREATER_THAN_OR_EQUAL_TO: the num1 >= num2 condition
  • LESS_THAN: the num1 < num2 condition
  • LESS_THAN_OR_EQUAL_TO: the num1 <= num2 condition
  • NOT_EQUALS: the num1 != num2 condition
Notes:
See also:

RoomProperties


The RoomProperties object lists all Room properties that can be queried using a Match Expression.

Available RoomProperties fields are:

  • GROUP_ID: the id of Group to which the Room belongs
  • HAS_FREE_PLAYER_SLOTS: the Room has at least one free player slot
  • IS_GAME: the Room's isGame flag
  • IS_PRIVATE: the Room's isPrivate flag
  • IS_TYPE_SFSGAME: the Room is of type SFSGame
  • MAX_SPECTATORS: the Room's max number of spectators
  • MAX_USERS: the Room's max number of users
  • NAME: the name of the Room
  • SPECTATOR_COUNT: the number of spectators in the Room
  • USER_COUNT: the number of users in the Room
Notes:
See also:

SFSEventType


The SFSEventType object lists all server-side events dispatched to an Extension, provided an handler was registered.

Available SFSEventType fields are:

  • BUDDY_ADD: the event fired when a user is added in the Buddy List of another client
  • BUDDY_BLOCK: the event fired when a Buddy is blocked in user's Buddy List
  • BUDDY_LIST_INIT: the event fired when a user initializes his Buddy List
  • BUDDY_MESSAGE: the event fired when a Buddy Message is exchanged between two buddies
  • BUDDY_ONLINE_STATE_UPDATE: the event fired when a buddy changes his online state
  • BUDDY_REMOVE: the event fired when a user is removed in the Buddy List of another client
  • BUDDY_VARIABLES_UPDATE: the event fired when one or more Buddy Variables are set by a user
  • FILE_UPLOAD: the event fired when one or more files have been uploaded by a user connected in the current Zone
  • GAME_INVITATION_FAILURE: the event fired after a private SFSGame has finished the cycle of invitations with an error
  • GAME_INVITATION_SUCCESS: the event fired after a private SFSGame has finished the cycle of invitations successfully
  • PLAYER_TO_SPECTATOR: the event fired when a user joined in a Game Room as a player is turned into a spectator
  • PRIVATE_MESSAGE: the event fired when a private message is sent by a client
  • PUBLIC_MESSAGE: the event fired when a public message is sent by a client
  • ROOM_ADDED: the event fired after a new Room was created in the current Zone
  • ROOM_REMOVED: the event fired after a Room was removed from the current Zone
  • ROOM_VARIABLES_UPDATE: the event fired when one or more Room Variables are set
  • SERVER_READY: the event fired when SmartFoxServer has completed the boot phase
  • SPECTATOR_TO_PLAYER: the event fired when a user joined in a Game Room as a spectator is turned into a player
  • USER_DISCONNECT: the event fired after a user disconnects himself or is disconnected
  • USER_JOIN_ROOM: the event fired after a user has joined a Room
  • USER_JOIN_ZONE: the event fired after a successful user login
  • USER_LEAVE_ROOM: the event fired after a user has left a Room
  • USER_LOGIN: the event fired when a user sends a login request
  • USER_LOGOUT: the event fired after a user logged out of the current Zone
  • USER_RECONNECTION_SUCCESS: the event fired when the HRC system is active and a client was successfully reconnected (feature not available for JavaScript clients)
  • USER_RECONNECTION_TRY: the event fired when the HRC system is active and a client is trying to reconnect (feature not available for JavaScript clients)
  • USER_VARIABLES_UPDATE: the event fired when one or more User Variables are set
Notes:
See also:

SFSRoomRemoveMode


The SFSRoomRemoveMode enum lists all possible auto-removal modes of dynamically created Rooms.

Available SFSRoomRemoveMode values are:

  • DEFAULT: a regular Room is removed when it is empty and its creator is not connected anymore, while instead a game Room is removed when it is empty
  • NEVER_REMOVE: the Room is never removed (use with caution)
  • WHEN_EMPTY: the Room is removed immediately when the last user leaves it
  • WHEN_EMPTY_AND_CREATOR_IS_GONE: the Room is removed when it is empty and its creator is not connected anymore
Notes:

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:

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:
See also:

UserProperties


The UserProperties object lists all User properties that can be queried using a Match Expression.

Available UserProperties fields are:

  • IS_IN_ANY_ROOM: the user is currently joined in at least one Room
  • IS_NPC: the user is a Non-Player Charachter
  • IS_PLAYER: the user is a player in the joined Room
  • IS_SPECTATOR: the user is a spectator in the joined Room
  • NAME: the name of the user
  • PRIVILEGE_ID: the user's privilege id
Notes:
See also:

VariableType


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

Available VariableType values are:

  • NULL: a null Variable
  • BOOL: a boolean Variable
  • INT: an int Variable (32 bit integer)
  • DOUBLE: a double Variable (64 bit double precision number)
  • STRING: an utf-string Variable (UTF-8 encoded string, with length up to 32 KBytes)
  • OBJECT: a Variable of type SFSObject
  • ARRAY: a Variable of type SFSArray
Notes:

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.

See also:
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.
See also:
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:

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]);
}

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.

See also:
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.