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.
See also
- SFSApi#banUser method
-
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:
- For members of the BoolMatch enum, please refer to its Javadoc.
See also:
- MatchExpression class
- NumberMatch enum
- StringMatch enum
- EQUALS: the
-
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:
- For members of the ClientDisconnectionReason enum, please refer to its Javadoc.
See also:
- SFSEventType.USER_DISCONNECT event type
-
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:
- For members of the InvitationResponse enum, please refer to its Javadoc.
See also:
- GameApi#replyToInvitation method
-
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:
- For members of the NumberMatch enum, please refer to its Javadoc.
See also:
- MatchExpression class
- BoolMatch enum
- StringMatch enum
- EQUALS: the
-
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:
- For members of the RoomProperties object, please refer to its Javadoc.
See also:
- MatchExpression class
-
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:
- For members of the SFSEventType object, please refer to its Javadoc.
See also:
- addEventHandler method
-
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:
- 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.
See also:
- MatchExpression class
- BoolMatch enum
- NumberMatch enum
- CONTAINS: the
-
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:
- For members of the UserProperties object, please refer to its Javadoc.
See also:
- MatchExpression class
-
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:
- 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.See also:
- SFSEventType enum
- SFSEvent class
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
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
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:
- getBuddyApi method
- getGameApi method
- getMMOApi method
- getFileApi method
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, ornull
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. - 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.
-
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:
- GameApi#replyToInvitation method
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
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.