BattleCore Standard Library

Overview

The BattleCore Standard Library is the set of device functions that BattleScript code uses to control the hardware and game state of a BattleCore device. These functions cover audio, lighting, infrared, networking, the finite state machine, player and weapon state, the game's config, and more.

Unlike the language standard libraries (std::console, std::debug, std::gpio and std::math), the BattleCore API is not part of the BattleScript language itself. It is provided by the device firmware, and is split into modules that each expose a focused set of native functions.

Namespacing

Every BattleCore function is namespaced under the lowercase battlecore namespace, followed by the module name and the function name:

battlecore::<module>.<fn>(...)

// for example
battlecore::weapon.fire();
battlecore::player.takeDamage(10);
battlecore::fsm.setState(StateEnum.DEAD);

Including the declarations

Because the BattleCore functions are provided by the firmware rather than the language, their declarations are pulled into your program by include-ing the matching declaration file for the module you want to use:

include "./battlecore/player.bst";
include "./battlecore/weapon.bst";

// the declarations are now available to call
battlecore::player.respawn();

The include statement is a textual include of another .bst file. It is how the native declarations and shared enums for each module become visible to your code. This is distinct from the language standard libraries, which are globally available and require no include or import.

Modules

The BattleCore Standard Library is made up of the following modules:

• audio (battlecore::audio) — audio packs, master volume, and track, tone and audio group playback.
• config (battlecore::config)— read the game's own settings from its config file.
• device (battlecore::device) — device identity, role, mode and volume.
• fsm (battlecore::fsm) — read the state, and move the player between the states of play.
• game (battlecore::game)— game mode, the game clock, ending the game, respawn mode, and questions about every player's record.
• infrared (battlecore::infrared) — infrared encoding configuration and install/uninstall.
• input (battlecore::input) — create digital inputs bound to GPIO pins.
• lang (battlecore::lang)— a game's text in each player's language and wording.
• lights (battlecore::lights) — switch and flash the single-colour lights, such as the muzzle flash.
• motion (battlecore::motion)— the player's speed (still, walking, running) and which way the tagger points, from its accelerometer.
• net (battlecore::net)— radio link state, mesh commands and the game's own messages to other taggers.
• player (battlecore::player) — player life cycle, lives, armour, shield, stats and record values.
• rgb (battlecore::rgb)— the coloured LEDs, their brightness and effects, and the headset's lights.
• screens (battlecore::screens) — current screen, screen elements and roller navigation.
• storage (battlecore::storage) — persistent key/value storage.
• weapon (battlecore::weapon) — weapon firing, reloading, the weapons carried, ammo and shot configuration.

Reference

• Device Events — every event a device emits to your script, and the payload each one carries.