Events and States

Overview

BattleScript has native support for event-driven programming through the state and event keywords. This allows your scripts to respond to various game events based on the current state of the device.

States

States represent different modes or conditions that your device can be in. For example, a device might be in an "idle" state, a "playing" state, or a "gameover" state.

States are defined using the state keyword followed by a string name:

state "idle" {
    // Event handlers for the idle state go here
}

state "inGame" {
    // Event handlers for the inGame state go here
}

state "gameOver" {
    // Event handlers for the gameOver state go here
}

Events

Events are specific occurrences that your script can respond to, such as button presses, timer expirations, or receiving data. Event handlers are defined inside state blocks using the event keyword.

state "idle" {
	    event "button.pressed" (Event_Button_Pressed event) => {
	        // Code to handle button press in idle state
	        if (event.buttonId == buttons.trigger) {
	            // start game logic here
	        }
	    }
}

Events are only processed if the device is in the corresponding state. If the device is not in the "idle" state, the "button.pressed" event in the example above would be ignored.

Event Data

Events can include data that provides information about the event. This data is passed to the event handler as a parameter.

interface Event_HardwareIrReceiver_DecodedDataEvent extends Event {
	    Data_IrData dynamicIrData;
}

state "inGame" {
	    event "irReceiver.decodedData" (Event_HardwareIrReceiver_DecodedDataEvent event) => {
	        // Access event data
	        int playerId = event.dynamicIrData.playerId;
	        int teamId = event.dynamicIrData.teamId;
	        int bulletTypeId = event.dynamicIrData.bulletTypeId;
	        
	        // Process the hit based on the data
	        if (bulletTypeId == bulletTypes.damage) {
	            // apply damage: event.dynamicIrData.hitValue
	        }
	    }
}

State Transitions

You can change the current state of the device using the fsm.setState() function:

state "inGame" {
	    event "player.eliminated" (Event event) => {
	        // Change to the gameOver state
	        fsm.setState("gameOver");
	    }
}

state "gameOver" {
	    event "fsm.onEnter" (Event_IrrelonFSM_OnEnter event) => {
	        // This event is triggered when entering the gameOver state
	        // play game over sound
	        // show game over screen
	    }
}

The special fsm.onEnter and fsm.onExit events are triggered when entering or exiting a state.