Basic ActionMap Example

From Blue Mars Developer Guidebook

Jump to: navigation, search
There are security restrictions on this article

Contents

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

Problems with this wiki page? Contact us either by: Support Email or Support Ticket System

Blue Mars Guidebook Privacy Policy
Blue Mars Guidebook Community Guidelines

Personal tools