Movement post thumbnail image

Under Construction

This article is under construction.

Movement in OpenBOR is designed to be simple and intuitive. Command mappings are configured by default to behave like most side scrolling games with velocities and physics all handled natively. All you need to do is provide some walking animations and off you go. The engine also employees a fallback scheme, playing more specialized animations if available and falling back to more basic animation otherwise. Movement speed for walking and running are adjustable at the model level.


As mentioned above, OpenBOR comes with a set of animations pre-mapped to player controls and AI behavior. Add the appropriate animation depending on what kind of movement behaviors you need.



Walk is the most basic walking animation. Entities play Walk whenever they are walking under player or AI control and no other walking animation is available. Don’t forget to include a loop in your walk animations (unless you want the last frame to play continuously).

Entities walking backward (opposite their current direction) with no Backwalk animation will play Walk animated in reverse order. Normally only AI entities can walk backward, but it is possible for players to do so with certain configurations (see below).

You may add multiple walk animations starting with walk2 (walk2, walk3, etc.), and then set up ranges for each. When hostile entities are in range of a Walk animation, that animation will play in place of the others. If multiple ranges overlap, lower numbered walk animations take priority.

Tip: Use the extra walk animations to easily give your characters dynamic behavior such as walking causally when alone and moving with a guarded shuffle close to enemies.

anim walk

    loop    1
    delay    8
    offset    60 98
    bbox.position.x 49
    bbox.position.y 43
    bbox.size.x 18
    bbox.size.y 55

    frame    data/chars/ax/walk_0.png
    frame    data/chars/ax/walk_1.png
    frame    data/chars/ax/walk_2.png
    frame    data/chars/ax/walk_3.png
    frame    data/chars/ax/walk_4.png
    frame    data/chars/ax/walk_5.png



Backwalk plays while entities are walking in the opposite direction they are facing. AI controlled entities always face the nearest hostile target (i.e. enemies vs. players) by default, so adding this animation can give them more visually appealing movement.

You may add multiple Backwalk animations (backwalk2, backwalk3, etc.) following the same logic as walk.


OpenBOR includes a robust native jumping system. In most cases you don’t need to do anything at all other than add your jumping and jumping attack animations. Use the following animations and properties to set up dynamic and nice looking jumps.


anim jump

Defining a JUMP animation in model text enables jump ability for the entity. When jumping, the entity plays JUMP from liftoff until touching the “ground” again. If the JUMP animation does not have a loop, the last frame plays until landing. Jumping trajectory and distance are controlled with Jump Height and jumpspeed properties (see below).

Jumping is mapped to the Jump button by default. During a jump players may execute one or more jump attacks (see below).

If available, AI controlled entities will use JUMP to ascend platforms and traverse pits. This is controlled by the JUMP animation’s range setting.

  • Distance to the obstruction must be equal or less than the minimum range setting.
  • The height of wall or platform must be within maximum range setting.
  • In the case of a pit, the total width must be equal or less than maximum range setting.

Assuming these conditions are met, the AI will jump.

Tip: Set up ranges carefully compared to the model’s jump trajectory settings. As an example, setting up short jumping trajectory with long ranges could lead to entities stupidly jumping into pits or repeating futile attempts to get onto a platform.


anim jumpdelay

If available, plays immediately before a jump initiates. Entity leaves ground and plays JUMP when this animation completes. Used mainly to create a standing to jump transition. The typical example is an entity crouching briefly to prepare for liftoff.

This animation only plays for native jumping. Use visual jump start frames frames immediately before animations with jumpframe or scripted jumps.


anim jumpland

If available, plays immediately after a jump lands. The typical example is an entity crouching briefly to absorb the impact of landing.

This animation only plays for native jumping. Use landframe or for scripted jumps, falls, etc.


anim forwardjump

If available, replaces JUMP when entity jumps while moving.


anim runjump

Running jump trajectory is a multiplier of the model’s existing jump trajectory settings. The multiplier is controlled by model’s running property.

If available, replaces JUMP when entity jumps while running. If players have running configured but no RUNJUMP, then JUMP or FORWARDJUMP plays instead, but running jump trajectory still applies.

If available AI uses RUNJUMP with logic identical to JUMP. If the obstacle to traverse falls with range of both JUMP and RUNJUMP, the AI prioritizes JUMP. Note the AI does not require a “run up” before executing a running jump.

Tip: Setting up both JUMP and RUNJUMP gives the AI more adaptive jumping capabilities just like a player controlled entity. With properly configured ranges the AI will use a normal jump to clear shorter distances, and a running jump when more height or reach is needed.

anim walkoff

If available, plays when walking off a ledge (walls, platforms, holes, etc.). Not technically a jump. You will need to use landframe to add a landing sequence.


Global jump configuration. Unless noted otherwise, global properties are part of the models.txt file.

Default Jump Height​

jumpheight <float>

# Default
jumpheight 4.0

Models.txt global default for all model jump heights. Also affects legacy Throw Distance.

No Air Cancel​

noaircancel <int>

# Default
noaircancel 0

Controls player air canceling.

  • 0: Players can cancel any air attack with a different air attack (ex. Jumpattack -> Jumpattack2).
  • 1: Players can cancel air attacks after the animation is complete.
  • 2: Players cannot cancel air attacks.


Model header properties.

Air Control​

air_control <flags>

# Default
air_control none

Configures player control options when jumping (for this model). Accepts one or more of the following flags in any order. Note, if used, you must include all flags you want to enable.

  • none – No configuration. Has no effect if any other flags are set.
  • jump_disable – Entity cannot jump at all.
  • jump_turn – Change direction in air with Left/Right.
  • jump_x_adjust – Change horizontal velocity in air with Left/Right if already moving on horizontal axis.
  • jump_x_move – Change horizontal velocity in air with Left/Right any time.
  • jump_x_stop – Lose horizontal momentum when not holding Left/Right.
  • jump_y_stop – Lose vertical momentum when not holding Jump (IOW Mario Brothers style jump height control).
  • jump_z_adjust– Change lateral velocity in air with Up/Down if already moving on lateral axis.
  • jump_z_initial – Can initiate a lateral jump.
  • jump_z_move – Change lateral velocity in air with Up/Down any time.
  • jump_z_stop – Lose lateral momentum when not holding Up/Down.
  • walkoff_turn – Same as jump_turn, for walkoff.
  • walkoff_x_adjust – Same as jump_x_adjust, for walkoff.
  • walkoff_x_move – Same as jump_x_move, for walkoff.
  • walkoff_x_stop – Same as jump_x_stop, for walkoff.
  • walkoff_z_adjust – Same as jump_z_adjust, for walkoff.
  • walkoff_z_move – Same as jump_z_move, for walkoff.
  • walkoff_z_stop – Same as jump_z_stop, for walkoff.

Example: Player can control jump height by how long they hold the jump key, jump laterally, and turn around in the air when jumping.

air_control jump_turn jump_y_stop jump_z_initial

Script accessible as air_control model property. Use following bitmask constants:

  • openborconstant(“AIR_CONTROL_NONE”) – Assign directly (not a mask) to reset all flags off.
  • openborconstant("AIR_CONTROL_JUMP_DISABLE”)
  • openborconstant("AIR_CONTROL_JUMP_TURN”)
  • openborconstant("AIR_CONTROL_JUMP_X_ADJUST”)
  • openborconstant("AIR_CONTROL_JUMP_X_MOVE”)
  • openborconstant("AIR_CONTROL_JUMP_X_STOP”)
  • openborconstant("AIR_CONTROL_JUMP_Y_STOP”)
  • openborconstant("AIR_CONTROL_JUMP_Z_ADJUST”)
  • openborconstant("AIR_CONTROL_JUMP_Z_INITIAL”)
  • openborconstant("AIR_CONTROL_JUMP_Z_MOVE”)
  • openborconstant("AIR_CONTROL_JUMP_Z_STOP”)
  • openborconstant("AIR_CONTROL_WALKOFF_TURN”)
  • openborconstant("AIR_CONTROL_WALKOFF_X_ADJUST”)
  • openborconstant("AIR_CONTROL_WALKOFF_X_MOVE”)
  • openborconstant("AIR_CONTROL_WALKOFF_X_STOP”)
  • openborconstant("AIR_CONTROL_WALKOFF_Z_ADJUST”)
  • openborconstant("AIR_CONTROL_WALKOFF_Z_MOVE”)
  • openborconstant("AIR_CONTROL_WALKOFF_Z_STOP”)

Equal Air Pause​

Pausing behavior when hitting another entity with attacks while in the air. Attacks normally add their pause effect to attacking entity if the entity is not already paused longer than the attack’s pause, or any time attacking entity is in the air.

equalairpause <int>

# Default
equalairpause 0
  • 0 = Hit pause added any time entity is in the air.
  • 1 = Follow same rules as an entity at base height.

Jump Speed​

jump_speed <float>

# Default: Special, see below.

X Axis toss velocity when jumping forward. Default value is the model’s speed or 1.0, whichever is higher.

Jump Height​

jump_height <float>

# Default: Special, see below.

Y axis toss velocity when entity jumps. For backward compatibility with BOR, Jump Height also affects the following:

  • Default animation ranges.
  • Default jumpframe velocities.
  • Y axis toss of the legacy Throw animation.
  • Y axis toss for Bomb type projectiles.

The default is controlled by global Default Jump Height property.




anim run

    loop    1
    delay    8
    offset    60 98
    bbox.position.x 49
    bbox.position.y 43
    bbox.size.x 18
    bbox.size.y 55

    frame    data/chars/ax/run_0.png
    frame    data/chars/ax/run_1.png
    frame    data/chars/ax/run_2.png
    frame    data/chars/ax/run_3.png
    frame    data/chars/ax/run_4.png
    frame    data/chars/ax/run_5.png

Animation for running or dashing. You will need to configure your model to enable running (see below). Once enabled, players are able to start running by double tapping Left or Right. AI controlled entities with chase subtype will run at distant hostile entities. An NPC will run to catch up with its distant parent.

Run Config​

run_config {flags}

run_config none

Basic running command setup. Accepts one or more of the following flags.

  • none – No running config (entity cannot run at all). Has no effect if used with other flags.
  • land – Can continue running after landing from a running jump.
  • x_left_dash_command – Running horizontal left stops if player releases direction command or animation is complete. Normally running continues until player releases a key or AI logic quits running, regardless of animation state.
  • x_left_dash_fixed – Running horizontal left always continues until animation is complete. Be careful not to use this with a looping animation. If used in conjunction with x_left_dash_command, x_left_dash_fixed takes priority.
  • x_left_enabled – Running horizontal left is enabled. Entity cannot run at all in this direction if not enabled.
  • x_left_initial – Entity can start running horizontal left if not running already.
  • x_right_dash_command – Same as x_left_dash_command, for horizontal right
  • x_right_dash_fixed – Same as x_left_dash_fixed, for horizontal right.
  • x_right_enabled – Same as x_left_right_enabled, for horizontal right.
  • x_right_initial – Same as x_left_initial, for horizontal right.
  • z_down_dash_command – Same as x_left_dash_command, for lateral down.
  • z_down_dash_fixed – Same as x_left_dash_fixed, for lateral down.
  • z_down_enabled – Same as x_left_right_enabled, for lateral down.
  • z_down_initial – Same as x_left_initial, for lateral down.
  • z_up_dash_command – Same as x_left_dash_command, for lateral up.
  • z_up_dash_fixed – Same as x_left_dash_fixed, for lateral up.
  • z_up_enabled – Same as x_left_right_enabled, for lateral up.
  • z_up_initial – Same as x_left_initial, for lateral up.

This is example is a typical running configuration. The entity can start and continue running left or right, and can veer up/down if already running.

run_config x_left_enabled x_left_initial x_right_enabled x_right_initial z_down_enabled z_up_enabled

Combined with a non-looping run animation, this example creates a fixed left or right dash/quickstep.

run_config x_left_enabled x_left_initial x_left_dash_fixed x_right_enabled x_right_initial x_right_dash_fixed

Accessible to script as a model property (MODEL_PROPERTY_RUN_CONFIG_FLAGS) using the following bitmask constants:

  • openborconstant(RUN_CONFIG_NONE)
  • openborconstant(RUN_CONFIG_LAND)
  • openborconstant(RUN_CONFIG_X_LEFT_DASH_COMMAND)
  • openborconstant(RUN_CONFIG_X_LEFT_DASH_FIXED)
  • openborconstant(RUN_CONFIG_X_LEFT_ENABLED)
  • openborconstant(RUN_CONFIG_X_LEFT_INITIAL)
  • openborconstant(RUN_CONFIG_X_RIGHT_DASH_COMMAND)
  • openborconstant(RUN_CONFIG_X_RIGHT_DASH_FIXED)
  • openborconstant(RUN_CONFIG_X_RIGHT_ENABLED)
  • openborconstant(RUN_CONFIG_X_RIGHT_INITIAL)
  • openborconstant(RUN_CONFIG_Z_DOWN_DASH_COMMAND)
  • openborconstant(RUN_CONFIG_Z_DOWN_DASH_FIXED)
  • openborconstant(RUN_CONFIG_Z_DOWN_ENABLED)
  • openborconstant(RUN_CONFIG_Z_DOWN_INITIAL)
  • openborconstant(RUN_CONFIG_Z_UP_DASH_COMMAND)
  • openborconstant(RUN_CONFIG_Z_UP_DASH_FIXED)
  • openborconstant(RUN_CONFIG_Z_UP_ENABLED)
  • openborconstant(RUN_CONFIG_Z_UP_INITIAL)

Run Speed​

run.speed.x {value}

run.speed.x 0.0

Movement speed while running, in pixels per engine update (same as speedf).

Run Jump​

run.jump.x {mutiplier}

run.jump.x 1.0

Distance achieved during a running jump. The value is a multiplier applied to normal jumping X velocity.

run.jump.y {Y velocity}

# Same as normal jump height

Height entity achieves during a running jump. Works the same as normal jump height.

General Configuration​

Use these settings to modify default behavior and customize movement to your needs.

Move Constraints​

move_constraints <flags>

#default (player)
move_constraints subject_to_basemap subject_to_gravity subject_to_hole subject_to_max_z subject_to_min_z subject_to_obstacle subject_to_platform subject_to_screen subject_to_wall

#default (Enemy, Item, NPC)
move_constraints subject_to_basemap subject_to_gravity subject_to_hole subject_to_max_z subject_to_min_z subject_to_obstacle subject_to_platform subject_to_wall

#default (Obstacle, Trap)
move_constraints subject_to_basemap subject_to_gravity subject_to_hole subject_to_max_z subject_to_min_z subject_to_platform subject_to_wall

#default (Projectile, Pshot) - Note the native projectile system modifies some move constraint flags on spawn.
move_constraints no_adjust_base subject_to_gravity subject_to_max_z subject_to_min_z

#default (Text)
move_constraints subject_to_max_z subject_to_min_z

#default (Endlevel)
move_constraints subject_to_basemap subject_to_gravity subject_to_hole subject_to_obstacle subject_to_platform subject_to_wall

#default (Panel)
move_constraints no_adjust_base subject_to_gravity

#default (Biker)
move_constraints subject_to_gravity subject_to_hole subject_to_max_z subject_to_min_z

#default (Arrow)
move_constraints no_adjust_base subject_to_gravity subject_to_max_z subject_to_min_z

Model text property that configures movement limitations in relation to stage terrain, obstacles, screen boundaries, and so on. Accepts one or more of the following flags. Note you must include all constraint flags you want for the entity. If this property is unused, each type (enemy, player, etc.) applies a set of default move constraints best suited for most game designs.

  • none – No effect if any other flag is used. Use this by itself if you want to override the model’s default configuration with all flags false.
  • no_adjust_base – Ignore changes in terrain (walls, platforms).
  • no_hit_head – Pass upward through platforms.
  • subject_to_basemap – Affected by basemaps (slopes).
  • subject_to_gravity – Affected by gravity.
  • subject_to_hole – Can fall into holes.
  • subject_to_max_z – Bound by maximum Z area.
  • subject_to_min_z – Bound by minimum Z area.
  • subject_to_obstacle – Cannot pass through obstacles.
  • subject_to_platform – Able to jump onto and be obstructed by platforms.
  • subject_to_screen – Cannot leave visible screen.
  • subject_to_wall – Cannot pass through walls.

Example: Follow the basemaps for terrain, fall normally when in air, and can’t pass through obstacles with a platform set up.

move_constraints subject_to_basemap subject_to_gravity subject_to_obstacle

Accessible to script as a model property (MODEL_PROPERTY_MOVE_CONFIG_FLAGS) using the following bitmask constants:

  • openborconstant(“MOVE_CONSTRAINT_NONE”)
  • openborconstant(“MOVE_CONSTRAINT_NO_ADJUST_BASE”)
  • openborconstant(“MOVE_CONSTRAINT_NO_HIT_HEAD”)
  • openborconstant(“MOVE_CONSTRAINT_SUBJECT_TO_HOLE”)
  • openborconstant(“MOVE_CONSTRAINT_SUBJECT_TO_MAX_Z”)
  • openborconstant(“MOVE_CONSTRAINT_SUBJECT_TO_MIN_Z”)
  • openborconstant(“MOVE_CONSTRAINT_SUBJECT_TO_WALL”)



void acting_entity = <entity pointer>;
void target_entity = <entity pointer>;

adjustwalkanimation(acting_entity, target_entity);

Force acting entity to use target for determining which alternate walking animation to play. Normally the first entity in indexed order with an alternate animation’s range determines if the alternate plays.

1 thought on “Movement”

Comments are closed.

Related Post