Locomotion Group Editor (Pre 3.5)

Obsolete

Locomotion Groups have been replaced by BSpaces since SDK release 3.5

Locomotion Group Editor

The Locomotion Group Editor (LMG Editor), is a tool tailored to create LMG animations in a more interactive way than having to write the .lmg xml files by hand. For more information on what LMG animations are and what are they used for, please refer to the Locomotion Groups documentation.

Panels of the LMG Editor

Menu Title

Description

File

Load LMG

Loads an existing .lmg animation into the editor.

Save LMG

Save the current edited animation into an .lmg file.

Load Character

Load a different character to preview the currently edited lmg animation. Loading a different character will change the available animations in the "Animations" panel

Edit

Undo

Undos the last option.

Redo

Redos the last option.

Options

Overlay parameter values

When an lmg is being played in the "Locomotion Preview" viewport, it will overlay the values for each of the possible parameters of the blend space.

Overlay animation weights

When an lmg is being played in the "Locomtion Preview" viewport, it will overlay the blend weights of all the animations that make up the lmg.

Blend Code Panel

Blend code selection is the basis for an lmg animation. The blend code controls what an lmg is capable of doing, the number and type of animation assets it requires, the blendspace parameters it will use...

Take a look at the Locomotion Groups document for a list of currently supported blend codes and information on what each of them does. Also in the Locomotion Groups document are details on how to add custom blend code support to the LMG Editor.

Caps Code Panel

Upon selecting a blend code, the caps code dropdown lists all the possible caps code for that specific blend code. Caps codes are used by the animation graph, most importantly to describe the type of motion the lmg is describing (run, walk, idle to move, move to idle, idle rotate).

Animations Panel

The animations panel shows a list of all the animations that can be used to compose lmgs for the current loaded character.

Filtering animations by name

Animations can be filtered by name by entering keywords in input box. Multiple keywords can be used by separating them with a space. A minus symbol can be used before a keyword to hide all animations that contain the keyword.

Eg. The filter "run fast -relaxed" displays only animations that contain the words "run" and "fast", but not "relaxed" in their name.

Use the Reset button to clear a filter.

When selecting an animation it will be previewed in the "Animation Preview Panel"

Animations in the Animation Panel can be dragged and dropped into any of the "Slots Panels".

Locomotion Preview Panel

The Locomotion Preview Panel is a viewport that displays the currently edited lmg animation played on the currently loaded character. If no animation is played, it probably means that the current lmg is not valid.

Animation Preview Panel

The Animation Preview Panel will display the currently selected animation in the "Animations Panel" list.

Slots Panel

The slots panel is composed of a list of slots. The number and type of slots depends on the blend code for the current lmg, specified in the "Blend Code Panel".

Each slot contains the name of the slot, which tries to convey the type of motion that the slot expects to hold, the animation name for the slot, and a status check.

Eg. An animation slot named "forward" may indicate that it requires an animation with forward movement to be placed in that slot for the lmg to work as intended.

To add an animation to an animation slot, type in the name of the animation in the slot, or alternatively, drag and drop the animation name from the "Animations Panel" to the slot.

When an animation name is in a slot, the status indicator will display in green if the animation is valid for that slot.

If the status indicator is red, hovering over it with the mouse will display a tooltip indicating what's wrong with the animation

All slots must be valid (green) for an lmg to be valid.

Test Panel

Depending on the blend code, a different number of blend space parameters are used to drive the motion of an lmg animation.

The test panel displays a series of controls to modify the blend space parameters used by the current blend code, and preview the results in the "Locomotion Preview Panel".

To see the numeric value of all the blend space parameters enable the "Overlay Parameter Values" option.

Motion Combinations Panel (Advanced)

The motion combinations panel is used to run an animation on top of the current lmg animation. It has been mainly used to create locomotion groups that differ only slightly without having to redo all the base assets.

Eg. If you need several lmgs to share the same base assets (forward, left, right, back...) and have only the upper body to change between them (holding rifle, pistol...) then we can specify an animation asset to change the upper body position and specify it as a motion combination for each lmg.

Note that this can also be accomplished with having animations on upper layers, but this way it's considered by the animation system as a single animation.

To add a motion combination the editing must be enabled. It is by default disabled as it's not the most common workflow to create lmgs with motion combinations.

Once editing is enabled, motion combination slots can be created or deleted with the "+" and "-" buttons respectively.

To add a motion combination animation to a slot, type the name of the animation, or drag and drop the animation name from the "Animations Panel"

Adding New Blend Codes to the LMG Editor (Advanced)

It may be necessary for specific projects to create their own lmg blend codes by modifying the CryAnimation code. This implies creating a new four letter blend code (like "STF1") and a set of blending rules for the animations it contains. Once that is done, it may be useful to be able to create and preview animations for those asset types in the lmg editor.

To do so, it is necessary to edit the "LmgEditor.xml" file that can be found inside the "Editor" folder.

Please also note that the LmgEditor.xml file is parsed each time the Lmg Editor is opened, so it's not necessary to restart Sandbox each time this file gets modified, it's enough just to restart the LMG Editor.

The general structure of this xml is the following:

<lmg_editor>
    <blend_types>
    ...
    </blend_types>

    <slots>
    ...
    </slots>

    <caps_codes>
    ...
    </caps_codes>

    <tests>
    ...
    </tests>
</lmg_editor>

For a new blend code to appear in the "Blend Codes Panel" you need to add a new entry to the <blend_types> in the xml file.

A blend type has the following structure:

<blend_type code="STF1" name="Strafe (STF1)" description="4 directions 1 speed" >
    <caps_code_ids>
        <caps_code_id>run</caps_code_id>
        <caps_code_id>walk</caps_code_id>
    </caps_code_ids>
    <slot_ids>
        <slot_id>forward</slot_id>
        <slot_id>left</slot_id>
        <slot_id>back</slot_id>
        <slot_id>right</slot_id>
    </slot_ids>
    <test_ids>
        <test_id>strafe_test</test_id>
    </test_ids>
</blend_type>
  • The code property is the four letter code used in CryAnimation.
  • The name property is the human readable name that will be displayed in the "Blend Codes Panel" dropdown menu.
  • Description should give an indication of what this locomotion group purpose is.
  • Caps code holds a list of possible caps codes for this blend code. These are just ids, the actual caps code definitions are specified later in the xml.
  • Slots hold a list of slot ids that this lmg will have available. These are also just ids, the actual slot definitions are specified later in the xml. If possible, reuse already existing slot ids instead of creating new slot specifications.
  • The test tag will hold the id of the test interface that will be used to create the "Test Panel". The test definitions are near the end of the file. There's a generic test id called "general_sliders" that will create a slider for each possible blendspace parameter in the test interface.

Slots

Slots are defined in the <slots> section of the xml. The following is a sample of a slot definition.

<slot id="forward_fast" name="Forward Fast" description="" position="0,1,0" />
  • The id property is used to index the slot in the blend_type and to identify the slot. It must be unique.
  • The name property is the human readable name that will be displayed next to the slot.
  • The description property contains text that will be displayed when hovering over a slot name.
  • The position property contains the values saved for the position property in the <example> nodes of the final lmg file. This property is not editable in the lmg editor, and it's only used by certain lmg types.

It is best to reuse current slots whenever possible instead of creating new ones.

Caps Code

Caps codes are defined in the <caps_codes> section of the xml. Here is a sample of a definition for a caps code:

<caps_code id="run" name="Run" code="RUN_" />
  • The id property is the id for the caps code, as used from the blend_type.
  • The name property is the human readable name that will be displayed in the Caps Code Panel dropdown list.
  • The code property is the four letter code used to export the caps code and it's the value that will get saved with the lmg file.

Tests

Tests are used to specify the controls that will appear in the Test Panel, and how the values in those controls are mapped to the blendspace parameters for an lmg, so that the user is able to play with the controls and modify the current animation while in the editor.

Test are defined in the <tests> section of the xml and their structure resembles the following:

<test id="strafe_ud_test" name="Strafe Up/Downhill Test" >
 ... controls ...
</test>
  • The test id is used in the blend_type structure to identify what test to use. The value must be unique.
  • The name property is the human readable name of the test.
  • The controls section of the test specify the controls, their positions and their mappings to the blendspace parameters.

There are four supported controls currently:


joystick


slider


horizontal_slider


vertical_slider

The common properties for each control are:

Property

Description

name

Human readable name for the control.

x

Horizontal position of the control, 0 being the left of the panel.

y

Vertical position of the control, 0 being the top of the panel

width

Horizontal size of the control.

height

Vertical size of the control.

default_x

Initial x value for the control.

default_y

Initial y value for the control.

The common properties for sliders are:

Property

Description

min_x

The minimum x value for the control.

min_y

The minimum y value for the control.

max_x

The maximum x value for the control.

max_y

The maximum y value for the control.

The properties specific to joysticks are:

Property

Description

length_min

The value for the joystick as measured at the inner circle.

length_max

The value for the joystick as measured at the outer circle.

On top of that, each control can specify how to map their state to lmg blendspace parameters.

This is specified in the mappings section:

For example, the following mapping definition:

<mapping what="X" to="TravelSlope" />

... maps the current x value of a control to the TravelSlope parameter.

The following values are acceptable for the "what" property.

The following values are for slider type controls:

Value

Description

X

Sets the x value directly to the blend space parameter.

X_TIMES_PARAM_RANGE

Sets the x value multiplied by the range of the parameter to the blend space parameter.

MAP_X_TO_PARAM_RANGE

Sets the normalised x value [0,1] multiplied by the range of the parameter to the blend space parameter.

X_TIMES_ASSET_RANGE

Sets the x value multiplied by the range of the asset for that parameter to the blend space parameter.

MAP_X_TO_ASSET_RANGE

Sets the normalised x value [0,1] multiplied by the range of the asset for that parameter to the blend space parameter.

Y

Sets the y value directly to the blend space parameter.

Y_TIMES_PARAM_RANGE

Sets the y value multiplied by the range of the parameter to the blend space parameter.

MAP_Y_TO_PARAM_RANGE

Sets the normalised y value [0,1] multiplied by the range of the parameter to the blend space parameter.

Y_TIMES_ASSET_RANGE

Sets the y value multiplied by the range of the asset for that parameter to the blend space parameter.

MAP_Y_TO_ASSET_RANGE

Sets the normalised x value [0,1] multiplied by the range of the asset for that parameter to the blend space parameter.

The following values are for joystick type controls:

Value

Description

LENGTH_TIMES_PARAM_RANGE

Sets the normalised length value [0,1] multiplied by the range of the parameter to the blend space parameter.

LENGTH_TIMES_ASSET_RANGE

Sets the normalised length value [0,1] multiplied by the range of the asset for that parameter to the blend space parameter.

LENGTH_TIMES_RANGE

Sets the normalised length value [0,1] multiplied by the range of the joystick as specified in the length_min and length_max properties to the blend space parameter.

ANGLE_Y_AXIS

Sets the value in radians between the vector from the center of the joystick to the knob position relative to the positive Y axis (up) to the blend space parameter.

The following values are the target blend space parameters that can be specified in the "to" property of the mapping. They map directly to their corresponding blend space parameter as defined in the EMotionParamID enum.

  • TravelAngle
  • TravelDistScale
  • TravelSpeed
  • TravelDist
  • TravelSlope
  • WeightShift
  • TurnSpeed
  • TurnAngle
  • Duration
  • Curving
  • Height
  • Scale