Dcurrent at 18:04, 20 August 2026

2026-08-20T18:04:15Z

← Older revision		Revision as of 14:04, 20 August 2026
Line 318:		Line 318:
	* [[Thinkscript]]		* [[Thinkscript]]
	* [[Updateentityscript]]		* [[Updateentityscript]]
			[[Category:Openbor]]

Dcurrent: Created page with "Category:Model Category:Script '''keyscript''' is a model and level command for executing script in response to player input. OpenBOR also provides fixed global key-script files and an InputAll preprocessing hook. Together, these form a layered input system that can observe, supplement, redirect, or replace native control behavior. Key scripts are not limited to activating attacks. They may control menus, open defensive windows, manage charged actions, change m..."

2026-08-20T17:56:02Z

Created page with "Category:Model Category:Script '''keyscript''' is a model and level command for executing script in response to player input. OpenBOR also provides fixed global key-script files and an InputAll preprocessing hook. Together, these form a layered input system that can observe, supplement, redirect, or replace native control behavior. Key scripts are not limited to activating attacks. They may control menus, open defensive windows, manage charged actions, change m..."

New page

[[Category:Model]]
[[Category:Script]]

'''keyscript''' is a model and level command for executing script in response to player input. OpenBOR also provides fixed global key-script files and an InputAll preprocessing hook. Together, these form a layered input system that can observe, supplement, redirect, or replace native control behavior.

Key scripts are not limited to activating attacks. They may control menus, open defensive windows, manage charged actions, change movement, coordinate multiplayer input, implement contextual controls, or support entirely custom command systems.

== Input States ==

OpenBOR maintains several input masks for each player. Each is an integer whose bits identify applicable controls.

{| class="wikitable sortable"
! State
! Player property
! Description
|-
| Held
| <code>keys</code>
| Controls currently held by the player.
|-
| Pressed
| <code>newkeys</code>
| Controls newly pressed during the current input refresh.
|-
| Released
| <code>releasekeys</code>
| Controls newly released during the current input refresh.
|-
| Play
| <code>playkeys</code>
| Pressed controls awaiting native gameplay handling. Native actions consume bits from this mask as they use them.
|-
| Disabled
| <code>disablekeys</code>
| Controls masked from the player's detected input.
|}

See [[Controls#Key Control Constants|Key Control Constants]] for the corresponding bit-mask constants.

== Processing Order ==

OpenBOR provides five script layers before native gameplay responds to input. The applicable layers execute in this order for each player:

{| class="wikitable"
! Order
! Layer
! Scope
! Event data
|-
| 1
| <code>data/scripts/inputall.c</code>
| All player input, before command history and ordinary key scripts
| <code>player</code>
|-
| 2
| Level <code>keyscript</code>
| Current level
| <code>player</code>
|-
| 3
| Model <code>keyscript</code>
| Entity currently controlled by the player
| <code>self</code>, <code>player</code>
|-
| 4
| <code>data/scripts/key1.c</code> through <code>key4.c</code>
| Corresponding player slot
| None
|-
| 5
| <code>data/scripts/keyall.c</code>
| All applicable players
| <code>player</code>
|}

Native gameplay input handling follows the script layers during entity update. Earlier scripts may change the player input masks before later scripts inspect them. Return values do not stop subsequent layers.

Global update scripts execute after InputAll but before the ordinary key-script chain. Logical entity updates occur after the key-script chain.

== InputAll ==

<code>data/scripts/inputall.c</code> is an automatic global script. No model or level command is required.

<syntaxhighlight lang="c" line>
void main()
{
int player = getlocalvar("player");

// Inspect or transform incoming player input here.
}
</syntaxhighlight>

InputAll executes during input refresh after OpenBOR reads physical controls into the player's input masks. It runs before OpenBOR records the command-input event and before any ordinary keyscript. Changes to <code>keys</code>, <code>newkeys</code>, or <code>releasekeys</code> can therefore alter what later command matching and key scripts observe.

InputAll is also suitable for updating <code>playkeys</code> when transformed input should affect native actions. For example, exchanging left and right only in <code>newkeys</code> would change the recorded press but leave the original native action in <code>playkeys</code> unless that mask is changed as well.

Unlike ordinary key scripts, InputAll is not suppressed by the game's paused state. This makes it suitable for custom pause interfaces and other input processing that must continue while gameplay is stopped.

== Level Keyscript ==

Add <code>keyscript</code> to a level definition and provide the path to the script file:

<syntaxhighlight lang="text">
keyscript data/scripts/level_key.c
</syntaxhighlight>

The level keyscript executes for applicable input from each player while that level is active. It receives the zero-indexed player slot.

<syntaxhighlight lang="c" line>
void main()
{
int player = getlocalvar("player");

// Handle level-specific input here.
}
</syntaxhighlight>

Level key scripts are useful for stage mechanics, shared interfaces, scripted sequences, environmental interactions, or control rules that should apply only in a particular level.

Current syntax provides one level <code>keyscript</code>, not a numbered <code>keyscript#</code> command. The <code>player</code> variable identifies which player's input triggered the event.

== Model Keyscript ==

Add <code>keyscript</code> to a model definition and provide the path to the script file:

<syntaxhighlight lang="text">
keyscript data/scripts/model_key.c
</syntaxhighlight>

The model keyscript executes only when an entity spawned from that model is currently assigned to a player slot. Adding the command to an ordinary AI-controlled entity does not make the script poll input. If control of that entity is assigned to a player, its model keyscript becomes applicable.

<syntaxhighlight lang="c" line>
void main()
{
void self = getlocalvar("self");
int player = getlocalvar("player");

// Handle model-specific input here.
}
</syntaxhighlight>

The command is named <code>keyscript</code>. References to ''entitykeyscript'' describe an internal engine label and should not be used in model text.

Model key scripts are ideal for character-specific controls because <code>self</code> already identifies the controlled entity. Different models may use the same physical input for entirely different actions without adding model-selection logic to a global script.

== Player Key Scripts ==

The following optional global files correspond directly to player slots:

* <code>data/scripts/key1.c</code> - Player 1.
* <code>data/scripts/key2.c</code> - Player 2.
* <code>data/scripts/key3.c</code> - Player 3.
* <code>data/scripts/key4.c</code> - Player 4.

OpenBOR loads these files automatically when present. They receive no automatic event variables because the filename already determines the player slot. Scripts that share common functions may pass their known zero-indexed slot explicitly.

<syntaxhighlight lang="c" line>
void main()
{
int player = 0; // key1.c is Player 1.

// Handle Player 1 input here.
}
</syntaxhighlight>

Player key scripts are useful when behavior belongs to a controller slot rather than the current model or level.

== Keyall ==

<code>data/scripts/keyall.c</code> is an automatic global script that executes for each applicable player after the level, model, and player-slot key scripts. OpenBOR supplies the zero-indexed player slot.

<syntaxhighlight lang="c" line>
void main()
{
int player = getlocalvar("player");

// Handle project-wide player input here.
}
</syntaxhighlight>

Keyall is suited to project-wide shortcuts, shared interfaces, diagnostics, achievements, or common behaviors that should not be duplicated across models and levels.

Level and model key scripts require an active level. Player-slot and Keyall scripts may also execute on applicable non-level engine screens. Ordinary key scripts do not execute while the game is paused.

== Trigger Conditions ==

By default, the ordinary key-script chain executes when a player newly presses or releases at least one control. Pressing and later releasing one control therefore causes two separate event calls.

Multiple controls changing during the same input refresh do not cause separate calls. Each applicable script executes once for that player and may inspect every relevant input bit during the call.

The ordinary chain executes only while the game is not paused. Level and model layers also require an active level, and the model layer requires a current player entity.

=== Held-Key Repetition ===

Add <code>keyscriptrate</code> to <code>data/scripts/script.txt</code> when the scripts should also execute while any control remains held:

<syntaxhighlight lang="text">
keyscriptrate 1
</syntaxhighlight>

Despite the setting's name, its value does not specify a numeric interval. Zero disables held-key repetition, while any nonzero value enables it. Once enabled, the ordinary key-script chain executes during outer updates while the player continues holding a control.

Creators do not need held-key repetition merely to inspect held controls. Any execution caused by a press or release may query the current held mask. Enable <code>keyscriptrate</code> when continuous execution is itself required.

== Inspecting Controls ==

<code>playerkeys()</code> provides a convenient way to test individual controls. It accepts a player slot, an input-state selector, and one or more control names:

<syntaxhighlight lang="c" line>
int result = playerkeys(player, state, control, ...);
</syntaxhighlight>

{| class="wikitable"
! State
! Meaning
|-
| <code>0</code>
| Control is currently held.
|-
| <code>1</code>
| Control was newly pressed.
|-
| <code>2</code>
| Control was newly released.
|}

Supported control names are:

* <code>attack</code>
* <code>attack2</code>
* <code>attack3</code>
* <code>attack4</code>
* <code>jump</code>
* <code>special</code>
* <code>start</code>
* <code>esc</code>
* <code>moveleft</code>
* <code>moveright</code>
* <code>moveup</code>
* <code>movedown</code>
* <code>screenshot</code>
* <code>anybutton</code>

<code>anybutton</code> represents Jump, Special, or any Attack control. It does not include movement, Start, Screenshot, or Escape.

When more than one control is supplied, <code>playerkeys()</code> returns true only when all requested controls match the selected state. This makes chord checks concise.

<syntaxhighlight lang="c" line>
void main()
{
void self = getlocalvar("self");
int player = getlocalvar("player");

// Newly pressed Attack 4.
if (playerkeys(player, 1, "attack4"))
{
setentityvar(self, "stance_change", 1);
}

// Up and Attack pressed together.
if (playerkeys(player, 1, "moveup", "attack"))
{
setentityvar(self, "command_uppercut", 1);
}

// Special was released.
if (playerkeys(player, 2, "special"))
{
setentityvar(self, "release_charge", 1);
}
}
</syntaxhighlight>

== Consuming Input ==

Key-script return values are ignored. Returning <code>0</code>, <code>1</code>, or another value does not consume input, prevent later scripts, or suppress native behavior.

To prevent a native action, remove the corresponding bit from the player's <code>playkeys</code> mask. Preserve unrelated bits so other controls remain available.

<syntaxhighlight lang="c" line>
void consume_attack4(int player)
{
int attack4 = openborconstant("FLAG_ATTACK4");
int play_keys = getplayerproperty(player, "playkeys");

changeplayerproperty(
player,
"playkeys",
play_keys & ~attack4
);
}
</syntaxhighlight>

Clearing <code>playkeys</code> suppresses pending native gameplay use, but does not erase the press from <code>newkeys</code>, the held state from <code>keys</code>, or a recorded command-input event. InputAll is the appropriate layer when the input itself must be transformed before command history is constructed.

Use <code>disablekeys</code> when a control should remain unavailable across future input refreshes. Clear the applicable current masks as well if the already-detected input must be cancelled immediately.

== Examples and Uses ==

Quick applications include:

* '''Character-specific controls''' - Give different playable models distinct command layouts or contextual actions.
* '''Parry windows''' - Open a brief defensive state when the player presses a designated direction or guard control.
* '''Charge actions''' - Begin charging on a press, monitor the held state, and release the action when the control is released.
* '''Input transformation''' - Reverse directions, exchange buttons, create accessibility mappings, or synthesize multi-button shortcuts with InputAll.
* '''Stage interaction''' - Operate switches, vehicles, dialogue, or other level-specific systems from the level keyscript.
* '''Shared interfaces''' - Implement project-wide menus, move lists, debug controls, or shortcuts through Keyall.
* '''Multiplayer coordination''' - Inspect the supplied player slot and arbitrate shared interfaces without allowing one player's input to interfere with another.
* '''Input chords''' - Detect simultaneous directions and buttons for throws, dodges, command attacks, or shortcuts.

== See Also ==

* [[Controls]]
* [[Player Property]]
* [[Controls#Command Input Sequence|Command Input Sequence]]
* [[Script Overview]]
* [[Animationscript]]
* [[Thinkscript]]
* [[Updateentityscript]]

Key Scripts - Revision history

Dcurrent at 18:04, 20 August 2026