battlecore::player

Life cycle

native void battlecore::player.die ();
native int  battlecore::player.loseLife (int count = 1);
native void battlecore::player.respawn ();
native int  battlecore::player.getRespawnTimeSecs ();
native void battlecore::player.setRespawnTimeSecs (int seconds);
native bool battlecore::player.getIsRespawning ();
native bool battlecore::player.getIsAlive ();

• die— kills the player. Shield and armour go to zero, and the death is recorded against whoever landed the hit being handled, if anyone. It does not spend a life and does not change state. Both of those are the game's rules.
• loseLife — spends lives, 1 when count is left out. Lives never go below zero. Returns the lives left. The firmware never spends a life on its own, so a game that charges a life for a death calls this.
• respawn — restores shield, armour and ammo to their maximums. Lives are not restored.
• getRespawnTimeSecs / setRespawnTimeSecs— how long a respawn takes, in seconds. It comes from the config's respawnTimeSecs, and is 5 when the config leaves it out. The respawn screen counts it down. The script still decides when the respawn ends.
• getIsRespawning — returns whether the player is in a respawn countdown.
• getIsAlive — returns true while the player has armour left. It says nothing about lives. Read those with getLives.

Armour reaching zero inside takeDamage kills the player the same way die does. A game that charges a life for each death spends it straight after:

battlecore::player.takeDamage(evt.data.hitValue);

if (battlecore::player.getIsAlive() == false) {
	if (battlecore::player.loseLife() == 0) {
		battlecore::fsm.setState(StateEnum.GAME_OVER, {"playerId": evt.data.playerId});
		return;
	}

	battlecore::fsm.setState(StateEnum.DEAD, {"playerId": evt.data.playerId});
}

Identity

native int  battlecore::player.getPlayerId ();
native int  battlecore::player.setPlayerId (int newVal);
native int  battlecore::player.getTeamId ();
native void battlecore::player.setTeamId (int newVal);
native void battlecore::player.setName (string newName);

• getPlayerId / setPlayerId — gets or sets the player id.
• getTeamId / setTeamId — gets or sets the team id.
• setName — sets the player name.

Damage and healing

native int  battlecore::player.takeDamage (int amount);
native void battlecore::player.takeArmourDamage (int amount);
native void battlecore::player.takeShieldDamage (int amount);
native int  battlecore::player.takeHealing (int amount);
native int  battlecore::player.takeArmourHealing (int amount);
native int  battlecore::player.takeShieldHealing (int amount);

• takeDamage — applies damage to the shield first, then to armour. Returns 0 when nothing landed, 1 when the shield took all of it, and 2 when armour took some. Armour reaching zero kills the player. An invulnerable player, or one with no armour left, takes nothing.
• takeArmourDamage / takeShieldDamage — apply damage to one pool only.
• takeHealing — heals armour first, then the shield with whatever is left over.
• takeArmourHealing / takeShieldHealing — heal one pool only.

The healing functions return how much was actually applied. That is 0 when the pool is already full.

Kills and deaths

native int  battlecore::player.getKillCount ();
native bool battlecore::player.addKills (int count = 1);
native int  battlecore::player.getDeathCount ();
native bool battlecore::player.addDeaths (int count = 1);

The firmware records kills and deaths as they happen, and every device adds them up the same way. A script does not count them. It only adjusts them: a kill that counts double, or a death that should not count.

• getKillCount / getDeathCount — return the current totals.
• addKills / addDeaths — add to the total, 1 when count is left out. Pass a negative number to take some away. Returns false outside a game.

Record values

native bool battlecore::player.setRecordValue (int slot, int value);
native int  battlecore::player.getRecordValue (int slot);

Each player's record has 8 slots, numbered 0 to 7, for the game's own values: which flag the player carries and since when, for example. The firmware never reads what they mean.

• setRecordValue— stores a value in one of this player's slots. Returns false outside a game.
• getRecordValue — reads one of this player's slots. An unused slot is 0.

The record is shared with every tagger in the game, and it comes back after a reboot. Other taggers read it with the record functions in battlecore::game. When another player changes one of their values, this tagger raises PLAYER_RECORD / CHANGE. See Device Events.

Stats (getters and setters)

The following stats each expose a getter and a setter. Getters of type int return the value; setters take a single newVal argument.

setShieldRecharging takes how many milliseconds a recharge from empty to full takes. Pass 0 to stop a recharge.