Camera

The camera object provided by the battle model provides an interface to query and move the camera. The camera interface also provides functions to query the state of an ambush controller, should the current battle be an ambush battle.

Loaded in Campaign Loaded in Campaign
Loaded in Battle Loaded in Battle
Loaded in Frontend Loaded in Frontend
Back to top

Creation

A handle to the camera can be created by calling the battle:camera function on the battle interface. This function returns a handle to the battle camera.

Back to top

Usage

Once a handle to a camera object is obtained, functions may be called on it to query or modify its state in the following form.

Example - Specification:

<object_name>:<function_name>(<args>)

Example - Creation and Usage:

local cam = bm:camera()
cam:look_at(v(0, 0, 0))        -- calling a function on the object once created
Back to top

Ambushes

The battle camera provides a number of functions for querying and modifying ambush controllers. Use of these function should allow for querying and control of ambush battles.

camera:is_ambush_controller_executing()
Returns whether an ambush controller is currently executing. This will return true in an ambush battle, prior to the ambushing army launching their attack.

Returns:

  1. boolean is ambush controller active

camera:allow_user_to_skip_ambush_intro(boolean user can skip)
Sets whether the player can skip the ambush intro with the ESC key. By default this is disabled, but it may be desirable to enable this in certain scripted circumstances.

Parameters:

1

boolean

user can skip

Returns:

  1. nil

camera:teleport_defender_when_ambush_intro_skipped(boolean teleport defender)
Sets whether the ambush defender is teleported to the end of their movement path when the ambush intro is skipped. By default this is disabled, but it may be desirable to enable this in certain scripted circumstances.

Parameters:

1

boolean

teleport defender

Returns:

  1. nil
Back to top

Camera Movement Files

camera:play(string file path, boolean loop)
Plays a specified camera file. These are files that specify camera positions in a specific format. Only for use in specific circumstances.

Parameters:

1

string

file path

2

boolean

loop

Returns:

  1. nil

camera:stop([boolean stop instantly])
Stops a playing camera file that was started with camera:play.

Parameters:

1

boolean

optional, default value=false

stop instantly

Returns:

  1. nil

camera:is_playing()
Returns whether a scripted camera started with camera:play is currently playing.

Returns:

  1. boolean camera is playing
Back to top

Camera Position and Movement

camera:look_at(
  battle_vector target,
  number transition time,
  [number starting angle],
  [boolean linear movement],
  [number target fov]
)

Turns the camera to face a specified battle_vector position over a specified time. A starting camera bearing, a transition mode and a target field of view may optionally be specified.

Parameters:

1

battle_vector

Look-at target position.

2

number

Transition time in seconds. Supply a negative number to have the function determine an appropriate transition time.

3

number

optional, default value=nil

Starting angle. If no angle is specified the camera's current facing is used instead (this is recommended).

4

boolean

optional, default value=false

Linear movement style. If enabled the camera will turn with a constantly velocity. If disabled the rate of camera rotation will accelerate and then decelerate.

5

number

optional, default value=0

Field of view at the end of the transition. If set to 0 the default field of view will be used, and if set to negative the current field of view will be kept.

Returns:

  1. nil

camera:move_to(
  battle_vector position,
  battle_vector target,
  number transition time,
  [boolean linear movement],
  [number target fov],
  [boolean use command queue]
)

Moves the camera to a specified position, facing a specified target, over a specified time. Both positions are supplied as battle_vector objects. A starting camera bearing, a transition mode and a target field of view may optionally be specified.

Parameters:

1

battle_vector

end position of camera after transition.

2

battle_vector

Look-at target of camera after transition.

3

number

Transition time in seconds. Supply a negative number to have the function determine an appropriate transition time.

4

boolean

optional, default value=false

Linear movement style. If enabled the camera will move with a constantly velocity. If disabled the camera will accelerate and then decelerate.

5

number

optional, default value=0

Field of view at the end of the transition. If set to 0 the default field of view will be used, and if set to negative the current field of view will be kept.

6

boolean

optional, default value=true

Setting this to false allows the camera to start moving when the game is paused, but the camera movement will not appear in replays.

Returns:

  1. nil

camera:position()
Returns the current position of the camera.

Returns:

  1. battle_vector position

camera:target()
Returns the current look-at target of the camera.

Returns:

  1. battle_vector target
Back to top

Disabling Camera Functionality

Certain aspects of camera functionality can be disabled and re-enabled using the functions in this section. All functionality is enabled by default. The functionality to enable or disable is specified as one of the following strings.

Keys:

  • KEYS_HEIGHT_UP_DOWN

  • KEYS_PAN_LEFT_RIGHT

  • KEYS_PITCH_UP_DOWN

  • KEYS_FORWARD_BACKWARDS

  • KEYS_STRAFE_LEFT_RIGHT

  • KEYS_FOLLOW_CAMERA

  • KEYS_ZOOM_CAMERA

  • KEYS_CONTEXT_CAMERA

  • KEYS_ALL_FUNCTIONS

Mouse:

  • MOUSE_HEIGHT_UP_DOWN

  • MOUSE_PAN_LEFT_RIGHT

  • MOUSE_PITCH_UP_DOWN

  • MOUSE_FORWARD_BACKWARDS

  • MOUSE_STRAFE_LEFT_RIGHT

  • MOUSE_FOLLOW_CAMERA

  • MOUSE_ZOOM_CAMERA

  • MOUSE_CONTEXT_CAMERA

  • MOUSE_ALL_FUNCTIONS

Edge:

  • EDGE_HEIGHT_UP_DOWN

  • EDGE_PAN_LEFT_RIGHT

  • EDGE_PITCH_UP_DOWN

  • EDGE_FORWARD_BACKWARDS

  • EDGE_STRAFE_LEFT_RIGHT

  • EDGE_FOLLOW_CAMERA

  • EDGE_ZOOM_CAMERA

  • EDGE_CONTEXT_CAMERA

  • EDGE_ALL_FUNCTIONS

UI:

  • UI_HEIGHT_UP_DOWN

  • UI_PAN_LEFT_RIGHT

  • UI_PITCH_UP_DOWN

  • UI_FORWARD_BACKWARDS

  • UI_STRAFE_LEFT_RIGHT

  • UI_FOLLOW_CAMERA

  • UI_ZOOM_CAMERA

  • UI_CONTEXT_CAMERA

  • UI_ALL_FUNCTIONS

  • CAMERA_ALL_FUNCTIONS

camera:enable_functionality(string functionality, boolean enable, [boolean bypass command queue])

Enables or disables some functionality of the camera.

Parameters:

1

string

Functionality to enable - see the list of valid functionality strings given above.

2

boolean

Enables the functionality. Supply false to disable the the functionality instead.

3

boolean

optional, default value=false

Bypasses the command queue. If this is set to true the command is processed immediately, including when paused, but the command will not be reproduced in multiplayer or in a battle replay.

Returns:

  1. nil
Back to top

Miscellaneous

camera:change_depth_of_field(
  number transition duration,
  [number focal depth],
  [number focal width],
  [number blur size]
)
Changes the depth of field of the camera.

Parameters:

1

number

Transition duration in seconds.

2

number

optional, default value=nil

Focus distance.

3

number

optional, default value=nil

Focal length.

4

number

optional, default value=nil

Blur size.

Returns:

  1. nil

camera:fade(boolean to black, number transition duration, [boolean bypass command queue])

Fades the camera over a supplied duration from picture to black, or from black to picture.

Parameters:

1

boolean

Fade to black. The screen will fade from picture to black if this is set to true, and from black to picture if it's set to false.

2

number

Transition duration in seconds.

3

boolean

optional, default value=false

Bypass the command queue, initiating the fade immediately.

Returns:

  1. nil

camera:change_height_range(number min height, number max height)
Changes the minimum/maximum permitted altitude of the camera above the ground. If negative values are supplied the game default values are used.

Parameters:

1

number

Minimum altitude in metres.

2

number

Maximum altitude in metres.

Returns:

  1. nil

camera:enable_shake()
Enables camera shaking.

Returns:

  1. nil

camera:disable_shake()
Disables camera shaking.

Returns:

  1. nil

camera:enable_anchor_to_army()
Enables the anchor which prevents the camera from being moved too far away from the players forces.

Returns:

  1. nil

camera:disable_anchor_to_army()
Disables the anchor which prevents the camera from being moved too far away from the players forces.

Returns:

  1. nil
Last updated 7/9/2024 11:45:05 AM