Data Bindings

The game exposes values to the HUD using Bindings. The HUD elements can register to a binding and receive a callback when the value changes. Bindings are indexed using a name and a type. The type is currently one of: int, string, float or bool.

Registering to a Bind

You can register a function to get called when a value gets changed. This is an example from the ammo hud panel:

bind.register("player_ammo_total", "int", function(value) {
	ammoTotalLabel.text = value;
});

Existing Binds

This is an overview of the bindings available in Empires. You can get an up to date list by typing emp_binding_list in your console.

Int

• player_mines_deployed - The amount of mines currently placed by the player
• player_ammo_current - The amount of ammo in the clip of the current weapon
• player_ammo_total - The amount of ammo in total
• player_mines_max - The maximum amount of mines the player can place
• player_ammo_clipsize - The maximum amount of ammo in a clip
• player_stamina - The stamina of the player from 0 to 100
• player_health_max - The maximum health of the player, normally 100.
• player_ammo_type - The type of ammo currently held.
• player_health - The current health of the player
• team_tickets - The amount of tickets the team of the player has
• team_tanks - The amount of vehicles the current team has on the field.
• team_tanks_max - The amount of vehicles the current team can place on the field.
• game_seconds_left - The amount of seconds left in the game.
• tickets_total - The total amount of tickets in the game.
• game_play_time_left - The amount of seconds left in the game.
• game_preparation_time_left - The amount of seconds left to prepare before the game starts.
• game_suddendeath_countdown - The amount of seconds left until sudden death.
• game_commander_freeze_left - The amount of seconds until the commander vehicle.
• game_length - The amount of seconds elapsed since the start of the game.

String

• team_name - The name of the current team. One of: brenodi, northern, spectator, unassigned, unknown.

Float

• team_res_total - The amount of res the team has.
• team_res_income - The resource income per second for the team of the player.
• player_wages - The amount of wages the current player has.

Adding a bind in C++ code

Binds usually live in either the C_EmpPlayer class, the C_EmpTeam class or the GameRules class. To create a new bind in the Player class, perform the following steps:

• Add a new bind member variable to the emp_player.h file:

  std::shared_ptr< EmpDataBinding<int> > _healthBinding;
  std::shared_ptr< EmpDataBinding<int> > _staminaBinding;
+ std::shared_ptr< EmpDataBinding<int> > _yourNewBinding;

• In the constructor implementation of the player class, create the actual binding:

  _healthBinding = EmpDataBindingManager<int>::GetBinding("player_health");
  _staminaBinding = EmpDataBindingManager<int>::GetBinding("player_stamina");
+ _yourNewBinding = EmpDataBindingManager<int>::GetBinding("your_new_binding");

• In the UpdateDataBindings function, set the actual value the bind is supposed to have:

  _healthMaxBinding->Set(GetMaxHealth());
  _staminaBinding->Set(GetStamina());
+ _yourNewBinding->Set(42);

• Your new binding should now show up in the emp_bindings_list command in the Empires console.

Choosing a Type

• For values that are strings or booleans the choice is simple, use the same type as the original value.
• If your original type is a number and it changes very frequently (multiple times per second), try to use an int if that doesn't cause big artifacts on the HUD. This makes the HUD update less often resulting in a smoother game.
• If the value changes less often or you actually need the extra precision, use a float.