Server Side Scripting: The Server Object Model
Note:This document is aimed primarily at developers already familiar with the Multiuser Xtra, and who are comfortable with object-oriented Lingo.
This TechNote is divided into three sections:
Server-Side Scripts: A summary
The Server Object Model
Server Object Lingo descriptions
Server-Side Scripts: A summary
Server Side Scripting is a significant new feature set added to version 3.0 of the Shockwave Multiuser Server (SMUS). Because scripts can now run in a server environment, certain concepts may be difficult to grasp due to their being abstracted one level beyond the standard Director playback environment. This document aims to present one essential Server Side Scripting concept: The Server Object Model.
In brief, Server Side Scripting can roughly be divided into two main areas:
| 1 | A subset of standard Director Lingo that runs in the server environment. Supported functions, properties, and datatypes/objects can be found on page 477-478 of What's New in Director 8.5 Shockwave Studio, or on pages 37-38 of Using the Shockwave Multiuser Server and Xtra 3.0. |
| 2 | New server-specific Lingo which includes server objects, server events, multithreading support, debugging support, and file access. Since this document focuses only on server objects, please refer to the documentation for information on other new Lingo aspects. |
Server objects are one aspect of new server-specific Lingo, and can be described by the Server Object Model. When the server is launched, the server object reference is passed to Dispatcher.ls. Now, assuming Dispatcher.ls has not been altered, it will store this reference in a property called, "pServer", and will use it to communicate with the server and send messages to other users. This storage occurs within the "on initialize" function located in Dispatcher.ls. Then, when custom scripts are registered with Scriptmap.ls, Dispatcher will pass the server object references to the custom script. This allows custom Lingo to also make use of the server objects.
There are four major components of the Server Object Model:
 |
Server:A reference to the server application. |
| |
ServerMovie:A reference to a connected Director movie. Users log on to a server under a movie name. This is the same as MovieID used in client messaging. |
| |
ServerGroup:A reference to a group. Users elect to join and leave groups within a movie. |
| |
ServerUser:A reference to a connected user. Same as UserID used in client messaging. |
Each of these four server objects has a set of unique Lingo functions and properties:
Server Object hierarchy
The server objects all conform to a parent/child hierarchy. For instance, the Server object is the topmost parent, from which a ServerMovie object can be derived and stored in a property, a variable or a list. Once a reference to a ServerMovie object has been stored then it is possible to derive a ServerGroup object. Likewise, once a reference to a ServerGroup object has been stored it is possible to derive a ServerUser object.
Again, because custom script files are automatically assigned the Server object when they're registered via the ScriptMap, it is therefore possible to derive any of the script objects within custom scripts.
The following example shows one way in which object references can be derived using the server object hierarchy:
on ServerObjectTest me -- derive first ServerMovie reference from Server reference aServerMovie = server.serverMovie( 1 ) -- derive first aServerGroup reference from aServerMovie reference aServerGroup = aServerMovie.serverGroup( 1 ) -- derive first aServerUser reference from aServerGroup reference aServerUser = aServerGroup.serverUser( 1 ) put "aServer: "&server put "aServerMovie: "&aServerMovie put "aServerGroup: "&aServerGroup put "aServerUser: "&aServerUser -- the output in the server console will look like the following: -- "aServer: <Server 4 141b10>"
-- "aServerMovie: <Movie 6 1413f4>"
-- "aServerGroup: <Group 3 141340>"
-- "aServerUser: <User 8 1412f0>" end
Note:For information on how to call custom handlers within a server-side script, please refer to "Sending Custom Events to Server-Side Scripts", located in both What's New in Director 8.5 Shockwave Studio, andUsing the Shockwave Multiuser Server and Xtra 3.0.
Once an object reference has been derived and stored, it is now possible to access the object's functions and properties. For example, with a reference to the aServerUser object one can now send a message to the user via "aServerUser.sendMessage( )":
aServerUser.sendMessage( someSubjectString, "Hi!" )
Server Object Lingo descriptions
Syntax:
aServer.displayMessage( string aMessage )
Description:
Displays a message in the servers console. Can also use"put" to display to the console. "Put" adds a new line; displayMessage( ) does not.
Usage example:
aServer.displayMessage( "Hi!"& RETURN )
put "Hi!"
Syntax:
aServer.serverMovie( string aMovieName | int aMovieIndex )
Description:
Finds a ServerMovie object by name or number. Returns a reference to the ServerMovie object.
Usage example:
movieRef = aServer.serverMovie( "ChessGame" )
Syntax:
aServer.createServerMovie( string aMovieName )
Description:
Creates and returns a ServerMovie object with the given name. Takes a string argument.
Note:Movie objects created with this function will not be automatically deleted when the last user logs off. It will be necessary to explicitly delete these objects using either aServer.deleteServerMovie("MovieID") or System.Movie.Delete["movieID"].
Usage example:
aServer.createServerMovie( "CheckersGame" )
Syntax:
aServer.deleteServerMovie( string aMovieName )
Description:
Deletes and returns the name of the specified ServerMovie. Takes a string argument.
Usage example:
aServer.deleteServerMovie( "CheckersGame" )
Syntax:
aServer.serverMovieCount
Description:
Returns the number of active ServerMovie objects. Takes no arguments.
Usage example:
movieNum = aServer.serverMovieCount
Syntax:
aServer.path
Description:
Returns the file path name string for the Server Application directory. Takes no arguments.
Usage example:
serverAppPath = aServer.path
Syntax:
aServer.scriptsPath
Description:
Returns the file path name string for the server scripts directory. Takes no arguments.
Usage example:
serverScriptsPath = aServer.scriptsPath
Syntax:
aServer.timeString
Description:
Returns the server time in string format. Takes no arguments.
Usage example:
serverTime = aServer.timeString
Syntax:
aServer.timeStamp
Description:
Returns the server time expressed in integer milliseconds. Takes no arguments.
Usage example:
serverTimeStamp = aServer.timeStamp
Syntax:
aServer.language
Description:
Returns the language code for the servers Operating System. Takes no arguments.
English = 0, French = 1, German = 2, Korean = 9, Japanese = 10.
Usage example:
whichOS = aServer.language
Syntax:
aServer.userLevel
Description:
Returns integer for default user level. Takes no arguments.
Usage example:
defaultUserLevel = aServer.userLevel
Syntax:
aServer.userLevel = integer userLevel
Description:
Sets default user level.
Usage example:
aServer.userLevel = 40
Syntax:
aServerMovie.serverGroup( string groupName | int groupNumber )
Description:
Returns a reference to a ServerGroup object.
Usage example:
groupRef = aServerMovie.serverGroup( 1 )
"serverMovie.createServerGroup()":
Syntax:
aServerMovie.createServerGroup( string groupName )
Description:
Creates and returns the specified ServerGroup.
Usage example:
aServerMovie.createServerGroup( "@RedTeam" )
"serverMovie.deleteServerGroup()":
Syntax:
aServerMovie.deleteServerGroup( string groupName )
Description:
Deletes and returns the name of the specified ServerGroup.
Usage example:
aServerMovie.deleteServerGroup( "@MusicChat" )
Syntax:
aServerMovie.sendMessage( string recipient | [ string recipient... string recipientN ], string subject, contents {,protocolFlag}{, errorCode} {, string senderID} )
Description:
Sends a message from within a server-side script to the specified movie, group, or user.
Whensending messages to a movie, the protocolFlag, errorCode, and stringSenderID are optional, but when used must be appear together and in the correct order. The protocolFlag is intended for future enhancements to the server and should be set to FALSE.
When sending a message to a user with the third syntax shown, the recipient parameter is omitted, since the specified user is the recipient.
The subject must begin with "system.script." to ensure that responses to the message are sent back to the server-side script.
Usage example:
errCode = aServerMovie.sendMessage \
( "Chris", "system.script.movePiece", ["Rook", 3, 0], 0, FALSE, "John" )
"serverMovie.serverGroupCount":
Syntax:
aServerMovie.serverGroupCount
Description:
Returns the number of ServerGroups in aServerMovie. Takes no arguments.
Usage example:
groupNum = aServerMovie.serverGroupCount
"serverMovie.serverUserCount":
Syntax:
aServerMovie.serverUserCount
Description:
Returns the number of ServerUsers in aServerMovie. Takes no arguments.
Usage example:
userNum = aServerMovie.serverUserCount
Syntax:
aServerMovie.name
Description:
Returns the name in string format of this movie.
Usage example:
movieName = aServerMovie.name
Syntax:
aServerMovie.userLevel
Description:
Returns the default userLevel for the movie. Takes no arguments.
Usage example:
defaultUserLevel = aServerMovie.userLevel
Syntax:
aServerMovie.userLevel = integer userLevel
Description:
Sets the default userLevel for the movie.
Usage example:
aServerMovie.userLevel = 60
Syntax:
aServerGroup.serverUser( string userName | int userNumber )
Description:
Find a ServerUser by name or number. Returns a reference to the ServerUser object.
Usage example:
userRef = aServerGroup.serverUser( "ModeMan" )
Syntax:
aServerGroup.addUser( aServerUserObject ServerUser )
Description:
Add a user to a group.
Usage example:
aServerGroup.addUser( aServerUser )
Syntax:
aServerGroup.removeUser( aServerUserObject ServerUser )
Description:
Remove a user from a group.
Usage example:
aServerGroup.removeUser( aServerUser )
Syntax:
aServerGroup.sendMessage( string subject, contents, {errCode}, {,protocolFlag} {, errorCode} {, string senderID} )
Description:
Sends a message from within a server-side script to the specified movie, group, or user.
When sending messages to a movie, the protocolFlag, errorCode, and stringSenderID are optional, but when used must be appear together and in the correct order. The protocolFlag is intended for future enhancements to the server and should be set to FALSE.
When sending a message to a user with the third syntax shown, the recipient parameter is omitted, since the specified user is the recipient.
The subject must begin with "system.script." to ensure that responses to the message are sent back to the server-side script.
Usage example:
errCode = aServerGroup.sendMessage \
( "Chris", "system.script.movePiece", ["Rook", 3, 0], 0, FALSE, "John" )
"serverGroup.serverUserCount":
Syntax:
aServerGroup.serverUserCount
Description:
Returns the number of users in the group. Takes no arguments.
Usage example:
userNum = aServerGroup.serverUserCount
Syntax:
aServerGroup.name
Description:
Returns the name in string format of this ServerGroup.
Usage example:
groupName = aServerGroup.name
Syntax:
aServerGroup.persists
Description:
Returns the persists setting for the group.
Usage example:
groupPersists = aServerGroup.persists
Syntax:
aServerGroup.persists = boolean persists
Description:
Set the persists property of the group. A setting of TRUE means the group will not be automatically deleted with the last user leaves the group.
Usage example:
aServerGroup.persists = FALSE
Syntax:
aServerGroup.userLimit
Description:
Returns the user limit for the ServerGroup.
Usage example:
userLimit = aServerGroup.userLimit
Syntax:
aServerGroup.userLimit = integer userLimit
Description:
Set the user limit for the group.
Usage example:
aServerGroup.userLimit = 10
Syntax:
aServerUser.sendMessage (string subject, msgContents, {, errorCode} {, senderName} )
Description:
Sends Message to the ServerUser.
Usage example:
aServerUser.sendMessage \
( "system.script.movePiece", ["Rook", 3, 0], 0, FALSE, "John" )
Syntax:
aServerUser.userLevel
Description:
Returns the userLevel of this serverUser.
Usage example:
levelOfUser = aServerUser.userLevel
Syntax:
aServerUser.userLevel = integer userLevel
Description:
Set the userLevel for this serverUser.
Usage example:
aServerUser.userLevel = 40
Syntax:
aServerUser.name
Description:
Returns the name in string format of the serverUser.
Usage example:
userName = aServerUser.name
Syntax:
aServerUser.creationTime
Description:
Returns the integer server time of the user logon.
Usage example:
creationTime = aServerUser.creationTime
Syntax:
aServerUser.ipAddress
Description:
Returns the IP Address of the user.
Usage example:
userIPAddress = aServerUser.ipAddress
Syntax:
aServerUser.serverMovie
Description:
Returns a reference to the ServerMovie object associated with the user.
Usage example:
whichMovie = aServerUser.serverMovie
This content requires Flash
To view this content, JavaScript must be enabled, and you need the latest version of the Adobe Flash Player.
Download the free Flash Player now!
