Player Property

Introduction

Player property is API interface for OpenBOR's player structure. This structure is responsible for tracking player game state, lives, credits, control inputs, and transferable status between player controlled entities. Each player has an independent instance of the player structure maintained globally.

Obtaining Object

The player property is a global array of structures referenced by player index.

Single Access

You may obtain the pointer to individual structures as an openborvariant(). Note this is a legacy method, and should never be used when you need to scan each player. Use the collection access method below.

Player one is exposed as openborvariant("player").

// Get player one structure.
void player_1 = openborvariant("player");

To get other players, add a numeric cadence:

/* Get player structures. */

void player_1 = openborvariant("player1");

void player_2 = openborvariant("player2");

void player_3 = openborvariant("player3");

void player_4 = openborvariant("player4");

Collection Access

Obtain the player collection array pointer.

void player_collection = openborvariant("player_collection");

Command Buffer

In order to detect key sequences and execute actions, OpenBOR keeps a 256 slot ring buffer for each player. Each buffer contains the last 256 player input events. Events recorded include the following:

• Any new key press.
• Any new key release.
• Any held key with an auto trigger reaching its time threshold.

Individual entries in the buffer host the following data:

• Newly pressed keys.
• Snapshot of inputs held when a positive edge occurs.
• Keys newly released at the event.
• Automatic hold-threshold edges.
• Complete held-state snapshot.
• Elapsed Time of event.
• Tick time of event.

In turn the key properties are bit masks that may contain one or more key flags.

To access the buffer, you will need to first acquire the buffer pointer from player properties, then select an index. This will in turn provide the pointer to buffer entry where you may access the desired property.

Get buffer entry

Once you have the buffer pointer, supply an index from 0 - 255 to get the buffer entry pointer. Note, as this is a ring buffer, indexes correspond to array elements, not the chronological order of recorded events.

void command_buffer = get_player_property(player, openborconstant("PLAYER_PROPERTY_COMMAND_BUFFER"));
int index = 2; // 0 - 255

void buffer_entry = get_command_input_event_object(command_buffer, index);

Access Buffer Entry Properties

Once you have obtained a buffer entry pointer, you may get or set buffer properties as follows.

// Get
int key_held = get_command_input_event_property(buffer_entry, openborconstant("COMMAND_INPUT_EVENT_PROPERTY_HELD"));

// Set
int new_key_held = openborconstant("FLAG_MOVEUP") | openborconstant("FLAG_JUMP");

set_command_input_event_property(buffer_entry, openborconstant("COMMAND_INPUT_EVENT_PROPERTY_HELD"), new_key_held);

Buffer Entry Properties

Property Constat	Description
COMMAND_INPUT_EVENT_PROPERTY_HELD	Complete snapshot of keys held at the event. Keys released by the event remain included so commands such as a[50] + ~a can verify both the held duration and release.
COMMAND_INPUT_EVENT_PROPERTY_HOLD	Automatic hold-threshold edges generated when inputs such as a*[50] reach their configured time.
COMMAND_INPUT_EVENT_PROPERTY_PRESS	Keys newly pressed at event.
COMMAND_INPUT_EVENT_PROPERTY_PRESS_CHORD	Snapshot of inputs held when a positive edge (key press) occurs. For example, if the player is holding f and presses a, the event's press chord will contain the key event masks openborconstant("FLAG_FORWARD") and openborconstant("FLAG_ATTACK").
COMMAND_INPUT_EVENT_PROPERTY_RELEASE	Key release on event.
COMMAND_INPUT_EVENT_PROPERTY_TICKS	SDL ticks when event occurred. This property is not used by native logic.
COMMAND_INPUT_EVENT_PROPERTY_TIME	Elapsed time when event occurred. This property is important for sequence timing, so be careful of causing logic errors if you choose to modify it.