From Blue Mars Developer Guidebook

Current revision (unreviewed)

There are security restrictions on this article

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

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).

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"

Action Filters

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

Functions

EnableActionFilter(name, enable): turn an action filter on/off; name - name of the action map filter; enable - boolean indicating whether to enable or disable the filter

IsActionFilterEnabled(name): return value - boolean true if filter is enabled, false if not; name - string name of the action filter; by Avatar Reality , last modified on 1/15/2008; example - none

CreateActionFilter(name): by Avatar Reality; status - in-progress

Predefined Filters

Currently there is no way to define new filters.

These are the action filters hardcoded in 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

ActionMap Manager

From Blue Mars Developer Guidebook

Contents

Action Maps

Overview

Example

Functions

Console & Debugging

Standard Action Maps

debug

default

player

vehicle

seavehicle

helicopter

landvehicle

vtol

Adding Action Maps

Actions

XML Definition

Activation Modes

Modifiers

List of Key Names

Key Gestures

Mouse Gestures

Action Filters

Functions

Predefined Filters

Views

Personal tools

Main

Guidebook

Help

References

Search

Toolbox