Controls - Revision history

Dcurrent: /* Key Events */

2026-08-20T18:32:33Z

Key Events

← Older revision		Revision as of 14:32, 20 August 2026
Line 307:		Line 307:
	Player input is represented by bit masks for held, newly pressed, newly released, pending native play, and disabled controls. Scripts may inspect these values with <code>playerkeys()</code> or player properties, and may alter the masks when input must be transformed or consumed.		Player input is represented by bit masks for held, newly pressed, newly released, pending native play, and disabled controls. Scripts may inspect these values with <code>playerkeys()</code> or player properties, and may alter the masks when input must be transformed or consumed.

	See [[~~Keyscript~~]] for the complete reference, including execution order, scope, event data, key states, <code>keyscriptrate</code>, input cancellation, and examples.		See [[Key Scripts]] for the complete reference, including execution order, scope, event data, key states, <code>keyscriptrate</code>, input cancellation, and examples.

	== Command Input Sequence ==		== Command Input Sequence ==

Dcurrent: /* Key Events */ Replace with stub directing to full article.

2026-08-20T18:31:18Z

Key Events: Replace with stub directing to full article.

← Older revision		Revision as of 14:31, 20 August 2026
Line 302:		Line 302:

	== Key Events ==		== Key Events ==
	When native options aren’t enough, OpenBOR provides several layers of key events. These allow you to capture an incoming key or command, and insert your own scripts to perform any action you can imagine.

	~~=== Key Status ===~~		OpenBOR provides layered script hooks for intercepting and responding to player input. These include the global InputAll preprocessor, level and model <code>keyscript</code>, per-player <code>key#.c</code> files, and global <code>keyall.c</code>. Each layer executes before native gameplay input handling, allowing creators to observe, supplement, redirect, or replace default control behavior.
	OpenBOR ~~maintains three key status values~~ for ~~each~~ player. Each ~~value is an integer you can apply bitwise logic~~ to ~~obtain an individual on/off flag for each key~~.

	* '''Hold -''' An engine update begins. ~~If a key is on~~, the ~~key is held.~~		Player input is represented by bit masks for held, newly pressed, newly released, pending native play, and disabled controls. Scripts may inspect these values with <code>playerkeys()</code> or player properties, and may alter the masks when input must be transformed or consumed.
	* '''Press -''' Player presses a key.
	* '''Release''' - Player releases a key.

	~~# InputAll - Runs on initial player input before any engine key handling or~~ key ~~scripts take place. Use this event if you want to change the command~~ input ~~itself. Examples include reversing player controls or creating shortcut keys for multi-button presses.~~		See [[Keyscript]] for the complete reference, including execution order, scope, event data, key states, <code>keyscriptrate</code>, input cancellation, and examples.
	~~# Level keyscript#~~
	~~# Entity keyscript~~
	~~# Global key#.c~~
	~~# Global keyall.c~~
	~~# Default key action~~.

	== Command Input Sequence ==		== Command Input Sequence ==

Dcurrent at 21:17, 20 July 2026

2026-07-20T21:17:56Z

← Older revision		Revision as of 17:17, 20 July 2026
Line 389:		Line 389:

	[[Category:Openbor]]		[[Category:Openbor]]
			[[Category:Script]]

Dcurrent: /* Script API */

2026-07-20T21:09:12Z

Script API

← Older revision		Revision as of 17:09, 20 July 2026
Line 213:		Line 213:

	=== Script API ===		=== Script API ===
	~~Sequences created with~~ cancel ~~and com~~ are model ~~properties~~. See [[Controls#Command Input Sequence\|Command Input Sequence]] below for details. The command history used to ~~verify~~ player inputs against sequences is ~~part of~~ the player structure. See [[Player Property#Command Buffer\|Player Property]] for details.		Command sequences defined by <code>com</code> and <code>cancel</code> are stored in each model structure’s command collection. See [[Controls#Command Input Sequence\|Command Input Sequence]] below for access details. The command history used to match player inputs against these sequences is stored in the player structure. See [[Player Property#Command Buffer\|Command Buffer]] in [[Player Property]] for access details.

	== Maximum Freespecials ==		== Maximum Freespecials ==

Dcurrent: /* Script API */

2026-07-20T21:03:30Z

Script API

← Older revision		Revision as of 17:03, 20 July 2026
Line 213:		Line 213:

	=== Script API ===		=== Script API ===
	The command history used to verify player inputs against sequences is part of the player structure. See [[Player Property#Command Buffer\|Player Property]] for details.		Sequences created with cancel and com are model properties. See [[Controls#Command Input Sequence\|Command Input Sequence]] below for details. The command history used to verify player inputs against sequences is part of the player structure. See [[Player Property#Command Buffer\|Player Property]] for details.

	== Maximum Freespecials ==		== Maximum Freespecials ==

Dcurrent: /* Sequence Step Properties */

2026-07-20T21:01:10Z

Sequence Step Properties

@@ Line 346: / Line 346: @@
 === Sequence Step Properties ===
-Each sequence step provides the following properties:
+Once you have obtained a sequence-step pointer, use <code>get_command_input_step_property()</code> and <code>set_command_input_step_property()</code> to read or modify its members. Key flags and timing properties use unsigned 64-bit integer values.
 {| class="wikitable sortable"
@@ Line 375: / Line 386: @@
 |}
 [[Category:Openbor]]

Dcurrent: /* Sequence Step Properties */

2026-07-20T20:57:12Z

Sequence Step Properties

@@ Line 374: / Line 374: @@
 |Maximum elapsed-time span allowed among the Press flags forming a chord. Zero requires the presses to occur on the same logical tick.
 |}
 [[Category:Openbor]]

Dcurrent at 20:46, 20 July 2026

2026-07-20T20:46:29Z

← Older revision		Revision as of 16:46, 20 July 2026
Line 374:		Line 374:
	\|Maximum elapsed-time span allowed among the Press flags forming a chord. Zero requires the presses to occur on the same logical tick.		\|Maximum elapsed-time span allowed among the Press flags forming a chord. Zero requires the presses to occur on the same logical tick.
	\|}		\|}
			[[Category:Openbor]]

Dcurrent: /* Command Buffer */

2026-07-20T20:40:23Z

Command Buffer

@@ Line 211: / Line 211: @@
 Cancel is otherwise identical to Command and follows the same rules (input sequence, energy cost, etc.).
 == Maximum Freespecials ==
@@ Line 314: / Line 317: @@
 # Global keyall.c
 # Default key action.
 == Command Input Sequence ==

Dcurrent: /* Under the Hood */

2026-07-20T04:29:21Z

Under the Hood

← Older revision		Revision as of 00:29, 20 July 2026
Line 433:		Line 433:
	\|Maximum elapsed-time span allowed among the Press flags forming a chord. Zero requires the presses to occur on the same logical tick.		\|Maximum elapsed-time span allowed among the Press flags forming a chord. Zero requires the presses to occur on the same logical tick.
	\|}		\|}

	~~== Under the Hood ==~~
	~~Why allow sixty-four steps per sequence and 256 entries per command buffer? These capacities are deliberate.~~

	Where practical, OpenBOR uses power-of-two capacities for fixed and circular collections. Circular indexes can then wrap with an inexpensive bit mask instead of a modulo operation, keeping hot-path processing efficient and predictable.

	~~<syntaxhighlight lang="text">~~
	~~2, 4, 8, 16, 32, 64, 128, 256...~~
	~~</syntaxhighlight>~~

	Few practical command sequences will approach thirty-two steps, though reaching that length remains possible. Since thirty-two could therefore be exhausted, the next suitable power-of-two capacity is sixty-four.

	~~Command-buffer sizing follows from the sequence capacity. Three event categories can cause an entry to be recorded:~~

	* Key press.
	* Key release.
	* Automatic hold threshold.

	~~In the worst case, events from all three categories may be interleaved throughout a sequence. Retaining enough history for a sixty-four-step sequence therefore requires three times that capacity:~~

	~~<syntaxhighlight lang="text">~~
	~~64 * 3 = 192~~
	~~</syntaxhighlight>~~

	~~The next power of two capable of holding at least 192 events is 256. OpenBOR therefore supports up to sixty-four steps per command sequence and retains 256 events in each player's command buffer.~~