Basic ActionMap Example

From Blue Mars Developer Guidebook

This page is protected and certified by Avatar Reality Inc. Only Editable by Avatar Reality Staff Members.

Contents 1 Action Map 2 Using the ActionMapManager Lua API

This basic Action Map example illustrates:

1. Defining a custom action map in XML
2. Loading and enabling a custom action map with ActionMapManager functions
3. Registering an OnAction state callback with a HUD function
4. Handling actions in the OnAction state callback

Action Map

Here's our custom action map, ActionMapExampleProfile.xml. In the example it is loaded from Levels/AR/Common/Libs/Config/ (create yours in a similar location under your company directory).

<?xml version="1.0" encoding="utf-8"?>
<ActionMaps>
  <actionmap name="ActionMapExample" version="21">
    <action name="amapex_left" onPress="1"> 
      <key name="a" />
      <key name="left" />
    </action>
    <action name="amapex_right" onPress="1">
      <key name="d" />
      <key name="right" />
    </action>
    <action name="amapex_forward" onPress="1">
      <key name="w" />
      <key name="up" />
    </action>
    <action name="amapex_back" onPress="1">
      <key name="s" />
      <key name="down" />
    </action>
    <action name="amapex_exit" onPress="1">
      <key name="q" />
    </action>
  </actionmap>
</ActionMaps>

Using the ActionMapManager Lua API

To test this script, an ARAvatarTrigger should be placed in a level, with ScriptCommand Property: EntityNamed("ActionMapExample1"):RespondToActions();. Be sure to register this ActionMapExample entity and place it in the level as well.

What to expect: when the avatar enters the trigger, the RespondToActions function will be called. You'll see debug messages for the WASD and arrow keys while in the Responding state, and WASD will not control the avatar since the "player" action map is disabled. The "q" key will quit to the Finish state, unregistering the action callback and re-enabling the "player" action map.

ActionMapExample =
{
  States = 
  {
    "Responding",
    "Finish",
  },

  Actions =
  {
    back = "amapex_back",
    forward = "amapex_forward",
    left = "amapex_left",
    right = "amapex_right",
    quit = "amapex_exit",
  },

  Editor=
  {
    Icon="AR_Default.bmp",
    ShowBounds=0,
  },
  
  actionCallbackID = nil,
}

function ActionMapExample:RespondToActions()
  if (not self.actionCallbackID) then
    if (not ActionMapManager.IsActionMapLoaded("ActionMapExample")) then
      --load custom action map (update path to your company directory)
      ActionMapManager.LoadFromXML("levels/ar/common/libs/config/actionmapexampleprofile.xml");
    end
    if (not ActionMapManager.IsActionMapEnabled("ActionMapExample")) then
      --enable custom action map
      ActionMapManager.EnableActionMap("ActionMapExample", true);
    end
    --handle actions in the state OnAction callback below
    self.actionCallbackID = HUD.RegisterActionCallback(self.Responding.OnAction, self); 
  end
  self:GotoState("Responding");
end

function ActionMapExample:OnReset() --City Editor cleanup
  self:GotoState("Finish");
end

ActionMapExample.Responding =
{
  OnBeginState = function(self)
    ARDebugMessage("Responding to custom WASD & arrow actions - Q to quit", 7);
    --disable the automatically enabled "player" action map while using your custom action map
    ActionMapManager.EnableActionMap("player",false);
  end,
  OnAction = function(self, action, activationMode)
    if (action == self.Actions.back) then ARDebugMessage("custom action: back");
    elseif (action == self.Actions.forward) then ARDebugMessage("custom action: forward");
    elseif (action == self.Actions.left) then ARDebugMessage("custom action: left");
    elseif (action == self.Actions.right) then ARDebugMessage("custom action: right");
    elseif (action == self.Actions.quit) then
      ARDebugMessage("custom action: quit");
      self:GotoState("Finish");
    end
  end,
  OnEndState = function(self)
    if (self.actionCallbackID) then
      HUD.UnregisterActionCallback(self.actionCallbackID);
      self.actionCallbackID = nil;      
      ActionMapManager.EnableActionMap("player",true);
    end
  end,
}

ActionMapExample.Finish = {}

Author: Magnolia @ AR

See HUD Actions and ActionMap_Manager for further details, including a list of available key/mouse names

Back to the Script Center