ElectroServer 3.0 (AS 2.0) Documentation
Table Of Contents
Table Of ContentsAuthor: Jobe Makar
Last Modified: 2004/10/15
Generator: gModeler.com.
ElectroServer 3.0 (AS 2.0) Overview
No documentation available.
No documentation available.
ElectroServer 3.0 Nested Elements
ElectroServerAvailability
Flash Player 6.
Usage
var es:ElectroServer = ElectroServer.getInstance()
Parameters
None.
Returns
Nothing.
Description
The ElectroServer class eases communication between Flash clients and ElectroServer (the socket server).
The ElectroServer class is a 'static' class, also known as a singleton. This means that only 1 instance of the class can exist. To create that instance you simply call the static method 'getInstance()' on the ElectroServer class, and a reference is returned.
var es:ElectroServer = ElectroServer.getInstance();
Then you can access everything available to the ElectroServer class through the 'es' reference.
Explanation for beginners
ElectroServer is a socket-server, a piece of software written in Java that resides on a remote server somewhere (or your own personal computer for testing). When the ElectroServer software is started (see ElectroServer documentation for that) it "binds" itself to a specific IP address and "listens" for communication requests over a specific port.
The connect() method is used to establish a connection with ElectroServer. By specifying the IP address and port that ElectroServer uses you can connect to it from Flash. This connection is called a persistent connection. It is persistent because the connection exists until it is closed by the Flash client, the server, or by killing the Flash client (leaving the web page).
While this connection exists data can be passed from the Flash client to the server or from the server to the Flash client without either side requesting the data. This data is intercepted and used by making use of many of the various methods and events of the ElectroServer object.
If you are truly a beginner and are having trouble understanding all of this, then please take a look at some open-source FLA examples that use the ElectroServer object.
Using the ElectroServer object is really pretty simple. Taking a look at a very basic source file can help immensely.
Example
The code below first creates the needed single instance of the ElectroServer class. It then tells the class which IP to look for ElectroServer, and on which port to communicate. The final line of ActionScript below tells the ElectroServer class to connect to the ElectroServer socket server.var es:ElectroServer = ElectroServer.getInstance();
es.setIP("127.0.0.1");
es.setPort(9875);
es.connect();
ElectroServer Properties
isConnected :
Availability
Flash Player 6.
Usage
ElectroServer.isConnected
Description
Returns true if this instance of the ElectroServer object is currently connected to ElectroServer, and false if it is not.
Example
Ifes is the reference to your instance of the ElectroServer object, thenvar connected:Boolean = es.isConnected
password :
Availability
Flash Player 6.
Usage
ElectroServer.password
Description
Returns your password if one was used during login.
Example
var myPassword:String = es.password;
username :
Availability
Flash Player 6.
Usage
ElectroServer.username
Description
Reference to the username that you specified at login.
Example
var myUsername:String = es.username;
ElectroServer Methods
addBuddy :
Availability
Flash Player 6.
Usage
ElectroServer.addBuddy(username)
Parameters
username Username of buddy to add (String)
Returns
Nothing.
Description
ElectroServer 3.6 and above supports the idea of "buddies". You can add a buddy to your buddy list. You are told when ever a buddy of yours logs into the server or logs out of the server.
The moment you add a buddy to your list you are informed if that buddy is logged in or not.
You can add a buddy by simply calling the addBuddy method and passing in any username.
See also removeBuddy, buddyLoggedIn, buddyLoggedOut, getBuddyList
Example
es.addBuddy("jobem");
adminLogin :
Availability
Flash Player 6.
Usage
ElectroServer.adminLogin(username,password)
Parameters
username The username of the admin (String)
password The password of the admin (String)
Returns
Nothing.
Description
This method is exactly the same as the login() method except that it informs the server that this user is trying to login as an administrator. There is only 1 administrator per instance of ElectroServer.
Administrators, once logged in, have a greater level of access than do users or moderators.
Example
es.adminLogin("system", "electroserver");
ban :
Availability
Flash Player 6.
Usage
ElectroServer.ban(username,reason,time)
Parameters
username The username of the person to be banned (String)
reason The reason why this user is being banned (String)
time The length of time to be banned (Number or String)
Returns
Nothing.
Description
Kicks a user from the server and bans them from logging in again. The 'time' parameter is the length of time in minutes that a user should be banned from the server. If "-1" then the user is banned until the the server is restarted.
Example
The following bans someone for 20 minutes.
es.ban("jobem", "You have repeatedly been mean.", 20);
changeRoomDetail :
Availability
Flash Player 6.
Usage
ElectroServer.changeRoomDetail(detail,value)
Parameters
detail The name of the attribute to change (String)
value The value to assign the updated attribute (Varies)
Returns
Nothing.
Description
Change attributes of the room that you are currently in.
Acceptable 'details' are:
'description', The value is an object (just like in createRoom and createGame). The properties of the object are description and attributes. Attributes is another object that can hold any number of custom variables.
'updatable', The value is true or false. If true, then the room will receive updates about the zone. If false then it will receive no updates accept regarding itself.
'hidden', The value is true or false. If true then the room is not seen by any other room. If false then the room is seen by other rooms within the zone.
'capacity', The value is a number. This changes the max capacity fo the room. If the value is -1 then there is no limit.
'password', The value is a string or blank. If blank then the room is switched to having no password. If not blank then the password of the room is changed to the new value.
Example
Changes the password of your room:
es.changeRoomDetail("password", "myNewPass");
Changes the description object,
var ob:Object = new Object();
ob.attributes = new Object();
ob.description = "A cool room";
ob.attributes.some_useful_variable = "asdf";
es.changeRoomDetails("description", ob);
Makes a room hidden,
es.changeRoomDetail("hidden", true);
close :
Availability
Flash Player 6.
Usage
ElectroServer.close()
Parameters
None.
Returns
Nothing.
Description
Closes the connection to ElectroServer.
Example
es.close()
connect :
Availability
Flash Player 6.
Usage
ElectroServer.connect(ip,Port)
Parameters
ip The ip address of ElectroServer (String)
port The port on which ElectroServer is listening (String)
Returns
Nothing.
Description
Creates a socket connection with ElectroServer using the ip and port passed in. Alternatively, the ip and port can be set using the setIP() and setPort() methods and left blank in this method.
Explanation for beginners
Note: this explanation is also seen in the documentation for the ElectroServer constructor.
ElectroServer is a socket-server, a piece of software written in Java that resides on a remote server somewhere (or your own personal computer for testing). When the ElectroServer software is started (see ElectroServer documentation for that) it "binds" itself to a specific IP address and "listens" for communication requests over a specific port.
The connect() method is used to establish a connection with ElectroServer. By specifying the IP address and port that ElectroServer uses you can connect to it. This connection is called a persistent connection. It is persistent because the connection exists until it is closed by the Flash client, the server, or by killing the Flash client (leaving the web page).
While this connection exists data can be passed from the Flash client to the server or from the server to the Flash client without either side requesting the data. This data is intercepted and used by making use of many of the various methods and events of the ElectroServer object.
If you are truly a beginner and are having trouble understanding all of this, then please take a look at some open-source FLA examples that use the ElectroServer object.
Example
var es:ElectroServer = ElectroServer.getInstance()
var ip:String = "127.0.0.1";
var port:Number = 9090;
es.connect(ip, port);
var es:ElectroServer = ElectroServer.getInstance()
es.setIP("127.0.0.1");
es.setPort(9090);
es.connect();
createGameRoom :
Availability
Flash Player 6.
Usage
ElectroServer.createGameRoom(roomOb)
Parameters
roomOb Object describing room to be created (Object)
Returns
Nothing.
Description
Creates a room for a game. This method accepts an object with exactly the same properties as the createRoom method does. Please see that method for full details.
The flag that shows that this room is a game room is found in the room object as: roomOb.description.attributes.isGameRoom, and has a value of 'true'.
Note: The createGameRoom method differs from the creatRoom method only because it flags the room as being a game room. When the room is created, modified, or removed, the same events are fired as with a regular room. By flagging a room as a game room it is easier to show a difference in the room list.
Example
createRoom :
Availability
Flash Player 6.
Usage
ElectroServer.createRoom(Room_object)
Parameters
Room_object Object containing all of the room attributes (Object). See below for the possible parameters.
Properties of Room_Object
The room_object object can contain many properties for custom rooms. Some of them are required while others are not.
password If blank the room is not password protected. If it contains anything then the room is password protected.
UserVariablesEnabled If blank or 'false' then user variables are not enabled for this room (increases performance). If 'true', then user variables are enabled for the room. See createUserVariable, login, or userVariableUpdated for more information.
hidden If blank or 'false' then the room is not hidden. If 'true', then the room is hidden and cannot be seen by the other rooms in your zone. This is often used for game rooms.
zone This is the zone in which you want to create a room. If the zone does not yet exist then it will be created. Required.
roomName The name of the room to be created. Required.
numbered If blank or 'false' the room does not number its users. If 'true' then it does. See the usersRenumbered event.
capacity If blank or -1 then the room has no maximum size. If the number is greater than 0 then the room created can only grow to a certain user size.
description Can be left blank or be a string describing the room.
updatable If blank or 'true' then the room is updatable. If 'false' then it is not. A room that is updatable receives zone updates and roomList updates. If it is not updatable then it only receives updates regarding itself (userListUpdates, etc). This increases performance for that room, recommended for games.
roomVariables Can be left blank if you don't want to create a room with room variables. This is an array of objects, each of which describes a room variable. The properties of a room variable are 'name' (name of variable), 'data' (value of variable), 'persistent' (optional Boolean), 'locked' (optional Boolean). Room variables can be created using the createRoomVariable() method. See that method for more details.
attributes Optional property. This is an object that can contain variables or arrays. It is attached to the room much like the room description is. This means that it is accessible by people in other rooms.
plugins Optional property. ElectroServer 3 supports the ability to use server-side plugins. You can access custom-written ActionScript or Java plugins from Flash on the server. But in order to access them they must b instantiated when creating a room. This property is an array of objects. Each object represents a plugin that you want to instantiate for the room. The 'name' variable on that object is the name of the plugin. The object can contain another object called 'variables' if you want to pass variables into the plugin. Using plugins is an advanced feature that requires a moderate level of understanding of ElectroServer and the ElectroServer object.
Returns
Nothing.
Description
Creates a room in a specific zone and then joins you to that room. See the above section for description of each of the configurable properties of a room.
Note: If you attempt to create a room that already exists then internally the ElectroServer object will receive an error and you will automatically be joined to that room (since it exists).
Example
Here is a long-winded example of creating a room with all properties used:
var roomOb:Object = new Object();
roomOb.zone = "Chat Area";
roomOb.roomName = "Lobby";
roomOb.hidden = false;
roomOb.numbered = false;
roomOb.UserVariablesEnabled = false;
roomOb.Description = "You can chat all day long in this room!";
roomOb.password = "";
roomOb.Capacity = -1;
roomOb.updatable = true;
//room vars
roomOb.roomVariables = new Array();
var ob:Object = new Object();
ob.name = "BackgroundMusic";
ob.data = "AmbientSounds";
roomOb.roomVariables.push(ob);
//end room vars
es.createRoom(roomOb);
createRoomVariable :
Availability
Flash Player 6.
Usage
ElectroServer.createRoomVariable(variable_object)
Parameters
variable_object An object that contains the properties of the room variable.
Properties of variable_object
name The name of the room variable to be created or updated. (String)
data The value of the room variable to be created or updated. (String)
locked Optional property. If true then the variable can not be modified once created in the room, however it can still be deleted. The default value is false. (Boolean)
persistent Optional property. If true then the variable remains in the room after the user that created it leaves the room. If false then the variable is deleted when the user who created it leaves the room. The default value is false. (Boolean)
Returns
Nothing.
Description
Creates or updates a variable in the room on the chat server. The variable can be flagged as locked and/or persistent.
Deeper explanation
ElectroServer supports room variables. This means that a Flash client can create a variable at the room level that is actually stored in ElectroServer. While ElectroServer is the 'master' of all of these room variables, each Flash client knows about all of the room variables as well. When ever a room variable is created, modified, or deleted, every user in that room is notified and the ElectroServer object updates this information internally.
When room variables are created, modified, or deleted an event in the ElectroServer object called 'roomVariablesUpdated' is fired. See that event for more information. The room variables can be accessed at any time by using the 'getRoomVariables()' method.
Room variables can be created and then modified. A room variable can be created and locked so that it cannot be modified any more (but can still be deleted). And a room variable can be flagged as persistent, which means that it is not automatically deleted when the user that created it leaves the room.
Why room variables are useful
With room variables you have a centralized location to store data. If, for instance, you wanted to create an avatar chat where chracters could walk around and chat, then room variables can help in the following way:
For each user in the room you can create a room variable that stores his position and the type of character that he is using. Then when someone new joins the room their Flash client just uses the room variables to determine where to place the avatar characters. Everytime someone moves their avatar character then they send a room variable update to update its postion on the server.
Without room variables the way that the above would be accomplished would be by sending information separately to everyone in the room round-robin style. This is not good practice, causes synchronization issues, and uses more bandwidth.
Here are two good examples of persistent room variables (meaning that they do not delete when the user that created them leaves the room):
1.) A Flash white board. You can use persistent room variables to store the drawings. Then as people leave and new people come into the white board they can see everything.
2.) For a multiplayer game you can build something in the world or leave something behind (like scorch marks form an explosion). When you leave the variable remains and so everyone can see your contribution.
Here is a good example of a locked room variable:
Let's say you wanted to create a scavenger hunt game. This game has several people in it and there are say, 10 objects to collect. You can collect one by moving your character to the object and pushing a special key. Well, what if two people reach the same object at the same time? How do you know who actually collected it? There is no way to do this without server-side help, like locked room variables.
If your username is "jobem" and you collect a "gold cup" then you can set a locked user variable into the room called:
goldCup = "jobem"
When everyone receives this room variable update they can flag that object as collected. If someone tries to collect the object in that 100 or so miliseconds of Internet latency then they will still fail because they will not be able to create the room variable as it is already locked!
To 'clean up' the game to start over you would then have to delete each of those room variables.
Example
The following code creates a room variable on the server in your current room. The variable is not locked and will be removed when you leave the room,
var ob = new Object();
ob.name = "NumberOfBadGuys";
ob.data = "30";
es.createRoomVariable(ob);
The following code creates a room variable on the server in your current room. This variable is locked, meaning that it cannot be modifed (only deleted). It is also persistent, which means it will not die if you leave the room,
var ob = new Object();
ob.name = "secretDoorUnlocked";
ob.data = "true";
ob.locked = true;
ob.persistent = true;
es.createRoomVariable(ob);
createUserVariable :
Availability
Flash Player 6.
Usage
ElectroServer.createUserVariable(name,value)
Parameters
name Variable name (String)
value Variable string value (String)
Returns
Nothing.
Description
Creates a variable stored on the server associated with the user that created it. As the user moves from room to room the variable comes with him. When the user enters a room or when any uservariable is created, removed, or modified, all users in that room are notified of the change.
Example
es.createUserVariable("myIcon", "happy face");
deleteUserVariable :
Availability
Flash Player 6.
Usage
ElectroServer.deleteUserVariable(name)
Parameters
name Name of variable to delete (String)
Returns
Nothing.
Description
Removes a uservariable associated with the user that makes the call.
Example
es.deleteUserVariable("myIcon");
getAllZones :
Availability
Flash Player 6.
Usage
ElectroServer.getAllZones()
Parameters
None.
Returns
Nothing.
Description
This method loads the list of all zones on the server. See also the allZonesLoaded event.
Example
es.getAllZones();
es.allZonesLoaded = function(zones) {
//This is called when all zone names have been loaded
for (var i = 0; i
trace(zones[i]);
}
};
getBuddyList :
Availability
Flash Player 6.
Usage
ElectroServer.getBuddyList()
Parameters
None.
Returns
Array of objects, each representing a buddy.
Description
This returns the list of your buddies as an array. Each element in the array is an object that has the following properties:
username - name of the buddy
isOnline - Boolean (true for online)
ob.status - String (offline or online)
ob.label - Matches the username. For use with list box component
See also addBuddy, removeBuddy, buddyLoggedIn, buddyLoggedOut
Example
var myBuddies = es.getBuddyList();
getIP :
Availability
Flash Player 6.
Usage
ElectroServer.getIP()
Parameters
None.
Returns
The ip address of ElectroServer
Description
Gives you the ip address that is stored in your instance of the ElectroServer object. The ip address was created in your instance of the ElectroServer object by either passing it in to the connect() method or by using the setIP() method.
Example
var myIP:String = es.getIP();
getPort :
Availability
Flash Player 6.
Usage
ElectroServer.getPort()
Parameters
None.
Returns
The port that is being used to communicate with ElectroServer.
Description
This method returns the port that is being used to communicate with ElectroServer. This port was set by passing it in with the connect() method or by calling the setPort() method.
Example
var myPort:Number = es.getPort();
getRoom :
Availability
Flash Player 6.
Usage
ElectroServer.getRoom()
Parameters
None.
Returns
Room object that describes the room that you are in.
Properties of the room object
Here are the properties of the room object:
name.value The name of the room
description.value The room description if there is one.
attributes (an object containing the following room properties):
attributes.users The number of users in the room
attributes.maxCapacity The maximum number of users allowed in this room. '-1' means there is no limit.
attributes.IsPasswordProtected A boolean value specifying if the room requires a password to enter.
roomVariables (an object containing the all of the variables that are stored in the room on the server):
Each variable stored in this object has its own unique name. They can be accessed by using a 'for in' loop on the object. See getRoomVariables()
Description
Returns the room object that describes your room. This object contains information about your room such as its name, number of users in it, if it is password protected, its maximum capacity, and all of the room variables.
Note: Room variables are stored and maintained on the server, but are replicated in the Flash client. When ever the serve makes a room variable modification then all Flash clients in that room are notified and the change is updated locally. See the 'roomVariableUpdated' event for more information as well as the 'getRoomVariables()' method.
Example
var myRoomName:String = es.getRoom().name.value
getRoomList :
Availability
Flash Player 6.
Usage
ElectroServer.getRoomList()
Parameters
None.
Returns
An array. Each element in the array is an object.
Properties of each room object
Each element in the room list array is an object describing a room. Here are the properties of a room object:
name.value The name of the room
description.value The room description if there is one.
attributes (an object containing the following room properties):
attributes.users The number of users in the room
attributes.maxCapacity The maximum number of users allowed in this room. '-1' means there is no limit.
attributes.IsPasswordProtected A boolean value specifying if the room requires a password to enter.
Description
Returns the list of rooms in your zone as an array. Each element in the array in an object describing a room. From each element you gain information about a room such as its name, description, number of users, maximum number of users allowed, and if the room is password protected.
Note: A zone is a collection of rooms like a room is a collection of users. A user can be in only 1 room. A room can be in only 1 zone.
Example
The code that follows is a simple way to just display the rooms in your current zone in an HTML enabled text filed. Note: this does not make use of the the other properties of the room objects.function showRooms() {
roomListBoxStr = "";
var roomlist:Array = es.getRoomList();
for (var i = 0; i<roomlist.length; ++i) {
var room:Object = roomlist[i];
roomListBoxStr += room.name.value+"< br >";
}
roomListBox.htmlText = roomListBoxStr;
}
getRoomsInZone :
Availability
Flash Player 6.
Usage
ElectroServer.getRoomsInZone(zone)
Parameters
zone Name of zone (String)
Returns
Nothing.
Description
A zone is a collection of rooms. Every room is in one zone or another, no room can exist outside of a zone. This method allows you to load the list of every room in the zone.
When the list is loaded onRoomsInZoneLoaded is fired. See onRoomsInZoneLoaded event for more information.
Example
es.getRoomsInZone("Chat Area");
es.onRoomsInZoneLoaded = function(room_list, zone_name) {
//This is fired when the rooms have been loaded
//tracing zone name
trace(zone_name);
for (var i = 0; i
//tracing room name
trace(ob.Name.value);
}
};
getRoomVariables :
Availability
Flash Player 6.
Usage
ElectroServer.getRoomVariables()
Parameters
None.
Returns
An object. Each property in the object is a variable for that room.
Description
Returns an object whose properties are ElectroServer room variables. Each property of this object is a variable stored at the room level actually on the server. These properties can be accessed either directly (like object.myVariable) or by using a 'for...in' loop. See the example.
Example
To simply show all of the room variables for a room in the output window, use the following code:
function showRoomVariables() {
var roomVariables:Object = es.getRoomVariables();
for (var i in roomVariables) {
trace(i+"="+roomVariables[i]);
}
}
or you can access a room variable directly like the following:
var musicLoop:String = es.getRoomVariables().musicLoop
Note: 'es' is the reference to your instance of the ElectroServer object.
getUser :
Availability
Flash Player 6.
Usage
ElectroServer.getUser()
Parameters
None.
Returns
An object that describes you.
Description
Every user in the userlist has an object that contains information about that user. This method returns the object that represents you.
Example
The following returns the number associated with you in a game.
var myNum:Number = es.getUser().assignednumber.value;
getUserList :
Availability
Flash Player 6.
Usage
ElectroServer.getUserList()
Parameters
None.
Returns
An array of objects. Each object describes a user in your room.
Description
Returns an array of objects, each of which describes a user in your room. The properties of each object are 'name' which is a string, and 'moderator' which is a boolean value. If 'moderator' is true then that user is a moderator. There is also a property called 'userVariables'.
User variables are variables saved on the server and associated with a specific user. This is useful for carrying information about a user around from room to room.
Example
getUserLocation :
Availability
Flash Player 6.
Usage
ElectroServer.getUserLocation(username)
Parameters
username User whose location you need (String)
Returns
Nothing.
Description
Every user is in a zone (collection of rooms) and in a room. If you want to know the specific zone and room that a specific user is in then use this method. Pass in the user's username.
When the server sends a response the event 'userLocationLoaded' will be fired. The username, zone name, and room name will be passed in. See the documentation for userLocationLoaded.
Example
es.getUserLocation("jobem");
//Capture the response
es.userLocationLoaded = function(username, zone, room) {
trace(username+", "+zone+", "+room);
};
getUsersInRoom :
Availability
Flash Player 6.
Usage
ElectroServer.getUsersInRoom(zone,room)
Parameters
zone Name of zone that the room is in (String)
room Name of the room (String)
Returns
Nothing.
Description
You can load the current list of users in any room on the server. You must specify the zone name and the room name. Once loaded, the usersInRoomLoaded event will be fired.
See also usersInRoomLoaded.
Example
es.getUsersInRoom("Chat Area", "Lobby");
es.usersInRoomLoaded = function(users) {
//This is fired when the users in a specific room have been loaded
//array is returned with user objects. They have only 1 property, username
for (var i = 0; i
trace(ob.username);
}
};
getZone :
Availability
Flash Player 6.
Usage
ElectroServer.getZone()
Parameters
None.
Returns
An object representing the zone that you are in.
Description
Returns an object representing your current zone. This object has the following properties:
numUsers - This is number of people in your zone.
name - This is the name of the zone that you are in.
A zone is a collection of rooms much like a room is a collection of users. A user can be in only 1 room and a room can be in only 1 zone. When in a zone you do not have any information about any of the other zones, including the number of people in them or the rooms in them.
Example
var usersInMyZone:Number = es.getZone().numUsers;
var myZoneName:String = es.getZone().name
joinGame :
Availability
Flash Player 6.
Usage
ElectroServer.joinGame(room,password,playerType,zone)
Parameters
room Name of the game room (String)
password Password to join the game room, if necessary (String)
playerType Either "player" or "spectator" (String)
zone Specify the zone. If blank then it takes your current zone (String)
Returns
Nothing.
Description
A game exists in a room. To join that game you must join that room. This method handles that for you.
If you pass in a playerType of "player" then you are joining that game to become a player. If you pass in a playerType of "spectator" then you are just there to watch.
Example
es.joinGame("Mini Golf 173", "", "player");
joinRoom :
Availability
Flash Player 6.
Usage
ElectroServer.joinRoom(room,password,zone)
Parameters
room Name of the room to join (String)
password Password for room, if needed (String)
zone Name of the zone that the room is in (String)
Returns
Nothing.
Description
Joins you to a room in a specified zone. You can only join a room that has already been created (unlike in ElectroServer 2). If a room has not yet been created then you must first create it using the createRoom method, and then ElectroServer will automatically join you to that room.
The password parameter can be left blank or can be "" if no password is needed. The 'zone' parameter can be left blank if you are already in a zone and the room that you are joining is in the same zone. However, if you have just logged in to the server and have not yet joined a room, then the zone must be specified.
More detail for beginners
A room is a collection of users. In a room you can see other users in your room. When in a room you cannot see users in any other rooms (you only know that they other rooms exist and you know how many people are in them). In a room you can send messages which are received by other people in that room.
Like a room is a collection of users, a zone is a collection of rooms. In a zone you can see all of the rooms in that zone, but you have no information if any other zones exist or any information about other zones.
Example
es.joinRoom("Lobby", "", "Chat Area");
or,
es.joinRoom("SecretRoom", "secret_password", "Chat Area");
or if you are already in a zone and want to join another room in that zone with no password, then it can be condensed to this:
es.joinRoom("Game talk");
kick :
Availability
Flash Player 6.
Usage
ElectroServer.kick(username,reason)
Parameters
username The username of the person to be kicked (String)
reason The reason why the user is being kicked (String)
Returns
Nothing.
Description
Kicks another user from the server. This is only available to moderator level users. A moderator is specified by a specific username/password combination found in the configuration.xml file for ElectroServer.
Example
es.kick("jobem", "You've been bad.");
loadConfiguration :
Availability
Flash Player 6.
Usage
ElectroServer.loadConfiguration()
Parameters
None.
Returns
Nothing.
Description
Loads the configuration file for the server (only an admin can do this). Once the configuration file is loaded the configurationLoaded event is fired.
The configuration file contains all of the configurable information for ElectroServer 3. It is used by admins to configure the server. They can modify many things such as the language filter, plug-ins, and banned users.
Admin functionality is not fully documented as it is expected that you will use the provided admin client.
Example
es.loadConfiguration();
login :
Availability
Flash Player 6.
Usage
ElectroServer.login(username,password)
Parameters
username The username by which you will be known (String)
password Optional: password for server-side authentication (String)
Returns
Nothing.
Description
Before you can use any of the server functionality you must login to the server. Using this method is how that is accomplished. If ElectroServer has not been edited to accept passwords, then the password field is not required.
The password field is used by the server in one of two ways:
1) To verify that you are a moderator for the server. A moderator has extended abilities such as kick and ban.
2) The password is passed through a custom-written event for the server. This would be in place to verify login information against a database.
The login method returns nothing. However, once the server has either accepted or denied your login request the ElectroServer.loggedIn event is fired.
Example
function loginResponse(success:Boolean, error:String) {
//This function is called when the server responds after a login request is sent
if (success) {
//properly logged in
gotoAndStop("Chat")
} else {
//not properly logged in, there was an error
msg.text = error;
trace(error);
gotoAndStop("Error")
}
}
es.loggedIn =loginResponse
es.login("jobem")
pluginRequest :
Availability
Flash Player 6.
Usage
ElectroServer.pluginRequest(plugin,method,parameters)
Parameters
plugin Name of the plugin, case sensitive (String)
method Method in the plugin to be executed (String)
parameters Object containing variables to be passed in (Object)
Returns
Nothing.
Description
Sends a request to a custom-written plugin in ElectroServer. You must specify the name of the plugin and the method to be executed. The plugin accepts this information and returns a result if necessary.
ElectroServer 3.0 has the ability to accept plugins. Plugins can be written in Java or ActionScript. With ElectroServer plugins you can easily extend the functionality of ElectroServer and create applications such as multiplayer real-time games!
Example
The following could work with a plugin written to store white board data. The white board could then inform all new users to the room of the current state of the board. This code could tell the plugin to draw a line. It is then up to the plugin to send this information to the other people in the room.
var parameters:Object = new Object();
parameters.startx = 200;
parameters.endx = 300;
parameters.starty = 37;
parameters.endy = 110;
parameters.color = "blue";
es.pluginRequest("WhiteBoardScriptPlugin", "DrawLine", parameters);
removeBuddy :
Availability
Flash Player 6.
Usage
ElectroServer.removeBuddy(username)
Parameters
username Username of buddy to remove from list (String)
Returns
Nothing.
Description
Removes a buddy from your buddy list.
See also addBuddy
Example
es.removeBuddy("jobem");
sendMessage :
Availability
Flash Player 6.
Usage
ElectroServer.sendMessage(type,message,var_or_users,variables)
Parameters
type "public" or "private" (String)
message The message to be sent (String)
var_or_users List of users to be sent this message or variables (Object). If this is a "private" message then this parameter accepts an array of usernames. If this is a "public" message then this parameter accepts an object with variables.
variables Object of variables to be sent , only for "private" messages. (Object)
Returns
Nothing.
Description
Send a message to the room or to one or more specific users. With this method a message can be sent to a room (public message) or to a list of users (private message). You can send an unlimited list of variables along with any message (see example).
When a message is sent it goes to ElectroServer where it is then broadcast to the appropriate people (the room or private users). When the message is received by these users the messageReceived event is fired. See the messageReceived event for more information.
Note: The variables parameter to this method is optional.
Note: Private messages can be sent to a user anywhere on the server. Each user has a unique username (you can't have two "john" users at the same time). So when you send a private message to "john" it will find him in any room in any zone.
Example
Here is the most simple example of sending a message to a room:
var message:String = "Hello world!";
es.sendMessage("public", message);
Here is a simple of example of how to send a message to a room with variables:
var message:String = "Hello world!";
var variables:Object = new Object();
variables.textColor = "yellow";
variables.soundToPlay = "boink";
es.sendMessage("public", message, variables)
Here is a simple example of how to send a private message to three people with variables:
var message:String = "Hello world!";
var variables:Object = new Object();
variables.textColor = "yellow";
variables.soundToPlay = "boink";
var users:Array = new Array();
users.push("Kelly");
users.push("Robert");
users.push("Mike");
es.sendMessage("private", message, users, variables);
sendMove :
Availability
Flash Player 6.
Usage
ElectroServer.sendMove(who,object)
Parameters
who "all" or "public" to send to room, or an array of usernames to send to specific users (String or Array)
object An ActionScript object to send (Object)
Returns
Nothing.
Description
Sends a game move to the room or to one or more specific users. Using the sendMove method you actually send an ActionScript object to the room or to specific users. The object is serialized using the WDDX protocol, sent to the user, deserialized, and used.
When the user receives the object the moveReceived event is fired.
Note: The WDDX serialization ActionScript is courtesy of Branden Hall.
Example
Here is a simple example of how to send a chess move to another user.
var ob:Object = new Object();
ob.action = "move_piece";
ob.piece = "white_queen";
ob.y_tile = 7;
ob.x_tile = 6;
es.sendMove("all", ob);
Here is an example of how you could send an array to everyone in your roomw.
var ob:Object = new Object();
ob.action = "ListOfFriends";
ob.friends = new Array ("Jobe", "Mike", "Robert", "Kelly");
es.sendMove("all", ob);
What follows is an example of a private game move that is send to only 1 other person. You are giving that person some ammo.
var ob:Object = new Object();
ob.action = "GiveAmmo";
ob.ammoType = "Uzi";
es.sendMove("mike", ob);
setDebug :
Availability
Flash Player 6.
Usage
ElectroServer.setDebug(true_false)
Parameters
true_false true or false (Boolean)
Returns
Nothing.
Description
If you pass in true then all XML messages sent or received will be traced. If false, then none are traced.
Example
es.setDebug(true)
setIP :
Availability
Flash Player 6.
Usage
ElectroServer.setIP(ip)
Parameters
ip IP address of ElectroServer. (String)
Returns
Nothing.
Description
Sets the ip address of ElectroServer. When ElectroServer 3 is started (on a physical server somewhere or on your local machine) it binds to a specific IP address. You must specify this IP address and the port in order to connect to ElectroServer.
The IP address of ElectroServer can be specified by using this method or by using the connect() method. See the connect method for more information.
Example
var es:ElectroServer = ElectroServer.getInstance();
es.setIP("127.0.0.1");
es.setPort("8080");
es.connect();
setPort :
No documentation available.
ElectroServer Events
allZonesLoaded :
Availability
Flash Player 6.
Usage
ElectroServer.allZonesLoaded(zones)
Parameters
zones List of zone names (Array)
Returns
Nothing.
Description
This event is fired when the list of all zones on the server is loaded. An array of zone names is passed in. See also getAllZones.
Example
es.getAllZones();
es.allZonesLoaded = function(zones) {
//This is called when all zone names have been loaded
for (var i = 0; i
trace(zones[i]);
}
};
buddyLoggedIn :
Availability
Flash Player 6.
Usage
ElectroServer.buddyLoggedIn(username)
Parameters
username Name of buddy who just logged in (String)
Returns
Nothing.
Description
This is fired as a result of one of two events:
1) That buddy just logged into the server
2) That buddy was already logged into the server but you just added him to your buddy list. The server fires this event so that you are updated to know that the buddy you just added is logged in.
Example
es.buddyLoggedIn = function(name) {
//This is fired when a buddy of yours logs in
trace(name +" just logged in")
};
buddyLoggedOut :
Availability
Flash Player 6.
Usage
ElectroServer.buddyLoggedOut(username)
Parameters
username Name of buddy that just logged out (String)
Returns
Nothing.
Description
This is fired as a result of one of two events:
1) That buddy just logged out of the server
2) That buddy was already logged out of the server but you just added him to your buddy list. The server fires this event so that you are updated to know that the buddy you just added is not online.
Example
es.buddyLoggedOut = function(name) {
//this is called when a buddy of yours logs out
trace(name+" just logged out");
};
configurationLoaded :
Availability
Flash Player 6.
Usage
ElectroServer.configurationLoaded()
Parameters
None.
Returns
Nothing.
Description
Event fired when the configuration file has finished loading. The configuration XML file is passed into the callback function. See the provided admin client for example usage.
Example
connectionClosed :
Availability
Flash Player 6.
Usage
ElectroServer.connectionClosed(ServerInitiated)
Parameters
ServerInitiated ServerInitiated parameter.
Returns
Nothing.
Description
Event fired when connection to the server is lost. If 'true' then the connection was closed due to forces out side of the Flash client (like ElectroServer closing it or a broken Internet connection). If 'false' then the connection closed because the ElectroServer.close() method was invoked. (Boolean)
Example
function serverClosed(ServerInitiated:Boolean) {
if (ServerInitiated) {
trace("Connction closed by server");
} else {
trace("Connction closed by Flash");
}
}
es.connectionClosed = serverClosed;
loggedIn :
Availability
Flash Player 6.
Usage
ElectroServer.loggedIn(success,error)
Parameters
success 'true' if successfull, 'false' otherwise (Boolean)
error If failed to login this contains the error (String)
Returns
Nothing.
Description
When a login response is received from ElectroServer this is fired
Example
function loggedIn(success:Boolean, error:String) {
if (success) {
//properly logged in
gotoAndStop("Chat");
} else {
//not properly logged in, there was an error
msg.text = error;
trace(error);
gotoAndStop("Error");
}
}
es.loggedIn = loggedIn;
es.login("jobem");
messageReceived :
Availability
Flash Player 6.
Usage
ElectroServer.messageReceived(type,message,from,variables)
Parameters
type Either "public" or "private" (String)
message The message received (String)
from The name of the user that sent the message (String)
variables An object containing the message variables sent, if any (Object)
Returns
Nothing.
Description
Event fired when a public or private message is received.
Example
function gotMessage(type:String, message:String, from:String) {
if (type == "public") {
chatHistory += from+": "+message+"
";
} else if (tyep == "private") {
showPrivateMessagePopUp(message, from);
}
}
es.messageReceived = gotMessage;
moveReceived :
Availability
Flash Player 6.
Usage
ElectroServer.moveReceived(type,object,from)
Parameters
type Either "public" or "private" (Object)
object An object sent to you (Object)
from The name of the user that sent the move (Object)
Returns
Nothing.
Description
Event fired when a move is received. You can send and receive actual ActionScript objects using sendMove and moveRecieved. This makes creating multiplayer games much simpler.
Example
The following is an example of a move that could be seen in a game where characters can jump and shoot.
function moveReceived(type:String, ob:Object, from:String) {
if (type == "private") {
var action:String = ob.action;
if (action == "shoot") {
var x:Number = ob.x;
var y:Number = ob.y;
var angle:Number = ob.angle;
var speed:Number = ob.speed;
createProjectile(x, y, angle, speed);
} else if (action == "jump") {
makeOpponentJump();
}
}
}
es.moveReceived = moveReceived;
onConnection :
Availability
Flash Player 6.
Usage
ElectroServer.onConnection(success,error)
Parameters
success 'true' if successfull, 'false' otherwise (Boolean)
error If the connection is not a success then this field contains the reason why (String)
Returns
Nothing.
Description
Event fired when a connection is accepted or declined by the server.
Example
function weAreConnected(success:Boolean, error:String) {
if (success) {
gotoAndStop("Login");
} else {
msg.text = error;
trace(error);
gotoAndStop("Error");
}
}
es.onConnection = weAreConnected;
onRoomsInZoneLoaded :
Usage
ElectroServer.onRoomsInZoneLoaded(roomList,zone)
Parameters
roomList List of rooms (Array)
zone Name of zone (String)
Returns
Nothing.
Description
This event is fired when the list of rooms in a zone is loaded. The list of rooms is passed in as the first parameter (see example for accessing the room names off of those room objects). The second parameter is the name of the zone.
See also getRoomsInZone.
Example
es.getRoomsInZone("Chat Area");
es.onRoomsInZoneLoaded = function(room_list, zone_name) {
//This is fired when the rooms have been loaded
//tracing zone name
trace(zone_name);
for (var i = 0; i
//tracing room name
trace(ob.Name.value);
}
};
pluginMessageReceived :
Availability
Flash Player 6.
Usage
ElectroServer.pluginMessageReceived(plugin,action,ob)
Parameters
plugin The name of the plugin that sent the message (String)
action Action that the plugin wants you to take (String)
variables Object holding variables sent by the plugin (Object)
Returns
Nothing.
Description
Event fired when Flash receives a message from a plugin.
ElectroServer 3 has the ability to run custom-written plugins written using either Java or ActionScript. These plugins can send messages to individual users or to a room. When a message is received by a Flash client from a plugin, the name of the plugin is passed in. Also, an action name is passed in. This can be something like "CreateMonster". The plugin can also send an unlimited number of variables, which are found in the variables parameter.
See example.
Note: Please read ElectroServer 3 documentation on writing server plugins.
Example
What follows is a snippet of code that could be straight out of a real-time RPG controlled by a server-side plugin
function pluginMessageReceived(plugin:String, action:String, variables:Object) {
if (plugin == "RPG_Monster_Generator_Plugin") {
if (action == "Spawn_New_Bad_Guy") {
var badGuyType = variables.badGuyType;
var x:Number = variables.x;
var y:Number = variables.y;
var armor:String = variables.armor;
var speed:Number = variables.speed;
var ferocity:Number = variables.ferocity;
addNewBadGuyToMap(x, y, badGuyType, armor, speed, ferocity);
} else if (action == "Picked_Up_Item") {
var item:String = variables.item;
var worth:Number = variables.worth;
addItemToInventory(item, worth);
}
}
}
es.pluginMessageReceived = pluginMessageReceived;
rawMessageReceived :
Availability
Flash Player 6.
Usage
ElectroServer.rawMessageReceived(message)
Parameters
message Raw message as a string (String)
Returns
Nothing.
Description
This is used by advanced users. Server-side plug-ins can be used to send messages of any format to a user. If the message is not of the typical ElectroServer XML protocol then this event is fired and the raw message is passed through.
This is mainly used for sending extremely condensed messages for real-time games.
Example
es.rawMessageReceived = function(message) {
trace(message);
}
roomJoined :
Availability
Flash Player 6.
Usage
ElectroServer.roomJoined(success_object,myRoom)
Parameters
success_object An ojbect containing 'success' boolean of true or false, and an 'error' property if needed (Object)
myRoom A reference to the object describing your room (Object)
Returns
Nothing.
Description
Event fired when a you have been accepted or denied access to a room. When you invoke the createRoom() method or the joinRoom() method you will receive a roomJoined event as a response after the server processes your request. This event passes in an object with a success = true or false property. If success = false then this object also contains an error message.
Typical errors are due to invalid room passwords (when trying to join a password protected room), invalid room name, or room full.
Note: the reference to the room that you are in can also be retrieved by using the getRoom() method.
Example
function roomJoined(results:Object, myRoom:Object) {
if (results.success) {
//Joined the room
gotoAndStop("Chat");
} else {
//Did not join the room
trace(results.error);
msg.text = results.error;
gotoAndStop("Error");
}
}
es.roomJoined = roomJoined;
roomListUpdated :
Availability
Flash Player 6.
Usage
ElectroServer.roomListUpdated(roomList,updateType,roomReference)
Parameters
roomList An array of objects describing the list of rooms. (Array)
updateType "all", "roomupdated", "roomcreated", "roomdeleted" (String)
roomReference roomReference parameter. (Object)
Returns
Nothing.
Description
Event fired when an update to the zone roomlist is received.
If updateType is "all": This is the initial roomlist received when joining a new zone (or logging in for the first time).
If updateType is "roomupdated": This is just a change in details for one room, such as its description, the number of users in that room, etc.
If updateType is "roomcreated": The room was just created.
If updateType is "roomdeleted": A room was jut removed. The 'roomReference' parameter is a string representing the name of the room just deleted. It is not a reference to the room object since it has been deleted.
Note: The reference to the room list can also be retrieved by using the getRoomList() method.
Example
The following is code that could have been used to update a visual list of rooms (perhaps in a list box component) as updates come in:
function roomListUpdated(roomList:Array, type:String, roomReference:Object) {
if (type == "all") {
//The entire list is new
showRooms(roomList);
} else if (type == "roomupdated") {
//A room that exists was updated
updateRoomInList(roomReference);
} else if (type == "roomcreated") {
//A new room was added
addRoomToList(roomReference);
} else if (type == "roomdeleted") {
//A room was removed
removeRoomFromList(roomReference);
}
}
es.roomListUpdated = roomListUpdated;
roomVariablesUpdated :
Availability
Flash Player 6.
Usage
ElectroServer.roomVariablesUpdated(type,roomVariables,name)
Parameters
type "all", "updated", "created", "deleted" (Object)
roomVariables An object containing all of the room variables. (Object)
name String name of the variable updated. (blank if type=="all") (Object)
Returns
Nothing.
Description
Event fired when a room variable is created, modified, or removed.
Room variables are variables actually store on the server in your room. They can be created, modified, or removed. By default, a room variable can be modified and will automatically be removed when the user that created it leaves the room. However, a room variable can be flagged to be persistent which means that it will nto delete when the user that creates it leaves the room. Also, a room variable can be flagged as locked, which means that once locked it can no longer be modified (but can still be deleted).
Example
If you created a chat room where you wanted to put an icon next to users that say they want to chat one-on-one with someone, then room variables can help there. Someone might create a room variable with their username and the following code is how it would be handled:
function roomVariablesUpdated(type:String, ob:Object, name:String) {
if (type == "updated" || type == "created") {
flagUserAsWantingToChat(name);
}
}
es.roomVariablesUpdated = roomVariablesUpdated;
In the createRoomVariable() method documention there is code to show a variable being created showing if a secret door has been unlocked or not. Here is that code again followed by the code that would intercept this variable once created:
To create it:
var ob:Object = new Object();
ob.name = "secretDoorUnlocked";
ob.data = "true";
ob.locked = true;
ob.persistent = true;
es.createRoomVariable(ob);
To intercept it:
function roomVariablesUpdated(type:String, ob:Object, name:String) {
if (type == "updated") {
if (name == "secretDoorUnlocked") {
toggleSecretDoor(ob.secretDoorUnlocked);
}
}
}
es.roomVariablesUpdated = roomVariablesUpdated;
userListUpdated :
Availability
Flash Player 6.
Usage
ElectroServer.userListUpdated(userList,type,name)
Parameters
userList Array of user objects (Array)
type "all", "userjoined", "userleft" (String)
userReference Name of the user that joined or left (String)
Returns
Nothing.
Description
Event fired when the users in your room changes. When you first join a room you get the full user list and type is "all". After that you only receive "userjoined" and "userleft" updates.
If type is "all" then the userRefrence parameter is blank. If type is "userjoined" then the userReference parameter contains a reference to the user object. If type is "userleft" then the userReference parameter is a string name of the user that left (not a reference to the object as the object has been removed).
Example
The following code could be used to handle user list updates to build a visual representation of the users (e.g. list box component):
function userListUpdated(userList:Array, type:String, userReference:Object) {
if (type == "all") {
//The entire list is new
buildUserList(userList);
} else if (type == "userjoined") {
//A user joined the room
addUserToList(userReference);
} else if (type == "userleft") {
//A user left the room
removeUserFromList(userReference);
}
}
es.userListUpdated = userListUpdated;
userLocationLoaded :
Availability
Flash Player 6.
Usage
ElectroServer.userLocationLoaded(username,zone,room)
Parameters
username Username (String)
zone Zone that the user is in (String)
room Room that the user is in (String)
Returns
Nothing.
Description
This event is fired as a result of getUserLocation. It tells you the zone and room that a specific user is in. See getUserLocation for more information.
Example
es.getUserLocation("jobem");
es.userLocationLoaded = function(username, zone, room) {
trace(username+", "+zone+", "+room);
};
usersInRoomLoaded :
Availability
Flash Player 6.
Usage
ElectroServer.usersInRoomLoaded(userlist)
Parameters
users Array of objects (Array)
zone Name of zone that room is in (String)
room Name of room that users are in (String)
Returns
Nothing.
Description
As a result of getUsersInRoom this event is fired. An array of user objects with a 'name' property is passed in. Also, the zone name and room name of the users are passed in.
Note: we are using objects with a 'name' property to leave open the chance to add more useful properties to this in the future, like userVariables. Currently you cann't load userVariables of a user who is in another room.
Example
es.getUsersInRoom("Chat Area", "Lobby");
es.usersInRoomLoaded = function(users, zone, room) {
//This is fired when the users in a specific room have been loaded
//array is returned with user objects. They have only 1 property, username
trace(zone)
trace(room)
for (var i = 0; i
trace(ob.username);
}
};
usersRenumbered :
Availability
Flash Player 6.
Usage
ElectroServer.usersRenumbered(userList)
Parameters
userList Array of user objects. (Array)
Returns
Nothing.
Description
Event fired when the users in your room have been renumbered. By default, when creating a room the Numbered attribute is 'false', meaning the users in that room are not numbered. However, when Numbered is 'true', the users in the room are numbered.
Why numbered users are usefull
When creating multiplayer games that use more than two players it is quite a task to keep track of the order of users in the game. What happens if someone leaves the game in the middle and it is their turn to move? Due to Internet latency and the various scenarios by which a person can leave a game it is difficult to guarantee no problems.
With numbered users you always know the order of the users. If it is number 3's turn to move and then number 3 leaves the room, well then it is still number 3's turn because number 4 just shifted down a position. Since this is kept on the server there is no chance of synchronization problems.
This concept is not the easiest to understand initially, it may help to view sample FLA files.
Note: the userList is passed in to the event handler. The userList can also be retrieved using the getUserList() method.
Example
Better example to come. The following simple traces the number of each user.
function usersRenumbered(userList:Array) {
for (var i:Number = 0; i < userList.length; ++i) {
trace(userList[i].AssignedNumber);
}
}
es.usersRenumbered = usersRenumbered;
userVariableUpdated :
Availability
Flash Player 6.
Usage
ElectroServer.userVariableUpdated(user,type,name)
Parameters
user object referencing the user who owns the variable (Object)
type Either "created" or "updated" (String)
name Name of the variable created or updated (String)
Returns
Nothing.
Description
This event is fired when a uservariable is created or updated that is associated with a user in your room.
Example
es.userVariableUpdated = function(user, type, name) {
trace("----------------");
trace("es.userVariableUpdated called");
trace("user="+user.Name.value);
trace(type)
trace("variable name="+name);
trace("variable value="+user.userVariables[name])
}
zoneChanged :
Availability
Flash Player 6.
Usage
ElectroServer.zoneChanged(zone)
Parameters
zone Name of the zone that you entered (String)
Returns
Nothing.
Description
Event fired when you enter a new zone. Simply gives you the name of the zone that you have just entered.
A zone is a collection of rooms much like a room is a collection of users. When in a zone you get information on the other rooms in your zone. You have no knowledge of any of the other zones.
Example
function zoneChanged(name:String) {
trace("I just entered this zone: "+name);
}
es.zoneChanged = zoneChanged;
zoneUpdated :
Availability
Flash Player 6.
Usage
ElectroServer.zoneUpdated(numUsers)
Parameters
numUsers Number of users in the zone (String)
Returns
Nothing.
Description
Event fired when the number of users in the zone changes. Simply gives you the number of users in your zone when ever that number is changed.
Example
function zoneUpdated (numUsers:Number) {
trace("The number of people in my zone is: "+numUsers);
}
es.zoneUpdated = zoneUpdated;
ElectroServer Associations
None.