Packagecom.whirled.game
Classpublic class NetSubControl
InheritanceNetSubControl Inheritance AbstractSubControl Inheritance AbstractControl Inheritance flash.events.EventDispatcher
ImplementsPropertySubControl

Provides access to 'net' game services. Do not instantiate this class yourself, access it via GameControl.net. The 'net' subcontrol is used to communicate shared state between game clients. When you set a property it is immediately distributed to the other clients in the game. Reading a property is immediate, you are reading the properties that have already been distributed. When a client connects to an already-running game, any properties already set will be available. Messages can be sent by either a server agent or a client at a maximum rate of 10 messages per second. Messages sent at a greater rate will be buffered until sending them will not cause this limit to be exceeded. A message sent to all players counts as a single message against this limit. Changing a property value also counts as sending a single message. The doBatch method can be used to combine a number of otherwise unrelated messages or property changes into a single unit so that they count only once against the limit.

See also

doBatch

Public Properties
 PropertyDefined by
  agent : MessageSubControl
[read-only] Provides a control with which to send messages to the server agent.
NetSubControl
  players : MessageSubControl
[read-only] Provides a control with which to send messages to all the players of this game, excluding any agent.
NetSubControl
Protected Properties
 PropertyDefined by
  _agentMsgCtrl : MessageSubControl
NetSubControl
  _playerCtrls : Map
NetSubControl
  _playersMsgCtrl : MessageSubControl
NetSubControl
Public Methods
 MethodDefined by
 Inherited
addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void
Registers an event listener.
AbstractControl
 Inherited
doBatch(fn:Function, ... args):void
Execute the specified function as a batch of commands that will be sent to the server together.
AbstractSubControl
  
get(propName:String):Object
NetSubControl
  
getPlayer(playerId:int):MessageSubControl
Provides a per-player way to send messages to a specific player.
NetSubControl
  
getPropertyNames(prefix:String = ""):Array
Get the names of all currently-set properties that begin with the specified prefix.
NetSubControl
 Inherited
isConnected():Boolean
Are we connected and running inside the whirled environment, or has someone just loaded up our SWF by itself?
AbstractSubControl
 Inherited
removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void
Unregisters an event listener.
AbstractControl
  
sendMessage(messageName:String, value:Object, playerId:int):void
Send a "message" to other clients subscribed to the game.
NetSubControl
  
set(propName:String, value:Object, immediate:Boolean = false):void
NetSubControl
  
setAt(propName:String, index:int, value:Object, immediate:Boolean = false):void
Update one element of an Array.
Note: Unlike setIn(), this update will fail silently if the index is out of bounds or if there is no array currently set at the specified property name.
NetSubControl
  
setIn(propName:String, key:int, value:Object, immediate:Boolean = false):void
Update one element of a Dictionary.
Note: Unlike setAt(), this will usually work.
NetSubControl
  
testAndSet(propName:String, newValue:Object, testValue:Object):void
Set a property that will be distributed, but only if it's equal to the specified test value.
NetSubControl
Events
 EventSummaryDefined by
  
ElemChanged
Dispatched when an element inside a property has changed in the shared game state.NetSubControl
  
MsgReceived
Dispatched when a message arrives with information that is not part of the shared game state.NetSubControl
  
PropChanged
Dispatched when a property has changed in the shared game state.NetSubControl
 Inherited
unload
Event.UNLOAD Dispatched when the SWF using this control has been unloaded.AbstractControl
Public Constants
 ConstantDefined by
  TO_ALL : int = 0
[static] Constant provided to sendMessage that will send a message to all subscribers.
NetSubControl
  TO_SERVER_AGENT : int = -2.147483648E9
[static] Constant provided to sendMessage that will send a message to the game's server agent, if there is one.
NetSubControl
Protected Constants
 ConstantDefined by
  EXCLUDE_AGENT : int = -2.147483647E9
[static] A special constant for sending a message to players only, and not the agent.
NetSubControl
Property detail
agentproperty
agent:MessageSubControl  [read-only]

Provides a control with which to send messages to the server agent.

Implementation
    public function get agent():MessageSubControl

See also

sendMessage
_agentMsgCtrlproperty 
protected var _agentMsgCtrl:MessageSubControl
_playerCtrlsproperty 
protected var _playerCtrls:Map
playersproperty 
players:MessageSubControl  [read-only]

Provides a control with which to send messages to all the players of this game, excluding any agent.

Implementation
    public function get players():MessageSubControl

See also

sendMessage
_playersMsgCtrlproperty 
protected var _playersMsgCtrl:MessageSubControl
Method detail
get()method
public function get(propName:String):Object

Parameters
propName:String

Returns
Object
getPlayer()method 
public function getPlayer(playerId:int):MessageSubControl

Provides a per-player way to send messages to a specific player.

Parameters
playerId:int

Returns
MessageSubControl

See also

sendMessage
getPropertyNames()method 
public function getPropertyNames(prefix:String = ""):Array

Get the names of all currently-set properties that begin with the specified prefix. Calling this method results in no network traffic.

Parameters
prefix:String (default = "")

Returns
Array
sendMessage()method 
public function sendMessage(messageName:String, value:Object, playerId:int):void

Send a "message" to other clients subscribed to the game. These is similar to setting a property, except that the value will not be saved- it will merely end up coming out as a MessageReceivedEvent.

Parameters
messageName:String — The message to send.
 
value:Object — The value to attach to the message.
 
playerId:int — if TO_ALL (or unset), sends to everyone (including the agent), otherwise the message will be private to just one player; if the game employs a server agent, TO_SERVER_AGENT may be used to send a message only to the server.

See also

TO_ALL
TO_SERVER_AGENT
set()method 
public function set(propName:String, value:Object, immediate:Boolean = false):void

Parameters
propName:String
 
value:Object
 
immediate:Boolean (default = false)
setAt()method 
public function setAt(propName:String, index:int, value:Object, immediate:Boolean = false):void

Update one element of an Array.
Note: Unlike setIn(), this update will fail silently if the index is out of bounds or if there is no array currently set at the specified property name. Furthermore, if you set the element with immediate=true, there are two updates: one locally that happens right away and the update on the server that will be dispatched back to all the clients. Either or both can fail, so be sure to set the Array up first using set().

Parameters
propName:String — the name of the property to modify.
 
index:int — the array index of the element to update.
 
value:Object — the value to set.
 
immediate:Boolean (default = false) — if true, the value is updated immediately in the local object. Otherwise any old value will remain in effect until the ElementChangedEvent arrives after a round-trip to the server.
setIn()method 
public function setIn(propName:String, key:int, value:Object, immediate:Boolean = false):void

Update one element of a Dictionary.
Note: Unlike setAt(), this will usually work. No key is out of range, obviously, and if you set a value in a property that was previously null, a new Dictionary will be created to hold your value. If a non-Dictionary property is already stored with the specified name then this will fail silently on the server. But: don't do that! It would be pretty bad style to store two different types of property under the same name.

Parameters
propName:String — the name of the property to modify.
 
key:int — the key of the element to update.
 
value:Object — the value to set. Passing null removes the specified key from the Dictionary.
 
immediate:Boolean (default = false) — if true, the value is updated immediately in the local object. Otherwise any old value will remain in effect until the ElementChangedEvent arrives after a round-trip to the server.
testAndSet()method 
public function testAndSet(propName:String, newValue:Object, testValue:Object):void

Set a property that will be distributed, but only if it's equal to the specified test value.

Please note that there is no way to test and set a property immediately, because the value must be sent to the server to perform the test.

The operation is 'atomic', in the sense that testing and setting take place during the same server event. In comparison, a separate 'get' followed by a 'set' operation would first read the current value as seen on your client and then send a request to overwrite any value with a new value. By the time the 'set' reaches the server the old value may no longer be valid. Since that's sketchy, we have this method.

Parameters
propName:String
 
newValue:Object
 
testValue:Object
Event detail
ElemChangedevent 
Event object type: com.whirled.net.ElementChangedEvent
ElementChangedEvent.type property = com.whirled.net.ElementChangedEvent.ELEMENT_CHANGED

Dispatched when an element inside a property has changed in the shared game state. This event is a result of calling setIn() or setAt().

The type of an ElementChangedEvent.

MsgReceivedevent  
Event object type: com.whirled.net.MessageReceivedEvent
MessageReceivedEvent.type property = com.whirled.net.MessageReceivedEvent.MESSAGE_RECEIVED

Dispatched when a message arrives with information that is not part of the shared game state.

The type of all MessageReceivedEvents.

PropChangedevent  
Event object type: com.whirled.net.PropertyChangedEvent
PropertyChangedEvent.type property = com.whirled.net.PropertyChangedEvent.PROPERTY_CHANGED

Dispatched when a property has changed in the shared game state. This event is a result of calling set() or testAndSet().

The type of a property change event.

Constant detail
EXCLUDE_AGENTconstant
protected static const EXCLUDE_AGENT:int = -2.147483647E9

A special constant for sending a message to players only, and not the agent.

TO_ALLconstant 
public static const TO_ALL:int = 0

Constant provided to sendMessage that will send a message to all subscribers.

See also

sendMessage()
TO_SERVER_AGENTconstant 
public static const TO_SERVER_AGENT:int = -2.147483648E9

Constant provided to sendMessage that will send a message to the game's server agent, if there is one.

See also

sendMessage()



Copyright © 2007-2009 Three Rings Design, Inc.