ActionMap Manager

From Blue Mars Developer Guidebook

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

Contents

Action Maps

Overview

Action maps are sets of action names associated with key or mouse gestures, defined in an XML file. Game logic can then use these logical names instead of hardcoding them and allow for different input devices.

Actions are not processed while the console is up or if a modal Flash element is active (see HUD).

Image:Actionmap.png

Action maps are defined in XML files. An action map file contains a version that should always be "21", and a number of action maps, each with a map name and a list of action names. Each action can be invoked by one or two key or mouse gestures (listed below).

The standard action maps are defined in Game/Libs/Config/defaultProfile.xml.

Third-party action maps should be added according to the the guidelines in General Attraction Submission Format. Action map files named defaultProfile.xml in the recommended locations will automatically be loaded.

Example

This action map defines three actions, each invoked on the key press (as opposed to key release).

<?xml version="1.0" encoding="utf-8"?>
<ActionMaps>
  <actionmap name="ARTest" version="21">
    <action name="nexttest" onPress="1">
      <key name="pgdn" />
    </action>
    <action name="prevtest" onPress="1">
      <key name="pgup" />
    </action>
    <action name="snapshot" onPress="1">
      <key name="print" />
    </action>
  </actionmap>
</ActionMaps>

Here's an entity script that loads and enables this action map. One or two (alternate) keys can be listed for each action. See HUD#Actions for more on registering the action callback.

function ARBasicTest:OnInit()
   ARTestStart(self);
end


-- just in the Editor
function ARBasicTest:OnReset()
   ARTestStart(self);
end

function ARBasicTest:StartTest()
   -- in the Editor, this may get called twice, so make sure part of it just gets called once
   if (self.ARTestOnActionID==nil) then
	ARDebug(3);
	ARDebugMessage("Starting Avatar Reality script test "..self.class,5);
	self:Activate(1);
	ActionMapManager.LoadFromXML("Levels/AR/Common/Libs/Config/ARTestProfile.xml");
	self.ARTestOnActionID=HUD.RegisterActionCallback(self.OnAction,self);
	self:GotoState(self.States[1]);
     end
     -- this is the part we want called a second time in the Editor
     ActionMapManager.EnableActionMap("ARTest",true);
  end

The script above is overly complicated. If the action map file was named defaultProfile.xml it would be loaded automatically and then only one line of code is needed to enable the action map.

function ARBasicTest:StartTest()
     ActionMapManager.EnableActionMap("ARTest",true);
  end


This still doesn't really do anything, until implement the action callback.

function ARBasicTest:OnAction(action,mode)
   if (mode == eAAM_OnPress) then
      if (action == "nexttest") then
	 self:NextState();
      elseif (action == "prevtest") then
	 self:PreviousState();
      elseif (action == "snapshot") then
	 System.ExecuteCommand("snapshot");
      end
   end
end

Functions

Minigames obtain the most recently-issued action by using HUD functions.

These Lua functions are available in the ActionMapManager table.


LoadFromXML(filename)
load an action map XML file.


IsActionMapLoaded(name)
return value - true if action map is loaded, false if not


EnableActionMap(name, enable)
turn action map on/off


IsActionMapEnabled(name)
return value - true if action map is enabled, false if not


Enable(enable)
enable/disable the action map manager

Console & Debugging

See Console/ActionMap

After making changes to an action map, if the expected actions are not received, here are a few ways to debug:

  • Make sure the action map is properly formatted, loaded (LoadFromXML, IsActionMapLoaded) and enabled (EnableActionMap, IsActionMapEnabled)
  • Use the Console Variable dump_action_maps to print the list of currently-loaded actions; if yours do not show up in the list, then:
  • Delete your local <My Documents\My Games\BlueMars> directory and re-launch the City Editor or Blue Mars client to ensure the action map is re-loaded

Standard Action Maps

The action maps are defined in Game/Libs/Config/defaultProfile.xml

debug

The debug action map is always enabled in devMode.

  <actionmap name="debug" version="21">
    <action name="debug" onPress="1">
      <key name="7" />
    </action>
    <action name="thirdperson" onPress="1" noModifiers="1">
      <key name="f1" />
    </action>
    <action name="tweak_enable" onPress="1">
      <key name="np_enter" />
    </action>
    <action name="tweak_up" onPress="1">
      <key name="up" />
      <key name="np_8" />
    </action>
    <action name="tweak_down" onPress="1">
      <key name="down" />
      <key name="np_2" />
    </action>
    <action name="tweak_left" onPress="1">
      <key name="left" />
      <key name="np_4" />
    </action>
    <action name="tweak_right" onPress="1">
      <key name="right" />
      <key name="np_6" />
    </action>
    <action name="tweak_inc" onPress="1">
      <key name="np_add" />
    </action>
    <action name="tweak_dec" onPress="1">
      <key name="np_subtract" />
    </action>
  </actionmap>

default

The default action map is normally enabled and includes the "use" action and mouse actions, normally used by HUD code.

  <actionmap name="default" version="21">
    <action name="hud_mouseclick" onPress="1" onRelease="1">
      <key name="mouse1" />
    </action>
    <action name="xi_use" onPress="1" onRelease="1">
      <key name="xi_x" />
    </action>
    <action name="hud_mousewheelup" onPress="1">
      <key name="mwheel_up" />
    </action>
    <action name="hud_mousewheeldown" onPress="1">
      <key name="mwheel_down" />
    </action>
    <action name="hud_mouserightbtndown" onPress="1">
      <key name="mouse2" />
    </action>
    <action name="hud_mouserightbtnup" onRelease="1">
      <key name="mouse2" />
    </action>
    <action name="hud_mousey">
      <key name="maxis_y" />
      <key name="xi_thumbry" />
    </action>
    <action name="xi_hud_back" onPress="1" onRelease="1">
      <key name="xi_start" />
    </action>
    <action name="hud_mousex">
      <key name="maxis_x" />
      <key name="xi_thumbrx" />
    </action>
    <action name="use" onPress="1" onRelease="1">
      <!-- also former v_exit -->
      <key name="f" />
    </action>
  </actionmap>


player

The player action map is normally enabled and is used to control a player's avatar.

  <actionmap name="player" version="21">
    <action name="xi_movey">
      <key name="xi_thumbly" />
    </action>
    <action name="moveleft" onPress="1" onRelease="1" retriggerable="1">
      <key name="a" />
      <key name="left" />
    </action>
    <action name="moveright" onPress="1" onRelease="1" retriggerable="1">
      <key name="d" />
      <key name="right" />
    </action>
    <action name="rotatepitch">
      <key name="maxis_y" />
    </action>
    <action name="leanleft" onPress="1" onRelease="1" onHold="1">
      <key name="q" />
    </action>
    <action name="xi_rotateyaw">
      <key name="xi_thumbrx" />
    </action>
    <action name="moveback" onPress="1" onRelease="1" retriggerable="1">
      <key name="s" />
      <key name="down" />
    </action>
    <action name="moveforward" onPress="1" onRelease="1" retriggerable="1">
      <key name="w" />
      <key name="up" />
    </action>
    <action name="rotateyaw">
      <key name="maxis_x" />
    </action>
    <action name="leanright" onPress="1" onRelease="1" onHold="1">
      <key name="e" />
    </action>
    <action name="xi_rotatepitch">
      <key name="xi_thumbry" />
    </action>
    <action name="xi_movex">
      <key name="xi_thumblx" />
    </action>
  </actionmap>


vehicle

The vehicle action map is enabled when entering a vehicle.

  <actionmap name="vehicle" version="21">
    <action name="binoculars" onPress="1">
      <key name="b" />
    </action>
    <action name="v_horn" onPress="1" onRelease="1">
      <key name="h" />
      <key name="xi_thumbr" />
    </action>
    <action name="use" onPress="1" onRelease="1">
      <key name="xi_x" />
    </action>
    <action name="xi_v_rotatepitch">
      <key name="xi_thumbry" />
    </action>
    <action name="xi_v_rotateyaw">
      <key name="xi_thumbrx" />
    </action>
    <action name="v_changeseat1" onPress="1">
      <key name="1" />
    </action>
    <action name="v_changeseat2" onPress="1">
      <key name="2" />
    </action>
    <action name="v_changeseat3" onPress="1">
      <key name="3" />
    </action>
    <action name="v_changeseat4" onPress="1">
      <key name="4" />
    </action>
    <action name="v_changeseat5" onPress="1">
      <key name="5" />
    </action>
    <action name="v_changeview" onPress="1">
      <key name="f1" />
      <key name="xi_b" />
    </action>
    <action name="v_zoom_in" onPress="1">
      <key name="mwheel_up" />
    </action>
    <action name="v_zoom_out" onPress="1">
      <key name="mwheel_down" />
    </action>
    <action name="v_lights" onPress="1" onRelease="1">
      <key name="l" />
      <key name="xi_thumbl" />
    </action>
    <action name="v_rotateyaw">
      <key name="maxis_x" />
    </action>
    <action name="v_rotatepitch">
      <key name="maxis_y" />
    </action>
    <action name="v_changeseat" onPress="1">
      <key name="xi_y" />
    </action>
    <action name="xi_v_movey">
      <key name="xi_thumbly" />
    </action>
    <action name="xi_v_movex">
      <key name="xi_thumblx" />
    </action>
  </actionmap>

seavehicle

Not used.

  <actionmap name="seavehicle" version="21">
    <action name="v_boost" onPress="1" onRelease="1" onHold="1" retriggerable="1">
      <key name="lshift" />
      <key name="xi_shoulderl" />
    </action>
    <action name="v_brake" onPress="1" onRelease="1">
      <key name="space" />
      <key name="xi_a" />
    </action>
    <action name="v_moveforward" onPress="1" onRelease="1" retriggerable="1">
      <key name="w" />
    </action>
    <action name="v_moveback" onPress="1" onRelease="1" retriggerable="1">
      <key name="s" />
    </action>
    <action name="v_turnleft" onPress="1" onRelease="1" retriggerable="1">
      <key name="a" />
    </action>
    <action name="v_turnright" onPress="1" onRelease="1" retriggerable="1">
      <key name="d" />
    </action>
  </actionmap>

helicopter

Not used.

  <actionmap name="helicopter" version="21">
    <action name="v_boost" onPress="1" onRelease="1" retriggerable="1">
      <key name="lshift" />
      <key name="xi_shoulderl" />
    </action>
    <action name="v_brake" onPress="1" onRelease="1">
      <key name="key" />
    </action>
    <action name="v_rotatepitch" always="1">
      <key name="maxis_y" />
    </action>
    <action name="v_moveup" onPress="1" onRelease="1" retriggerable="1">
      <key name="w" />
    </action>
    <action name="v_movedown" onPress="1" onRelease="1" retriggerable="1">
      <key name="s" />
    </action>
    <action name="v_rotatedir" always="1">
      <key name="maxis_x" />
    </action>
    <action name="v_rollleft" onPress="1" onRelease="1" onHold="1">
      <key name="a" />
    </action>
    <action name="v_rollright" onPress="1" onRelease="1" onHold="1">
      <key name="d" />
    </action>
    <action name="v_pitchup" onPress="1" onRelease="1">
      <key name="r" />
    </action>
    <action name="v_pitchdown" onPress="1" onRelease="1">
      <key name="c" />
    </action>
  </actionmap>

landvehicle

Not used.

  <actionmap name="landvehicle" version="21">
    <action name="v_boost" onPress="1" onRelease="1" retriggerable="1">
      <key name="lshift" />
      <key name="xi_shoulderl" />
    </action>
    <action name="v_brake" onPress="1" onRelease="1">
      <key name="space" />
      <key name="xi_a" />
    </action>
    <action name="v_moveforward" onPress="1" onRelease="1" retriggerable="1">
      <key name="w" />
    </action>
    <action name="v_moveback" onPress="1" onRelease="1" retriggerable="1">
      <key name="s" />
    </action>
    <action name="v_turnleft" onPress="1" onRelease="1" retriggerable="1">
      <key name="a" />
    </action>
    <action name="v_turnright" onPress="1" onRelease="1" retriggerable="1">
      <key name="d" />
    </action>
    <action name="v_rollleft" onPress="1" onRelease="1">
      <key name="q" />
    </action>
    <action name="v_rollright" onPress="1" onRelease="1">
      <key name="e" />
    </action>
    <action name="attack1" onPress="1" onRelease="1">
	  	<key name="mouse1"/>
			<key name="xi_triggerr_btn"/>
		</action>
  </actionmap>

vtol

Not used.

  <actionmap name="vtol" version="21">
    <action name="v_boost" onPress="1" onRelease="1" retriggerable="1">
      <key name="lshift" />
      <key name="xi_shoulderl" />
    </action>
    <action name="v_rotatepitch" always="1">
      <key name="maxis_y" />
    </action>
    <action name="v_moveforward" onPress="1" onRelease="1" retriggerable="1">
      <key name="w" />
    </action>
    <action name="v_moveback" onPress="1" onRelease="1" retriggerable="1">
      <key name="s" />
    </action>
    <action name="v_moveup" onPress="1" onRelease="1">
      <key name="space" />
      <key name="xi_dpad_up" />
    </action>
    <action name="v_movedown" onPress="1" onRelease="1">
      <key name="lctrl" />
      <key name="xi_dpad_down" />
    </action>
    <action name="v_rotatedir" always="1">
      <key name="maxis_x" />
    </action>
    <action name="v_strafeleft" onPress="1" onRelease="1" onHold="1">
      <key name="a" />
    </action>
    <action name="v_straferight" onPress="1" onRelease="1" onHold="1">
      <key name="d" />
    </action>
    <action name="v_rollleft" onPress="1" onRelease="1" onHold="1">
      <key name="q" />
    </action>
    <action name="v_rollright" onPress="1" onRelease="1" onHold="1">
      <key name="e" />
    </action>
  </actionmap>

Adding Action Maps

New action map files should be added in vendor-specific directories under /Libs/Config/ , e.g. Game/Levels/AR/Common/Libs/Config.

Actions

XML Definition

An action map file rquires the following XML:

<?xml version="1.0" encoding="utf-8"?>
<ActionMaps>
  <actionmap name="mapname" version="21">

  </actionmap>
</ActionMaps>

For the actionmap name attribute, use the name of your new action map, but the version attribute must be 21.

Within the actionmap definition, list all the actions.

<action name="actioname" onPress="1">
  <key name="keyname" />
</action>

Select the action name you want, preferably specific to the context in which you'll be using this action map (e.g. "Swing" in a golf game). Specify an activation mode (in this case, onPress), and optionally a modifier.

You can specify one or two keys per action. If you specify none or more than two, the action definition will not register. Each key name corresponds to a physical key on the keyboard or a mouse button.

Activation Modes

  • onPress - the action key is pressed
  • onRelease - the action key is released
  • onHold - the action key is held
  • always -

The activation mode is passed to action listeners registered via HUD#Actions and identified by the corresponding Lua constant:

eAAM_OnPress
eAAM_OnRelease
eAAM_OnHold
eAAM_Always

Modifiers

  • retriggerable
  • noModifiers - action only takes place if no contrl, shift, alt, or win keys are pressed.
  • consoleCmd - action corresponds to a console command

List of Key Names

Key Gestures

[Letters] "a" - "z"
[Numbers] "1" - "0"
[Arrows] "up", "down", "left", "right"
[Function keys] "f1" - "f15"
[Numpad] "np_1" - "np_0", "numlock", "np_divide", "np_multiply", "np_subtract", "np_add", "np_enter", "np_period"
[Esc] "escape"
[~] "tilde"
[Tab] "tab"
[CapsLock] "capslock"
[Shift] "lshift", "rshift" 
[Control] "lctrl", "rctrl"
[Alt] "lalt", "ralt"
[ ] "space"
[-] "minus"
[=] "equals"
[Backspace] "backspace"
[[]] "lbracket", "rbracket"
[\] "backslash"
[;] "semicolon"
['] "apostrophe"
[Enter] "enter"
[,] "comma"
[.] "period"
[/] "slash"

[Home] "home"
[End] "end"
[Delete] "delete"
[PageUp] "pgup"
[PageDown] "pgdn"

[Insert] "insert"
[ScrollLock] "scrolllock"
[PrintScreen] "print"
[Pause/Break] "pause"


Mouse Gestures

[Left/primary mouse button] "mouse1"
[Right/secondary mouse button] "mouse2"
[Mouse wheel up] "mwheel_up"
[Mouse wheel down] "mwheel_down"
[New position along x-axis] "maxis_x"
[New position along y-axis] "maxis_y"


Xbox Controller Gestures

[D-pad] 
"xi_dpad_up", 
"xi_dpad_down", 
"xi_dpad_left", 
"xi_dpad_right"

[Thumbsticks] 
"xi_thumbl", "xi_thumbr" (click thumbstick)
"xi_thumblx", "xi_thumbrx" (X-axis)
"xi_thumbly", "xi_thumbry" (Y-axis)
"xi_thumbl_up", "xi_thumbr_up"
"xi_thumbl_down", "xi_thumbr_down"
"xi_thumbl_left", "xi_thumbr_left"
"xi_thumbl_right", "xi_thumbr_right"

[Buttons] 
"xi_a", 
"xi_b", 
"xi_x", 
"xi_y", 
"xi_start", 
"xi_back"

[Shoulder] 
"xi_shoulderl", "xi_shoulderr"

[Trigger]
"xi_triggerl", "xi_triggerr"
"xi_triggerl_btn", "xi_triggerr_btn" (trigger usable as a button)


Action Filters

Action filters are named sets of actions that allow you to turn off those actions.

Functions

CreateActionFilter(name)
create an action filter


FilterAction(name, action)
add a filtered action to an action filter


EnableActionFilter(name, enable)
turn an action filter on/off


IsActionFilterEnabled(name)
check whether an action filter is active

Predefined Filters

These are the action filters built into CryEngine.

no_move
leanleft
leanright
crouch
prone
jump
moveleft
moveright
moveforward
moveback
sprint
xi_movey
xi_movex
no_grenades
grenade
xi_grenade
no_mouse
attack1
v_attack
v_attack2
rotateyaw
v_rotateyaw
rotatepitch
v_rotatepitch
nextitem
previtem
small
medium
heavy
handgrenade
explosive
suitmode
utility
zoom
reload
use
xi_use
xi_grenade
xi_handgrenade
xi_zoom
jump
in_vehicle_suit_menu
use
v_changeseat
v_changeview
v_lights
v_changeseat1
v_changeseat2
v_changeseat3
v_changeseat4
v_changeseat5
suit_menu
attack1
v_attack1
v_attack2
rotateyaw
v_rotateyaw
rotatepitch
v_rotatepitch
nextitem
previtem
small
medium
heavy
handgrenade
explosive
suitmode
utility
reload
use
xi_use
xi_grenade
xi_handgrenade
xi_zoom
freezetime

reload rotateyaw rotatepitch drop modify jump crouch prone togglestance leanleft leanright

rotateyaw rotatepitch

reload drop modify nextitem previtem small medium heavy explosive handgrenade holsteritem

utility debug firemode objectives

speedmode strengthmode defensemode

invert_mouse

gboots lights

radio_group_0 radio_group_1 radio_group_2 radio_group_3 radio_group_4

voice_chat_talk xi_voice_chat_talk xi_binoculars xi_rotateyaw xi_rotatepitch xi_v_rotateyaw xi_v_rotatepitch hud_nanosuit_nextitem hud_nanosuit_minus hud_nanosuit_plus hud_mousex hud_mousey hud_mouseclick hud_suit_menu hud_openchat hud_openteamchat hud_mousewheelup hud_mousewheeldown hud_mouserightbtndown hud_mouserightbtnup hud_show_multiplayer_scoreboard hud_hide_multiplayer_scoreboard hud_toggle_scoreboard_cursor hud_pda_switch hud_show_pda_map hud_buy_weapons hud_pda_scroll scores hud_menu hud_back xi_hud_back hud_night_vision hud_weapon_mod hud_suit_mod hud_select1 hud_select2 hud_select3 hud_select4 hud_select5 buyammo

no_vehicle_exit
use
mp_radio
small
medium
heavy
suitmode
explosive
handgrenade
v_changeseat1
v_changeseat2
v_changeseat3
v_changeseat4
v_changeseat5
v_changeseat
cutscene
binoculars

hud_night_vision hud_show_multiplayer_scoreboard hud_hide_multiplayer_scoreboard hud_suit_menu hud_suit_mod hud_weapon_mod hud_show_pda_map leanleft leanright

cutscene_no_player
loadLastSave
load
no_map_open
hud_show_pda_map
no_objectives_open
hud_show_multiplayer_scoreboard
hud_hide_multiplayer_scoreboard
scores
vehicle_no_seat_change_and_exit
use
v_changeseat
v_changeseat1
v_changeseat2
v_changeseat3
v_changeseat4
v_changeseat5
no_connectivity
hud_show_multiplayer_scoreboard
hud_hide_multiplayer_scoreboard);
scores
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