Campaign Documentation

Scripting Homepage

Search

Search campaign only




Game Areas

• > Campaign Index
• Battle Index
• Frontend Index

On this page

Key

Loaded in Campaign
Loaded in Battle
Loaded in Frontend

• Timer Manager
•   Campaign
•     new_campaign
•   Battle
•     new_battle
•   Frontend
•     new_frontend
•   Model Timers
•     callback
•     repeat_callback
•     remove_callback
•   Real Timers
•     real_callback
•     repeat_real_callback
•     remove_real_callback

Campaign Topics

• Campaign Index
• Campaign Script Structure
• Lua Language
• Narrative System
• Scripted Events

Game Code Interfaces

• CampaignUI
• Cinematics
• Common
• Episodic Scripting
• Model Hierarchy
• ScriptedValueRegistry
• UIComponents

Script Interfaces

• Campaign Manager
• Core
• Campaign Cutscenes
• Campaign UI Manager
• Chapter Missions
• Convex Areas
• Global
• Infotext Manager
• Interventions
• Invasion Manager
• Mission Managers
• Movie Overlays
• Narrative Events
• Navigable Tours
• Objectives Manager
• Payload String Constructor
• Random Army Manager
• Script Messager
• Scripted Tours
• Text Pointers
• > Timer Manager
• Topic Leader
• Unique Table
• Validate

Data Interfaces

• Campaign Custom Starts
• Faction Intro
• Narrative
• Narrative Event Templates
• Narrative Query Templates
• Narrative Trigger Templates

Timer Manager

The timer manager object provides library support for calling functions with a time interval i.e. waiting one second before calling a function. It is loaded in all game modes and provides similar but not identical functionality in each.

It is rare for game scripts to need direct access to the timer manager. The timer manager is automatically created as the script libraries are loaded, and both the battle_manager and campaign_manager provide pass-through functions to the timer manager which game scripts typically use instead of calling the timer manager directly. For the campaign these functions are documented in the Timer Callbacks section of this documentation, and in battle they are documented here: Timer Callbacks.

Direct access to the timer manager might be more useful for frontend scripts, but they are rarer in themselves. The core function core:get_tm can be used to get a handle to the timer manager after it has been created.

Loaded in Campaign
Loaded in Battle
Loaded in Frontend

The campaign construction function timer_manager:new_campaign is automatically called by the campaign_manager during the loading sequence (when the WorldCreated model event is received), so there should be no need for client scripts to call it.

The mechanics of the underlying campaign model timing system is very different to the equivalent system in battle. As such, the campaign constructor provides versions of timer_manager:callback, timer_manager:repeat_callback and timer_manager:remove_callback which are different from those provided in battle. The usage of the campaign version of these functions is the same as for battle, with the key difference that model time in campaign is expressed in seconds in campaign and milliseconds in battle. Real Timers use milliseconds in all game modes.

During the end-turn sequence the update rate of the campaign model can accelerate wildly. This will cause a function registered to be called after five seconds to happen near-instantly during the end turn sequence, for example. To ameliorate this effect, the timer manager will automatically check the real world time once the interval has completed. If the real world time is less than would be expected then the callback is retried repeatedly until the real world interval has elapsed. This behaviour is only active in singleplayer mode as it would cause desyncs in multiplayer.

The battle-specific constructor timer_manager:new_battle is automatically called by the battle_manager when it is created, so there should be no need for client scripts to call it.

The mechanics of the underlying battle model timing system is very different to the equivalent system in campaign. Therefore, the battle constructor provides versions of timer_manager:callback, timer_manager:repeat_callback and timer_manager:remove_callback which are different from those provided in campaign. The usage of these functions is the same in battle and campaign, with the key difference that model time in campaign is expressed in seconds in campaign and milliseconds in battle. Real Timers use milliseconds in all game modes.

The frontend-specific constructor timer_manager:new_frontend is automatically called in lib_header.lua as it's loaded, so there should be no need for client scripts to call it.

There is no game model to provide timer functionality in the frontend, so only the real timer is available. The frontend-specific constructor creates timer_manager:callback, timer_manager:repeat_callback and timer_manager:remove_callback functions but these remap to timer_manager:real_callback, timer_manager:repeat_real_callback and timer_manager:remove_callback respectively.

Model timers are synchronised to the game model in campaign and battle. They are the main timers used by game scripts. Both the campaign manager and battle manager provide pass-through interfaces to the functionality documented here - see Timer Callbacks (campaign) and Timer Callbacks (battle). It is intended that game scripts call these pass-through functions rather than the timer manager itself.

When a callback is created with an interval of one second, then the callback function would be called as part of a model update where at least one second of model time has elapsed. This means:

• Model timers are confined to the resolution of the game model update, which is currently between 100ms and 200ms. A model timer callback with an interval of 250ms, for example, would not be called until the following model tick, at 300-400ms after the callback was created.
• Model updates will speed up and slow down in battle if the player changes their battle speed, and also speed up a lot during the end turn sequence in battle. Model updates are also stopped when the game is paused. For these reasons a model timer callback of one second cannot be relied on to trigger after one second has passed in the real world. See Real Timers for callback functions linked to a timer synchronised to real time.
• As model updates are synchronised between all clients in a multiplayer game, so too are model timers.
• There is no game model present in the frontend, so only real timers are available. The functions timer_manager:callback, timer_manager:repeat_callback and timer_manager:remove_callback are available in the frontend but will redirect to the real timer equivalents.

It is strongly recommended that game scripts rely on model timers as their primary mode of script timing, and only use real timers in certain specific situations, usually to do with UI manipulation.

Real timers are synchronised to user-interface updates rather than game model updates, like Model Timers. In practice, this means:

• Real timers continue to tick and will call their callback even if model updates are paused (e.g. the game is paused in battle).
• Real timers do not change speed with the model (in battle, and also in campaign during the end-turn sequence).
• Real timers can have a resolution greater than a model tick (100-200ms).
• Real timers have a variable resolution - as the frame rate changes, so does the frequency with which real timers get checked.
• Real timers work in the frontend where no game model is present.
• Synchronicity between different clients in a multiplayer game cannot be guaranteed (and is highly unlikely to be achieved).
• Due to the lack of synchronisation between the real timer and the model, the latter may not be in a suitable state to be queried when a real timer is called.

It is strongly recommended that game scripts rely on model timers as their primary mode of script timing, and only use real timers in certain specific situations, usually to do with UI manipulation.