Entity Communication

From Whirled

Jump to: navigation, search
ActionScript Tutorial
Create an interactive pet using AS3.
Difficulty Level
Intermediate
Requirements
ActionScript 3.0, Whirled SDK
Other Information
This tutorial uses AS3 to build a smart pet that is able to detect and interact with other items in the room.


Contents

Prerequisites

  1. Setting up your programming environment
  2. This tutorial currently assumes you are familiar with programming and that you can learn by example.

Entity Events

In Whirled, every item (toys, pets, avatars, backdrops...) is called an entity. Every copy of your item in Whirled has its own unique entity ID.

You can use EntityControl.addEventListener() to listen for entityEntered, entityMoved and entityLeft events: 

_ctrl = new PetControl(this);
_ctrl.addEventListener(ControlEvent.ENTITY_MOVED, handleMovement);

function handleMovement (event :ControlEvent) :void
{
    _ctrl.sendChat("Something's moving around!");
}

Requesting Properties

The ControlEvent contains the entity ID of the mover, we can use that to access properties on that entity using EntityControl.getEntityProperty(): 

function handleMovement (event :ControlEvent) :void
{
    var targetId :String = event.name;

    // Use getEntityProperty() to query the target's name
    _ctrl.sendChat("I see you " + _ctrl.getEntityProperty(EntityControl.PROP_NAME, targetId));
}

Now our pet will announce when it sees an avatar (or another pet) moving in the room. Let's improve this a bit to make the pet follow any movement: 

function handleMovement (event :ControlEvent) :void
{
    var targetId :String = event.name;

    // IMPORTANT: We will receive events from our own movements, so make sure we don't handle them here
    if (targetId != _ctrl.getMyEntityId()) {
        _ctrl.sendChat("I see you " + _ctrl.getEntityProperty(EntityControl.PROP_NAME, targetId));
        
        // Follow it
        var pos :Array = _ctrl.getEntityProperty(EntityControl.PROP_LOCATION_PIXEL, targetId) as Array;
        _ctrl.setPixelLocation(pos[0], pos[1], pos[2], 0);
    }
}

Custom Property Providers

Let's make a food bowl that our pet can go to when he's hungry. The food bowl will be a separate toy item, and can use a property provider to respond to our pet when he asks for food. 

// In Food.as

_ctrl = new PetControl(this);
_ctrl.registerPropertyProvider(propertyProvider);

function propertyProvider (key :String) :Object
{
    if ("tutorial:takeFood" == key) {
        // Something in the room is requesting food from me, send back a random amount
        return Math.floor(Math.random()*20) + 1;
    }

    // We don't support this key, so return null
    return null;
}

Let's modify our pet to look for food when someone in the room says "go eat": 

// In Dog.as

_ctrl.addEventListener(ControlEvent.RECEIVED_CHAT, handleChat);

function handleChat (event :ControlEvent) :void
{
    if (event.value == "go eat") {
        // Get all the furniture/toys IDs in the room
        var furnis :Array = _ctrl.getEntityIds(EntityControl.TYPE_FURNI);

        for each (var id :String in furnis) {
            // Try to ask for some food
            var food :Number = _ctrl.getEntityProperty("tutorial:takeFood", id) as Number;

            // If food was returned
            if (food > 0) {
                _ctrl.sendChat("*munch munch*");

                // Walk over to the food bowl
                var pos :Array = _ctrl.getEntityProperty(EntityControl.PROP_LOCATION_PIXEL, id) as Array;
                _ctrl.setPixelLocation(pos[0], pos[1], pos[2], 0);

                return;
            }
        }

        // If we reach this point, we didn't find anything edible
        _ctrl.sendChat("I can't find anything to eat... *whimper*");
    }
}

Calling Remote Functions

Property providers allows an entity to respond to simple messages passed to it. In this case, the messages are just strings. What if we want to specify parameters in the message? For example, a Knight avatar may send an "attackForDamage" message along with the amount of damage it is trying to inflict. In this hypothetical case, a slayable Dragon pet would listen for "attackForDamage" and respond: 

// In Dragon.as

_ctrl.registerPropertyProvider(propertyProvider);
function propertyProvider (key :String) :Object
{
    if (key == "attackForDamage") {
        // Don't actually do anything yet
        // Return a Function object that the Knight can use to damage the dragon
        return function (damage :Number) :void {
            _ctrl.sendChat("Ouch! A Knight hit me for " + x + " damage!");
        }
    }

    return null;
}

// In Knight.as

var dragonId :String = ... // The entity ID of a Dragon
var attackForDamage :Function = _ctrl.getEntityProperty("attackForDamage", dragonId) as Function;

// Attack the Dragon for 30 damage
attackForDamage(30);

// Or... have damage be based on your Knight's "level"
attackForDamage(10 * (_ctrl.getMemory("level") as Number));

Helper Class: RemoteEntity

If your project use entity properties heavily, consider using the convenient RemoteEntity class instead of direct calls to EntityControl.getEntityProperty(): 

// RemoteEntity example snippet:

// Set up a remote targeting a certain entity
var remote :RemoteEntity = new RemoteEntity(_ctrl, targetId);

// Same as trace("Hello " + _ctrl.getEntityProperty(EntityProperty.PROP_NAME, targetId) as String))
trace("Hello " + remote.getName());

// Same as (_ctrl.getEntityProperty("attackForDamage", targetId) as Function)(50);
remote.call("attackForDamage", 50);


Demo

Mr Fusspot gets hungry quickly, but he's happy to play with visitors when he has the energy:

External links

Retrieved from "http://wiki.whirled.com/Entity_Communication"
Personal tools