Lamp toy (code tutorial)

The lamp is a very simple toy that demonstrates persistent memory. This is a guide to the Whirled code behind the lamp.

Prerequisites
This tutorial assumes that you have completed the Simple avatar (Flash tutorial). In particular, it requires that you set up the Whirled SDK.

Downloading the Example

 * 1) Get the lamp example here: [[Media:Lamp.zip]]
 * 2) Extract the archive's contents and open the lamp.fla file in Flash CS3.

Control Setup
First, we set up a control object for interacting with Whirled.

var _ctrl :ToyControl = new ToyControl(this);

Listening for memory changes
When one player toggles the lamp, we want all of the other players in the room to see the change as well. Also, when the last player leaves the room with the lamp on, we want it to still be on when a player returns.

We manage this by storing the values in entity memory. Entity memory is shared among instances of the object, and is stored by the Whirled server even when no instances are active.

When the server detects that an entity's memory has changed, it emits an event so that the instances running in players' browsers can respond appropriately. We'll listen for those events and assign the "updateLamp" function to handle them:

_ctrl.addEventListener(ControlEvent.MEMORY_CHANGED, updateLamp);

The updateLamp function checks the shared persistent memory and updates the local lamp's appearance appropriately. Entity memory is stored as values associated with String keys. The lamp uses only one memory entry, named "State", and expects it to have a value of "On" or "Off".

ToyControl.getMemory(key, default) is used to retrieve entity memories by key. If no memory by the called key exists, the second argument is used as the default value. In updateLamp, this line is used to retrieve the lamp's on or off state, which will default to "Off" if it has never been set.

var memory:Object = _ctrl.getMemory("State", "Off");

If the memory says that the state is "On", the lamp runs its "On" animation. If it is "Off", it runs the "Off" animation.

The updateLamp function is called once during setup to syncronize the new lamp with the last stored setting.

Responding to memory changes
The lamp should toggle on and off when a player clicks it. To accomplish this, we set up a MOUSE_DOWN listener.

hitBox.addEventListener(MouseEvent.MOUSE_DOWN, mouseDownHandler);

To inform the instances in other players' browsers, the mouseDownHandler function sets the entity memory to the new value. This will send a MEMORY_CHANGED event to each instance of the lamp (including the local instance that caused the change), allowing them to update their images.

The toggling happens in the switchLamp function. It first retrieves the current value, as above.

var memory:Object = _ctrl.getMemory("State", "Off");

It then sets the opposite state.

if(String(memory) == "On"){ _ctrl.setMemory("State","Off"); }else if(String(memory) == "Off"){ _ctrl.setMemory("State","On"); }

The MEMORY_CHANGED event is sent to each instance of the lamp, triggering its updateLamp method (because of the listener we set up in the constructor).

function updateLamp (o :Object = null) :void {	//Get value of the memory from the server. (Variable name, Default Value) var memory:Object = _ctrl.getMemory("State", "Off"); if(String(memory) == "On"){ theLamp.gotoAndPlay("On"); }else if(String(memory) == "Off"){ theLamp.gotoAndPlay("Off"); } }

In this example, we're not using the method argument (the Object o). When the event is triggered, we retrieve the new state from the shared memory.

var memory:Object = _ctrl.getMemory("State", "Off"); We then trigger the appropriate animation. if(String(memory) == "On"){ theLamp.gotoAndPlay("On"); }else if(String(memory) == "Off"){ theLamp.gotoAndPlay("Off"); }