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 Battle loaded in battle
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

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 550

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

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 566

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

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 590

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

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 617

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

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 648

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

Returns:

  1. boolean camera is playing

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 672

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

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 691

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

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 748

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

Returns:

  1. battle_vector position

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 811

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

Returns:

  1. battle_vector target

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 820

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)
Enables some functionality of the camera after it has been disabled with camera:disable_functionality.

Parameters:

1

string

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

Returns:

  1. nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 896

camera:disable_functionality(string functionality)
Disables some camera functionality.

Parameters:

1

string

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

Returns:

  1. nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 927

Back to top

Miscellaneous

camera:change_depth_of_field(
  number transition duration,
  [number focus distance],
  [number focal length],
  [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. If this is not specified then the default focus distance is used.

3

number

optional, default value=nil

Focal length. This must be specified if focus distance is supplied.

4

number

optional, default value=nil

Blur size. This must be specified if focus distance is supplied.

Returns:

  1. nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 961

camera:fade(boolean to black, number transition duration)
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.

Returns:

  1. nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 993

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

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 1029

camera:enable_shake()
Enables camera shaking.

Returns:

  1. nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 1048

camera:disable_shake()
Disables camera shaking.

Returns:

  1. nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 1058

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

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 1068

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

defined in ../../common/EmpireBattle/Source/BattleScript/BattleEditorScriptInterface.cpp, line 1083

Last updated 25/08/2021 12:07:50