https://chronocrash.com/openbor/wiki/api.php?action=feedcontributions&feedformat=atom&user=DcurrentOpenBOR - User contributions [en]2026-10-21T22:28:11ZUser contributionsMediaWiki 1.46.2https://chronocrash.com/openbor/wiki/index.php?title=Category:Pages_with_syntax_highlighting_errors&diff=1107Category:Pages with syntax highlighting errors2026-10-14T14:39:31Z<p>Dcurrent: Created page with "An annoying aspect of Media-wiki is the delicacy of syntax highlighting - as in properly display code samples. Often the system will work perfectly for a time, then spontaneously fail as the host server makes unannounced updates. Please contact me ([https://www.chronocrash.com/forum/members/dcurrent.2/ DCurrent]) at the [https://www.chronocrash.com/forum ChronoCrash forum] if you see pages appearing here."</p>
<hr />
<div>An annoying aspect of Media-wiki is the delicacy of syntax highlighting - as in properly display code samples. Often the system will work perfectly for a time, then spontaneously fail as the host server makes unannounced updates. Please contact me ([https://www.chronocrash.com/forum/members/dcurrent.2/ DCurrent]) at the [https://www.chronocrash.com/forum ChronoCrash forum] if you see pages appearing here.</div>Dcurrenthttps://chronocrash.com/openbor/wiki/index.php?title=Animation_Overview&diff=1106Animation Overview2026-09-27T13:23:29Z<p>Dcurrent: /* Animation identifiers */</p>
<hr />
<div>Animations are one of OpenBOR's fundamental building blocks. Models use animations to describe how they look and behave over time. Walking, standing, attacking, falling, taking damage, and many other actions are represented by ordered animation frames.<br />
<br />
Each animation belongs to a model and occupies a recognized animation slot such as <code>idle</code>, <code>walk</code>, <code>jump</code>, <code>pain</code>, or <code>attack1</code>. OpenBOR's native logic selects many of these slots automatically. Scripts may also select an animation or frame directly.<br />
<br />
An animation frame is more than an image. It may also contain timing, offsets, collision boxes, movement, sounds, draw settings, entity spawns, and other behavior.__TOC__<br />
<br />
== Basic structure ==<br />
<br />
The <code>anim</code> command begins an animation definition. Commands following it configure the animation or prepare properties for its frames. Each <code>frame</code> command adds one frame using the properties currently in effect.<br />
<br />
<syntaxhighlight lang="text"><br />
anim idle<br />
loop 1<br />
delay 12<br />
offset 32 96<br />
<br />
frame data/chars/example/idle_01.png<br />
frame data/chars/example/idle_02.png<br />
frame data/chars/example/idle_03.png<br />
</syntaxhighlight><br />
<br />
This example creates a looping idle animation with three frames. With the default centisecond delay unit, each frame lasts 0.12 seconds.<br />
<br />
Indentation and blank lines are optional, but they make animation blocks easier to read.<br />
<br />
=== Animation identifiers ===<br />
<br />
The value following <code>anim</code> identifies the animation's purpose. Common examples include:<br />
<br />
{| class="wikitable"<br />
! Identifier<br />
! Typical purpose<br />
|-<br />
| <code>idle#</code><br />
| Standing without moving.<br />
|-<br />
| <code>walk#</code><br />
| Ordinary movement.<br />
|-<br />
| <code>jump</code><br />
| Initial or rising jump state.<br />
|-<br />
| <code>land</code><br />
| Landing from a jump or fall.<br />
|-<br />
| <code>pain</code><br />
| Reacting to damage.<br />
|-<br />
| <code>fall#</code><br />
| Knockdown or falling reaction.<br />
|-<br />
| <code>rise#</code><br />
| Recovering from a fall.<br />
|-<br />
| <code>attack#</code><br />
| Native attack animation.<br />
|-<br />
| <code>freespecial#</code><br />
| Creator-configured special or command move.<br />
|-<br />
|<code>follow#</code><br />
|General use animations inaccessible to native engine logic and only activated by creator defined follow triggers or scripts.<br />
|}<br />
<br />
Animation identifiers are behavioral slots, not arbitrary labels. Supplying an animation makes the corresponding behavior available to native engine logic and scripts. Some model types require certain animations to operate normally, while others are optional.<br />
<br />
== Frame construction ==<br />
<br />
OpenBOR reads model files from top to bottom. Frame property commands update temporary state, and <code>frame</code> commits a copy of that state to the animation.<br />
<br />
<syntaxhighlight lang="text"><br />
anim idle<br />
loop 1<br />
offset 32 96<br />
<br />
delay 10<br />
frame data/chars/example/idle_01.png<br />
<br />
delay 25<br />
frame data/chars/example/idle_02.png<br />
</syntaxhighlight><br />
<br />
The first frame receives a delay of 10. The second receives a delay of 25 because the delay changes before its <code>frame</code> command.<br />
<br />
Commands placed after a <code>frame</code> line cannot alter the frame that was already added. Most frame properties remain active for subsequent frames until another command changes or disables them. Some one-shot properties, such as a frame sound, reset after the frame is added.<br />
<br />
Define important state explicitly in each animation. In particular, specifying a delay inside every animation avoids accidentally inheriting a previously active delay while the model file is being parsed.<br />
=== Frame numbering ===<br />
Frames use zero-based indexes. The first frame line is frame 0, the second is frame 1, and so on. Commands that target a frame number use these indexes unless their own documentation states otherwise.<br />
<br />
The same image may appear more than once when different timing or behavior is needed. OpenBOR reuses its globally cached pixel data, so repeating an image does not require another pixel-data allocation.<br />
<br />
Frame <code>none</code> adds a logical frame without a visible sprite, which can be useful for invisible states or script-controlled behavior.<br />
<br />
== Offsets ==<br />
<br />
The <code>offset</code> command selects the anchor point inside a frame image.<br />
<br />
<syntaxhighlight lang="text"><br />
offset 32 96<br />
frame data/chars/example/idle_01.png<br />
</syntaxhighlight><br />
<br />
OpenBOR places the selected point at the entity's world position. For a standing character, the anchor is usually near the ground between the character's feet.<br />
<br />
Choose a consistent animation canvas size during production and align every source frame to the same anchor before export. Guides for the ground line and horizontal center make this much faster than correcting alignment one frame at a time in the model file.<br />
<br />
OpenBOR automatically trims unused image space when it loads sprites. Consistent source canvases are still useful because the trimming process preserves the intended relationship between the artwork and its anchor without retaining transparent padding in memory.<br />
<br />
Poor source alignment makes an entity appear to shake, slide, or change height when frames cycle. Per-frame offset changes remain available for deliberate repositioning or assets that cannot be realigned, but they should generally be the exception rather than the primary production workflow.<br />
<br />
== Looping ==<br />
Animations do not loop unless looping is enabled.<syntaxhighlight lang="text"><br />
loop {enable} {loop frame - optional} {end frame - optional}<br />
<br />
# Default<br />
loop 0 0 0<br />
</syntaxhighlight>loop <code>1</code> repeats the animation. loop <code>0</code> disables looping.<br />
<br />
The optional loop frame selects the zero-based frame to return to when the animation repeats. The optional end frame is an exclusive boundary - when playback reaches that frame index, it returns to the selected loop frame instead of displaying the boundary frame. <br />
<br />
For example, if end frame is <code>7</code>, frame <code>7</code> - the sixth frame, does not display - the animation instantly loops on reaching that frame. If end frame is not provided animation proceeds to the last frame and loops.<br />
<br />
Idle and walk animations commonly loop. Attacks, pain reactions, falls, and transitions commonly play once and stop on their final frame until native logic or a script selects another animation.<br />
<br />
== Delay ==<br />
<br />
Delay controls how long a frame remains active before OpenBOR advances the animation. The command is stateful and applies to each following frame until another <code>delay</code> command changes it.<br />
<br />
=== Syntax ===<br />
<br />
<syntaxhighlight lang="text"><br />
delay <value> [unit]<br />
</syntaxhighlight><br />
<br />
The unit is optional. Omitting it is equivalent to selecting <code>global</code>.<br />
<br />
<syntaxhighlight lang="text"><br />
delay 10<br />
delay 10 global<br />
</syntaxhighlight><br />
<br />
Both examples use the module's global delay unit.<br />
<br />
=== Delay units ===<br />
Optional time unit setting. <br />
{| class="wikitable"<br />
! Unit<br />
! Meaning<br />
|-<br />
| <code>global</code><br />
| Uses the unit selected by <code>global_config_delay_unit</code> in <code>data/models.txt</code>. This is the default mode.<br />
|-<br />
| <code>millisecond</code><br />
| Interprets the value as thousandths of a second.<br />
|-<br />
| <code>centisecond</code><br />
| Interprets the value as hundredths of a second. This is the default global unit and preserves traditional OpenBOR timing.<br />
|-<br />
| <code>second</code><br />
| Interprets the value as seconds.<br />
|-<br />
| <code>minute</code><br />
| Interprets the value as minutes.<br />
|-<br />
| <code>direct</code><br />
| Stores the value directly as logical clock ticks without time-unit conversion.<br />
|}<br />
<br />
OpenBOR converts the supplied value from the selected unit into logical clock ticks. See [[Animation Overview#Logical clock precision|Logical clock precision]].<br />
<br />
Examples:<br />
<br />
<syntaxhighlight lang="text"><br />
delay 250 millisecond<br />
delay 25 centisecond<br />
delay 2 second<br />
delay 1 minute<br />
delay 50 direct<br />
</syntaxhighlight><br />
<br />
Singular unit names are required.<br />
<br />
=== Global delay unit ===<br />
<br />
Use <code>global_config_delay_unit</code> in <code>data/models.txt</code> to select the unit used by unqualified and explicitly global delays.<br />
<br />
<syntaxhighlight lang="text"><br />
global_config_delay_unit centisecond<br />
</syntaxhighlight><br />
<br />
The setting accepts <code>millisecond</code>, <code>centisecond</code>, <code>second</code>, <code>minute</code>, or <code>direct</code>. It does not accept <code>global</code>, because the global setting must resolve to a concrete unit.<br />
<br />
If the command is omitted, the global unit is <code>centisecond</code>. Changing the setting reinterprets every model delay that uses <code>global</code>, so modules should choose a unit deliberately. Explicit frame units remain independent of the global selection.<br />
<br />
The setting is read while models are loaded. OpenBOR converts each delay to logical ticks and stores the converted result with the animation frame. It is not a runtime timing switch for animations that are already loaded.<br />
<br />
=== Logical clock precision ===<br />
<br />
OpenBOR animation timing ultimately uses whole logical clock ticks. Unit conversion follows these relationships:<br />
<br />
<syntaxhighlight lang="text"><br />
millisecond = value * game speed / 1000<br />
centisecond = value * game speed / 100<br />
second = value * game speed<br />
minute = value * game speed * 60<br />
direct = value<br />
</syntaxhighlight><br />
<br />
Fractional results truncate. No time unit can represent a duration smaller than the module's logical clock precision, and any fractional remainder is discarded.<br />
<br />
For example, at the default game speed of 200 ticks per second, each logical tick represents 5 milliseconds. Any value from 15 through 19 milliseconds therefore converts to three ticks, representing 15 milliseconds, while 20 milliseconds converts exactly to four ticks.<br />
<br />
The <code>direct</code> unit is useful when exact integration with the logical clock matters. Its real-time duration changes with game speed because its value is already a tick count. By pairing a game speed evenly divisible by a target frame rate with direct delays, creators can time animations in exact frame intervals. For example, a game speed of 240 provides four logical ticks for each frame at 60 Hz. This supports frame-based timing conventions commonly used by the fighting game community and fixed-refresh console games.<br />
<br />
=== Infinite delay ===<br />
<br />
Use <code>infinite</code> or the infinity symbol <code>∞</code> when a frame should not advance through ordinary clock timing.<br />
<br />
<syntaxhighlight lang="text"><br />
anim idle<br />
delay infinite<br />
offset 32 96<br />
frame data/chars/example/idle_01.png<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="text"><br />
delay ∞<br />
</syntaxhighlight><br />
<br />
An infinite frame remains active until something outside normal timing changes its animation or frame. Scripts may use the <code>DELAY_INFINITE</code> constant for the same engine value.<br />
<br />
The word <code>infinite</code> is the most portable model-file spelling. The <code>∞</code> form is UTF-8 text and may be damaged by old Windows editors, archive tools, or other utilities that do not preserve Unicode correctly.<br />
<br />
Any negative numeric delay also becomes infinite for backward compatibility. New content should use <code>infinite</code> or <code>∞</code> so its intent is explicit.<br />
<br />
=== Finite range and behavior flags ===<br />
<br />
Finite delay values use the lower 32 bits of an unsigned 64-bit value. The largest finite value is 4,294,967,295 - in default centisecond units, roughly 16 months. Conversions that would exceed this limit clamp to the largest finite delay instead of overflowing or accidentally becoming infinite.<br />
<br />
The upper 32 bits are reserved for delay behavior flags. Bit 63 is the infinite flag. Enhanced-delay calculations modify only the finite lower value and preserve behavior flags, so an infinite frame cannot accidentally become finite.<br />
<br />
=== Enhanced delay ===<br />
<br />
[[Enhanced Delay|Enhanced delay]], or <code>edelay</code>, adjusts frame delays through a model's multiplier, modifier, range, and cap settings. These calculations occur after time-unit conversion, so enhanced-delay ranges, modifiers, and caps operate on logical tick values rather than the source unit written in the animation.<br />
<br />
Enhanced-delay arithmetic is bounded to the finite delay range. It cannot overflow into behavior flags or create an infinite delay through calculation.<br />
<br />
== Frame properties ==<br />
<br />
Timing and graphics form only the minimum animation. Frame property commands can add behavior such as:<br />
<br />
{| class="wikitable"<br />
! Property<br />
! Purpose<br />
|-<br />
| <code>bbox</code><br />
| Defines the frame's body collision area. Use <code>bbox none</code> to disable it.<br />
|-<br />
| Attack collision commands<br />
| Define areas that damage or otherwise affect targets.<br />
|-<br />
| <code>move</code>, <code>movea</code>, and <code>movez</code><br />
| Apply frame movement along the model's axes.<br />
|-<br />
| <code>sound</code><br />
| Plays a sound when the frame begins.<br />
|-<br />
| Draw commands<br />
| Change scaling, rotation, transparency, remapping, clipping, and other rendering behavior.<br />
|-<br />
| Spawn commands<br />
| Create or summon child entities on selected frames.<br />
|-<br />
| Animation scripts<br />
| Execute creator-defined logic as frames change.<br />
|}<br />
<br />
Property commands normally appear before the <code>frame</code> they configure:<br />
<br />
<syntaxhighlight lang="text"><br />
anim idle<br />
loop 1<br />
delay 10<br />
offset 32 96<br />
<br />
bbox 12 20 40 76 10<br />
frame data/chars/example/idle_01.png<br />
<br />
bbox none<br />
frame data/chars/example/idle_02.png<br />
</syntaxhighlight><br />
<br />
The first frame has a body collision box. The second does not because <code>bbox none</code> changes the pending frame state before the second <code>frame</code> command.<br />
<br />
== Practical example ==<br />
<br />
<syntaxhighlight lang="text"><br />
anim idle<br />
loop 1<br />
offset 32 96<br />
bbox 12 20 40 76 10<br />
<br />
delay 100 millisecond<br />
frame data/chars/example/idle_01.png<br />
<br />
delay 150 millisecond<br />
frame data/chars/example/idle_02.png<br />
<br />
delay 100 millisecond<br />
frame data/chars/example/idle_03.png<br />
<br />
<br />
anim attack1<br />
loop 0<br />
offset 40 96<br />
delay 80 millisecond<br />
<br />
frame data/chars/example/attack_01.png<br />
<br />
move 4<br />
frame data/chars/example/attack_02.png<br />
<br />
move 0<br />
delay 160 millisecond<br />
frame data/chars/example/attack_03.png<br />
</syntaxhighlight><br />
<br />
The idle animation loops with intentionally uneven timing. The attack plays once, moves the entity during its second frame, stops that movement before the third frame, and holds the final attack pose longer.<br />
<br />
== Common problems ==<br />
<br />
{| class="wikitable"<br />
! Symptom<br />
! Likely cause<br />
|-<br />
| Frames appear to shake or slide.<br />
| Offsets do not align the same visual anchor across images.<br />
|-<br />
| A property affects the wrong frame.<br />
| The property command appears after the intended <code>frame</code> line, or persistent frame state was not changed before the next frame.<br />
|-<br />
| An animation plays much too quickly or slowly.<br />
| The delay unit or <code>global_config_delay_unit</code> does not match the values used by the model.<br />
|-<br />
| Very small delays appear identical.<br />
| Both values truncate to the same logical tick count at the selected game speed.<br />
|-<br />
| An animation never advances.<br />
| Its delay is infinite, its animation has stopped, or external logic is holding or replacing its state.<br />
|-<br />
| A non-looping animation does not repeat.<br />
| This is expected unless native logic or a script selects the animation again.<br />
|}<br />
<br />
When debugging an animation, begin with a minimal definition containing <code>anim</code>, <code>delay</code>, <code>offset</code>, and <code>frame</code>. Confirm its images, alignment, and timing before adding collision, movement, effects, or scripts.<br />
[[Category:Openbor]]<br />
[[Category:Animation]]<br />
[[Category:Model]]</div>Dcurrenthttps://chronocrash.com/openbor/wiki/index.php?title=Animation_Overview&diff=1105Animation Overview2026-09-27T13:21:21Z<p>Dcurrent: /* Animation identifiers */</p>
<hr />
<div>Animations are one of OpenBOR's fundamental building blocks. Models use animations to describe how they look and behave over time. Walking, standing, attacking, falling, taking damage, and many other actions are represented by ordered animation frames.<br />
<br />
Each animation belongs to a model and occupies a recognized animation slot such as <code>idle</code>, <code>walk</code>, <code>jump</code>, <code>pain</code>, or <code>attack1</code>. OpenBOR's native logic selects many of these slots automatically. Scripts may also select an animation or frame directly.<br />
<br />
An animation frame is more than an image. It may also contain timing, offsets, collision boxes, movement, sounds, draw settings, entity spawns, and other behavior.__TOC__<br />
<br />
== Basic structure ==<br />
<br />
The <code>anim</code> command begins an animation definition. Commands following it configure the animation or prepare properties for its frames. Each <code>frame</code> command adds one frame using the properties currently in effect.<br />
<br />
<syntaxhighlight lang="text"><br />
anim idle<br />
loop 1<br />
delay 12<br />
offset 32 96<br />
<br />
frame data/chars/example/idle_01.png<br />
frame data/chars/example/idle_02.png<br />
frame data/chars/example/idle_03.png<br />
</syntaxhighlight><br />
<br />
This example creates a looping idle animation with three frames. With the default centisecond delay unit, each frame lasts 0.12 seconds.<br />
<br />
Indentation and blank lines are optional, but they make animation blocks easier to read.<br />
<br />
=== Animation identifiers ===<br />
<br />
The value following <code>anim</code> identifies the animation's purpose. Common examples include:<br />
<br />
{| class="wikitable"<br />
! Identifier<br />
! Typical purpose<br />
|-<br />
| <code>idle</code><br />
| Standing without moving.<br />
|-<br />
| <code>walk</code><br />
| Ordinary movement.<br />
|-<br />
| <code>jump</code><br />
| Initial or rising jump state.<br />
|-<br />
| <code>land</code><br />
| Landing from a jump or fall.<br />
|-<br />
| <code>pain</code><br />
| Reacting to damage.<br />
|-<br />
| <code>fall</code><br />
| Knockdown or falling reaction.<br />
|-<br />
| <code>rise</code><br />
| Recovering from a fall.<br />
|-<br />
| <code>attack1</code><br />
| A native attack animation.<br />
|-<br />
| <code>freespecial1</code><br />
| A creator-configured special move.<br />
|-<br />
|<code>follow</code><br />
|General use animations inaccessible to native engine logic and only activated by creator defined follow triggers or scripts.<br />
|}<br />
<br />
Animation identifiers are behavioral slots, not arbitrary labels. Supplying an animation makes the corresponding behavior available to native engine logic and scripts. Some model types require certain animations to operate normally, while others are optional.<br />
<br />
== Frame construction ==<br />
<br />
OpenBOR reads model files from top to bottom. Frame property commands update temporary state, and <code>frame</code> commits a copy of that state to the animation.<br />
<br />
<syntaxhighlight lang="text"><br />
anim idle<br />
loop 1<br />
offset 32 96<br />
<br />
delay 10<br />
frame data/chars/example/idle_01.png<br />
<br />
delay 25<br />
frame data/chars/example/idle_02.png<br />
</syntaxhighlight><br />
<br />
The first frame receives a delay of 10. The second receives a delay of 25 because the delay changes before its <code>frame</code> command.<br />
<br />
Commands placed after a <code>frame</code> line cannot alter the frame that was already added. Most frame properties remain active for subsequent frames until another command changes or disables them. Some one-shot properties, such as a frame sound, reset after the frame is added.<br />
<br />
Define important state explicitly in each animation. In particular, specifying a delay inside every animation avoids accidentally inheriting a previously active delay while the model file is being parsed.<br />
=== Frame numbering ===<br />
Frames use zero-based indexes. The first frame line is frame 0, the second is frame 1, and so on. Commands that target a frame number use these indexes unless their own documentation states otherwise.<br />
<br />
The same image may appear more than once when different timing or behavior is needed. OpenBOR reuses its globally cached pixel data, so repeating an image does not require another pixel-data allocation.<br />
<br />
Frame <code>none</code> adds a logical frame without a visible sprite, which can be useful for invisible states or script-controlled behavior.<br />
<br />
== Offsets ==<br />
<br />
The <code>offset</code> command selects the anchor point inside a frame image.<br />
<br />
<syntaxhighlight lang="text"><br />
offset 32 96<br />
frame data/chars/example/idle_01.png<br />
</syntaxhighlight><br />
<br />
OpenBOR places the selected point at the entity's world position. For a standing character, the anchor is usually near the ground between the character's feet.<br />
<br />
Choose a consistent animation canvas size during production and align every source frame to the same anchor before export. Guides for the ground line and horizontal center make this much faster than correcting alignment one frame at a time in the model file.<br />
<br />
OpenBOR automatically trims unused image space when it loads sprites. Consistent source canvases are still useful because the trimming process preserves the intended relationship between the artwork and its anchor without retaining transparent padding in memory.<br />
<br />
Poor source alignment makes an entity appear to shake, slide, or change height when frames cycle. Per-frame offset changes remain available for deliberate repositioning or assets that cannot be realigned, but they should generally be the exception rather than the primary production workflow.<br />
<br />
== Looping ==<br />
Animations do not loop unless looping is enabled.<syntaxhighlight lang="text"><br />
loop {enable} {loop frame - optional} {end frame - optional}<br />
<br />
# Default<br />
loop 0 0 0<br />
</syntaxhighlight>loop <code>1</code> repeats the animation. loop <code>0</code> disables looping.<br />
<br />
The optional loop frame selects the zero-based frame to return to when the animation repeats. The optional end frame is an exclusive boundary - when playback reaches that frame index, it returns to the selected loop frame instead of displaying the boundary frame. <br />
<br />
For example, if end frame is <code>7</code>, frame <code>7</code> - the sixth frame, does not display - the animation instantly loops on reaching that frame. If end frame is not provided animation proceeds to the last frame and loops.<br />
<br />
Idle and walk animations commonly loop. Attacks, pain reactions, falls, and transitions commonly play once and stop on their final frame until native logic or a script selects another animation.<br />
<br />
== Delay ==<br />
<br />
Delay controls how long a frame remains active before OpenBOR advances the animation. The command is stateful and applies to each following frame until another <code>delay</code> command changes it.<br />
<br />
=== Syntax ===<br />
<br />
<syntaxhighlight lang="text"><br />
delay <value> [unit]<br />
</syntaxhighlight><br />
<br />
The unit is optional. Omitting it is equivalent to selecting <code>global</code>.<br />
<br />
<syntaxhighlight lang="text"><br />
delay 10<br />
delay 10 global<br />
</syntaxhighlight><br />
<br />
Both examples use the module's global delay unit.<br />
<br />
=== Delay units ===<br />
Optional time unit setting. <br />
{| class="wikitable"<br />
! Unit<br />
! Meaning<br />
|-<br />
| <code>global</code><br />
| Uses the unit selected by <code>global_config_delay_unit</code> in <code>data/models.txt</code>. This is the default mode.<br />
|-<br />
| <code>millisecond</code><br />
| Interprets the value as thousandths of a second.<br />
|-<br />
| <code>centisecond</code><br />
| Interprets the value as hundredths of a second. This is the default global unit and preserves traditional OpenBOR timing.<br />
|-<br />
| <code>second</code><br />
| Interprets the value as seconds.<br />
|-<br />
| <code>minute</code><br />
| Interprets the value as minutes.<br />
|-<br />
| <code>direct</code><br />
| Stores the value directly as logical clock ticks without time-unit conversion.<br />
|}<br />
<br />
OpenBOR converts the supplied value from the selected unit into logical clock ticks. See [[Animation Overview#Logical clock precision|Logical clock precision]].<br />
<br />
Examples:<br />
<br />
<syntaxhighlight lang="text"><br />
delay 250 millisecond<br />
delay 25 centisecond<br />
delay 2 second<br />
delay 1 minute<br />
delay 50 direct<br />
</syntaxhighlight><br />
<br />
Singular unit names are required.<br />
<br />
=== Global delay unit ===<br />
<br />
Use <code>global_config_delay_unit</code> in <code>data/models.txt</code> to select the unit used by unqualified and explicitly global delays.<br />
<br />
<syntaxhighlight lang="text"><br />
global_config_delay_unit centisecond<br />
</syntaxhighlight><br />
<br />
The setting accepts <code>millisecond</code>, <code>centisecond</code>, <code>second</code>, <code>minute</code>, or <code>direct</code>. It does not accept <code>global</code>, because the global setting must resolve to a concrete unit.<br />
<br />
If the command is omitted, the global unit is <code>centisecond</code>. Changing the setting reinterprets every model delay that uses <code>global</code>, so modules should choose a unit deliberately. Explicit frame units remain independent of the global selection.<br />
<br />
The setting is read while models are loaded. OpenBOR converts each delay to logical ticks and stores the converted result with the animation frame. It is not a runtime timing switch for animations that are already loaded.<br />
<br />
=== Logical clock precision ===<br />
<br />
OpenBOR animation timing ultimately uses whole logical clock ticks. Unit conversion follows these relationships:<br />
<br />
<syntaxhighlight lang="text"><br />
millisecond = value * game speed / 1000<br />
centisecond = value * game speed / 100<br />
second = value * game speed<br />
minute = value * game speed * 60<br />
direct = value<br />
</syntaxhighlight><br />
<br />
Fractional results truncate. No time unit can represent a duration smaller than the module's logical clock precision, and any fractional remainder is discarded.<br />
<br />
For example, at the default game speed of 200 ticks per second, each logical tick represents 5 milliseconds. Any value from 15 through 19 milliseconds therefore converts to three ticks, representing 15 milliseconds, while 20 milliseconds converts exactly to four ticks.<br />
<br />
The <code>direct</code> unit is useful when exact integration with the logical clock matters. Its real-time duration changes with game speed because its value is already a tick count. By pairing a game speed evenly divisible by a target frame rate with direct delays, creators can time animations in exact frame intervals. For example, a game speed of 240 provides four logical ticks for each frame at 60 Hz. This supports frame-based timing conventions commonly used by the fighting game community and fixed-refresh console games.<br />
<br />
=== Infinite delay ===<br />
<br />
Use <code>infinite</code> or the infinity symbol <code>∞</code> when a frame should not advance through ordinary clock timing.<br />
<br />
<syntaxhighlight lang="text"><br />
anim idle<br />
delay infinite<br />
offset 32 96<br />
frame data/chars/example/idle_01.png<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="text"><br />
delay ∞<br />
</syntaxhighlight><br />
<br />
An infinite frame remains active until something outside normal timing changes its animation or frame. Scripts may use the <code>DELAY_INFINITE</code> constant for the same engine value.<br />
<br />
The word <code>infinite</code> is the most portable model-file spelling. The <code>∞</code> form is UTF-8 text and may be damaged by old Windows editors, archive tools, or other utilities that do not preserve Unicode correctly.<br />
<br />
Any negative numeric delay also becomes infinite for backward compatibility. New content should use <code>infinite</code> or <code>∞</code> so its intent is explicit.<br />
<br />
=== Finite range and behavior flags ===<br />
<br />
Finite delay values use the lower 32 bits of an unsigned 64-bit value. The largest finite value is 4,294,967,295 - in default centisecond units, roughly 16 months. Conversions that would exceed this limit clamp to the largest finite delay instead of overflowing or accidentally becoming infinite.<br />
<br />
The upper 32 bits are reserved for delay behavior flags. Bit 63 is the infinite flag. Enhanced-delay calculations modify only the finite lower value and preserve behavior flags, so an infinite frame cannot accidentally become finite.<br />
<br />
=== Enhanced delay ===<br />
<br />
[[Enhanced Delay|Enhanced delay]], or <code>edelay</code>, adjusts frame delays through a model's multiplier, modifier, range, and cap settings. These calculations occur after time-unit conversion, so enhanced-delay ranges, modifiers, and caps operate on logical tick values rather than the source unit written in the animation.<br />
<br />
Enhanced-delay arithmetic is bounded to the finite delay range. It cannot overflow into behavior flags or create an infinite delay through calculation.<br />
<br />
== Frame properties ==<br />
<br />
Timing and graphics form only the minimum animation. Frame property commands can add behavior such as:<br />
<br />
{| class="wikitable"<br />
! Property<br />
! Purpose<br />
|-<br />
| <code>bbox</code><br />
| Defines the frame's body collision area. Use <code>bbox none</code> to disable it.<br />
|-<br />
| Attack collision commands<br />
| Define areas that damage or otherwise affect targets.<br />
|-<br />
| <code>move</code>, <code>movea</code>, and <code>movez</code><br />
| Apply frame movement along the model's axes.<br />
|-<br />
| <code>sound</code><br />
| Plays a sound when the frame begins.<br />
|-<br />
| Draw commands<br />
| Change scaling, rotation, transparency, remapping, clipping, and other rendering behavior.<br />
|-<br />
| Spawn commands<br />
| Create or summon child entities on selected frames.<br />
|-<br />
| Animation scripts<br />
| Execute creator-defined logic as frames change.<br />
|}<br />
<br />
Property commands normally appear before the <code>frame</code> they configure:<br />
<br />
<syntaxhighlight lang="text"><br />
anim idle<br />
loop 1<br />
delay 10<br />
offset 32 96<br />
<br />
bbox 12 20 40 76 10<br />
frame data/chars/example/idle_01.png<br />
<br />
bbox none<br />
frame data/chars/example/idle_02.png<br />
</syntaxhighlight><br />
<br />
The first frame has a body collision box. The second does not because <code>bbox none</code> changes the pending frame state before the second <code>frame</code> command.<br />
<br />
== Practical example ==<br />
<br />
<syntaxhighlight lang="text"><br />
anim idle<br />
loop 1<br />
offset 32 96<br />
bbox 12 20 40 76 10<br />
<br />
delay 100 millisecond<br />
frame data/chars/example/idle_01.png<br />
<br />
delay 150 millisecond<br />
frame data/chars/example/idle_02.png<br />
<br />
delay 100 millisecond<br />
frame data/chars/example/idle_03.png<br />
<br />
<br />
anim attack1<br />
loop 0<br />
offset 40 96<br />
delay 80 millisecond<br />
<br />
frame data/chars/example/attack_01.png<br />
<br />
move 4<br />
frame data/chars/example/attack_02.png<br />
<br />
move 0<br />
delay 160 millisecond<br />
frame data/chars/example/attack_03.png<br />
</syntaxhighlight><br />
<br />
The idle animation loops with intentionally uneven timing. The attack plays once, moves the entity during its second frame, stops that movement before the third frame, and holds the final attack pose longer.<br />
<br />
== Common problems ==<br />
<br />
{| class="wikitable"<br />
! Symptom<br />
! Likely cause<br />
|-<br />
| Frames appear to shake or slide.<br />
| Offsets do not align the same visual anchor across images.<br />
|-<br />
| A property affects the wrong frame.<br />
| The property command appears after the intended <code>frame</code> line, or persistent frame state was not changed before the next frame.<br />
|-<br />
| An animation plays much too quickly or slowly.<br />
| The delay unit or <code>global_config_delay_unit</code> does not match the values used by the model.<br />
|-<br />
| Very small delays appear identical.<br />
| Both values truncate to the same logical tick count at the selected game speed.<br />
|-<br />
| An animation never advances.<br />
| Its delay is infinite, its animation has stopped, or external logic is holding or replacing its state.<br />
|-<br />
| A non-looping animation does not repeat.<br />
| This is expected unless native logic or a script selects the animation again.<br />
|}<br />
<br />
When debugging an animation, begin with a minimal definition containing <code>anim</code>, <code>delay</code>, <code>offset</code>, and <code>frame</code>. Confirm its images, alignment, and timing before adding collision, movement, effects, or scripts.<br />
[[Category:Openbor]]<br />
[[Category:Animation]]<br />
[[Category:Model]]</div>Dcurrenthttps://chronocrash.com/openbor/wiki/index.php?title=Animation_Overview&diff=1104Animation Overview2026-09-27T13:17:01Z<p>Dcurrent: /* Finite range and behavior flags */</p>
<hr />
<div>Animations are one of OpenBOR's fundamental building blocks. Models use animations to describe how they look and behave over time. Walking, standing, attacking, falling, taking damage, and many other actions are represented by ordered animation frames.<br />
<br />
Each animation belongs to a model and occupies a recognized animation slot such as <code>idle</code>, <code>walk</code>, <code>jump</code>, <code>pain</code>, or <code>attack1</code>. OpenBOR's native logic selects many of these slots automatically. Scripts may also select an animation or frame directly.<br />
<br />
An animation frame is more than an image. It may also contain timing, offsets, collision boxes, movement, sounds, draw settings, entity spawns, and other behavior.__TOC__<br />
<br />
== Basic structure ==<br />
<br />
The <code>anim</code> command begins an animation definition. Commands following it configure the animation or prepare properties for its frames. Each <code>frame</code> command adds one frame using the properties currently in effect.<br />
<br />
<syntaxhighlight lang="text"><br />
anim idle<br />
loop 1<br />
delay 12<br />
offset 32 96<br />
<br />
frame data/chars/example/idle_01.png<br />
frame data/chars/example/idle_02.png<br />
frame data/chars/example/idle_03.png<br />
</syntaxhighlight><br />
<br />
This example creates a looping idle animation with three frames. With the default centisecond delay unit, each frame lasts 0.12 seconds.<br />
<br />
Indentation and blank lines are optional, but they make animation blocks easier to read.<br />
<br />
=== Animation identifiers ===<br />
<br />
The value following <code>anim</code> identifies the animation's purpose. Common examples include:<br />
<br />
{| class="wikitable"<br />
! Identifier<br />
! Typical purpose<br />
|-<br />
| <code>idle</code><br />
| Standing without moving.<br />
|-<br />
| <code>walk</code><br />
| Ordinary movement.<br />
|-<br />
| <code>jump</code><br />
| Initial or rising jump state.<br />
|-<br />
| <code>land</code><br />
| Landing from a jump or fall.<br />
|-<br />
| <code>pain</code><br />
| Reacting to damage.<br />
|-<br />
| <code>fall</code><br />
| Knockdown or falling reaction.<br />
|-<br />
| <code>rise</code><br />
| Recovering from a fall.<br />
|-<br />
| <code>attack1</code><br />
| A native attack animation.<br />
|-<br />
| <code>freespecial1</code><br />
| A creator-configured special move.<br />
|}<br />
<br />
Animation identifiers are behavioral slots, not arbitrary labels. Supplying an animation makes the corresponding behavior available to native engine logic and scripts. Some model types require certain animations to operate normally, while others are optional.<br />
<br />
== Frame construction ==<br />
<br />
OpenBOR reads model files from top to bottom. Frame property commands update temporary state, and <code>frame</code> commits a copy of that state to the animation.<br />
<br />
<syntaxhighlight lang="text"><br />
anim idle<br />
loop 1<br />
offset 32 96<br />
<br />
delay 10<br />
frame data/chars/example/idle_01.png<br />
<br />
delay 25<br />
frame data/chars/example/idle_02.png<br />
</syntaxhighlight><br />
<br />
The first frame receives a delay of 10. The second receives a delay of 25 because the delay changes before its <code>frame</code> command.<br />
<br />
Commands placed after a <code>frame</code> line cannot alter the frame that was already added. Most frame properties remain active for subsequent frames until another command changes or disables them. Some one-shot properties, such as a frame sound, reset after the frame is added.<br />
<br />
Define important state explicitly in each animation. In particular, specifying a delay inside every animation avoids accidentally inheriting a previously active delay while the model file is being parsed.<br />
=== Frame numbering ===<br />
Frames use zero-based indexes. The first frame line is frame 0, the second is frame 1, and so on. Commands that target a frame number use these indexes unless their own documentation states otherwise.<br />
<br />
The same image may appear more than once when different timing or behavior is needed. OpenBOR reuses its globally cached pixel data, so repeating an image does not require another pixel-data allocation.<br />
<br />
Frame <code>none</code> adds a logical frame without a visible sprite, which can be useful for invisible states or script-controlled behavior.<br />
<br />
== Offsets ==<br />
<br />
The <code>offset</code> command selects the anchor point inside a frame image.<br />
<br />
<syntaxhighlight lang="text"><br />
offset 32 96<br />
frame data/chars/example/idle_01.png<br />
</syntaxhighlight><br />
<br />
OpenBOR places the selected point at the entity's world position. For a standing character, the anchor is usually near the ground between the character's feet.<br />
<br />
Choose a consistent animation canvas size during production and align every source frame to the same anchor before export. Guides for the ground line and horizontal center make this much faster than correcting alignment one frame at a time in the model file.<br />
<br />
OpenBOR automatically trims unused image space when it loads sprites. Consistent source canvases are still useful because the trimming process preserves the intended relationship between the artwork and its anchor without retaining transparent padding in memory.<br />
<br />
Poor source alignment makes an entity appear to shake, slide, or change height when frames cycle. Per-frame offset changes remain available for deliberate repositioning or assets that cannot be realigned, but they should generally be the exception rather than the primary production workflow.<br />
<br />
== Looping ==<br />
Animations do not loop unless looping is enabled.<syntaxhighlight lang="text"><br />
loop {enable} {loop frame - optional} {end frame - optional}<br />
<br />
# Default<br />
loop 0 0 0<br />
</syntaxhighlight>loop <code>1</code> repeats the animation. loop <code>0</code> disables looping.<br />
<br />
The optional loop frame selects the zero-based frame to return to when the animation repeats. The optional end frame is an exclusive boundary - when playback reaches that frame index, it returns to the selected loop frame instead of displaying the boundary frame. <br />
<br />
For example, if end frame is <code>7</code>, frame <code>7</code> - the sixth frame, does not display - the animation instantly loops on reaching that frame. If end frame is not provided animation proceeds to the last frame and loops.<br />
<br />
Idle and walk animations commonly loop. Attacks, pain reactions, falls, and transitions commonly play once and stop on their final frame until native logic or a script selects another animation.<br />
<br />
== Delay ==<br />
<br />
Delay controls how long a frame remains active before OpenBOR advances the animation. The command is stateful and applies to each following frame until another <code>delay</code> command changes it.<br />
<br />
=== Syntax ===<br />
<br />
<syntaxhighlight lang="text"><br />
delay <value> [unit]<br />
</syntaxhighlight><br />
<br />
The unit is optional. Omitting it is equivalent to selecting <code>global</code>.<br />
<br />
<syntaxhighlight lang="text"><br />
delay 10<br />
delay 10 global<br />
</syntaxhighlight><br />
<br />
Both examples use the module's global delay unit.<br />
<br />
=== Delay units ===<br />
Optional time unit setting. <br />
{| class="wikitable"<br />
! Unit<br />
! Meaning<br />
|-<br />
| <code>global</code><br />
| Uses the unit selected by <code>global_config_delay_unit</code> in <code>data/models.txt</code>. This is the default mode.<br />
|-<br />
| <code>millisecond</code><br />
| Interprets the value as thousandths of a second.<br />
|-<br />
| <code>centisecond</code><br />
| Interprets the value as hundredths of a second. This is the default global unit and preserves traditional OpenBOR timing.<br />
|-<br />
| <code>second</code><br />
| Interprets the value as seconds.<br />
|-<br />
| <code>minute</code><br />
| Interprets the value as minutes.<br />
|-<br />
| <code>direct</code><br />
| Stores the value directly as logical clock ticks without time-unit conversion.<br />
|}<br />
<br />
OpenBOR converts the supplied value from the selected unit into logical clock ticks. See [[Animation Overview#Logical clock precision|Logical clock precision]].<br />
<br />
Examples:<br />
<br />
<syntaxhighlight lang="text"><br />
delay 250 millisecond<br />
delay 25 centisecond<br />
delay 2 second<br />
delay 1 minute<br />
delay 50 direct<br />
</syntaxhighlight><br />
<br />
Singular unit names are required.<br />
<br />
=== Global delay unit ===<br />
<br />
Use <code>global_config_delay_unit</code> in <code>data/models.txt</code> to select the unit used by unqualified and explicitly global delays.<br />
<br />
<syntaxhighlight lang="text"><br />
global_config_delay_unit centisecond<br />
</syntaxhighlight><br />
<br />
The setting accepts <code>millisecond</code>, <code>centisecond</code>, <code>second</code>, <code>minute</code>, or <code>direct</code>. It does not accept <code>global</code>, because the global setting must resolve to a concrete unit.<br />
<br />
If the command is omitted, the global unit is <code>centisecond</code>. Changing the setting reinterprets every model delay that uses <code>global</code>, so modules should choose a unit deliberately. Explicit frame units remain independent of the global selection.<br />
<br />
The setting is read while models are loaded. OpenBOR converts each delay to logical ticks and stores the converted result with the animation frame. It is not a runtime timing switch for animations that are already loaded.<br />
<br />
=== Logical clock precision ===<br />
<br />
OpenBOR animation timing ultimately uses whole logical clock ticks. Unit conversion follows these relationships:<br />
<br />
<syntaxhighlight lang="text"><br />
millisecond = value * game speed / 1000<br />
centisecond = value * game speed / 100<br />
second = value * game speed<br />
minute = value * game speed * 60<br />
direct = value<br />
</syntaxhighlight><br />
<br />
Fractional results truncate. No time unit can represent a duration smaller than the module's logical clock precision, and any fractional remainder is discarded.<br />
<br />
For example, at the default game speed of 200 ticks per second, each logical tick represents 5 milliseconds. Any value from 15 through 19 milliseconds therefore converts to three ticks, representing 15 milliseconds, while 20 milliseconds converts exactly to four ticks.<br />
<br />
The <code>direct</code> unit is useful when exact integration with the logical clock matters. Its real-time duration changes with game speed because its value is already a tick count. By pairing a game speed evenly divisible by a target frame rate with direct delays, creators can time animations in exact frame intervals. For example, a game speed of 240 provides four logical ticks for each frame at 60 Hz. This supports frame-based timing conventions commonly used by the fighting game community and fixed-refresh console games.<br />
<br />
=== Infinite delay ===<br />
<br />
Use <code>infinite</code> or the infinity symbol <code>∞</code> when a frame should not advance through ordinary clock timing.<br />
<br />
<syntaxhighlight lang="text"><br />
anim idle<br />
delay infinite<br />
offset 32 96<br />
frame data/chars/example/idle_01.png<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="text"><br />
delay ∞<br />
</syntaxhighlight><br />
<br />
An infinite frame remains active until something outside normal timing changes its animation or frame. Scripts may use the <code>DELAY_INFINITE</code> constant for the same engine value.<br />
<br />
The word <code>infinite</code> is the most portable model-file spelling. The <code>∞</code> form is UTF-8 text and may be damaged by old Windows editors, archive tools, or other utilities that do not preserve Unicode correctly.<br />
<br />
Any negative numeric delay also becomes infinite for backward compatibility. New content should use <code>infinite</code> or <code>∞</code> so its intent is explicit.<br />
<br />
=== Finite range and behavior flags ===<br />
<br />
Finite delay values use the lower 32 bits of an unsigned 64-bit value. The largest finite value is 4,294,967,295 - in default centisecond units, roughly 16 months. Conversions that would exceed this limit clamp to the largest finite delay instead of overflowing or accidentally becoming infinite.<br />
<br />
The upper 32 bits are reserved for delay behavior flags. Bit 63 is the infinite flag. Enhanced-delay calculations modify only the finite lower value and preserve behavior flags, so an infinite frame cannot accidentally become finite.<br />
<br />
=== Enhanced delay ===<br />
<br />
[[Enhanced Delay|Enhanced delay]], or <code>edelay</code>, adjusts frame delays through a model's multiplier, modifier, range, and cap settings. These calculations occur after time-unit conversion, so enhanced-delay ranges, modifiers, and caps operate on logical tick values rather than the source unit written in the animation.<br />
<br />
Enhanced-delay arithmetic is bounded to the finite delay range. It cannot overflow into behavior flags or create an infinite delay through calculation.<br />
<br />
== Frame properties ==<br />
<br />
Timing and graphics form only the minimum animation. Frame property commands can add behavior such as:<br />
<br />
{| class="wikitable"<br />
! Property<br />
! Purpose<br />
|-<br />
| <code>bbox</code><br />
| Defines the frame's body collision area. Use <code>bbox none</code> to disable it.<br />
|-<br />
| Attack collision commands<br />
| Define areas that damage or otherwise affect targets.<br />
|-<br />
| <code>move</code>, <code>movea</code>, and <code>movez</code><br />
| Apply frame movement along the model's axes.<br />
|-<br />
| <code>sound</code><br />
| Plays a sound when the frame begins.<br />
|-<br />
| Draw commands<br />
| Change scaling, rotation, transparency, remapping, clipping, and other rendering behavior.<br />
|-<br />
| Spawn commands<br />
| Create or summon child entities on selected frames.<br />
|-<br />
| Animation scripts<br />
| Execute creator-defined logic as frames change.<br />
|}<br />
<br />
Property commands normally appear before the <code>frame</code> they configure:<br />
<br />
<syntaxhighlight lang="text"><br />
anim idle<br />
loop 1<br />
delay 10<br />
offset 32 96<br />
<br />
bbox 12 20 40 76 10<br />
frame data/chars/example/idle_01.png<br />
<br />
bbox none<br />
frame data/chars/example/idle_02.png<br />
</syntaxhighlight><br />
<br />
The first frame has a body collision box. The second does not because <code>bbox none</code> changes the pending frame state before the second <code>frame</code> command.<br />
<br />
== Practical example ==<br />
<br />
<syntaxhighlight lang="text"><br />
anim idle<br />
loop 1<br />
offset 32 96<br />
bbox 12 20 40 76 10<br />
<br />
delay 100 millisecond<br />
frame data/chars/example/idle_01.png<br />
<br />
delay 150 millisecond<br />
frame data/chars/example/idle_02.png<br />
<br />
delay 100 millisecond<br />
frame data/chars/example/idle_03.png<br />
<br />
<br />
anim attack1<br />
loop 0<br />
offset 40 96<br />
delay 80 millisecond<br />
<br />
frame data/chars/example/attack_01.png<br />
<br />
move 4<br />
frame data/chars/example/attack_02.png<br />
<br />
move 0<br />
delay 160 millisecond<br />
frame data/chars/example/attack_03.png<br />
</syntaxhighlight><br />
<br />
The idle animation loops with intentionally uneven timing. The attack plays once, moves the entity during its second frame, stops that movement before the third frame, and holds the final attack pose longer.<br />
<br />
== Common problems ==<br />
<br />
{| class="wikitable"<br />
! Symptom<br />
! Likely cause<br />
|-<br />
| Frames appear to shake or slide.<br />
| Offsets do not align the same visual anchor across images.<br />
|-<br />
| A property affects the wrong frame.<br />
| The property command appears after the intended <code>frame</code> line, or persistent frame state was not changed before the next frame.<br />
|-<br />
| An animation plays much too quickly or slowly.<br />
| The delay unit or <code>global_config_delay_unit</code> does not match the values used by the model.<br />
|-<br />
| Very small delays appear identical.<br />
| Both values truncate to the same logical tick count at the selected game speed.<br />
|-<br />
| An animation never advances.<br />
| Its delay is infinite, its animation has stopped, or external logic is holding or replacing its state.<br />
|-<br />
| A non-looping animation does not repeat.<br />
| This is expected unless native logic or a script selects the animation again.<br />
|}<br />
<br />
When debugging an animation, begin with a minimal definition containing <code>anim</code>, <code>delay</code>, <code>offset</code>, and <code>frame</code>. Confirm its images, alignment, and timing before adding collision, movement, effects, or scripts.<br />
[[Category:Openbor]]<br />
[[Category:Animation]]<br />
[[Category:Model]]</div>Dcurrenthttps://chronocrash.com/openbor/wiki/index.php?title=Rgbcolor()&diff=1103Rgbcolor()2026-09-27T04:47:13Z<p>Dcurrent: Redirected page to Direct Drawing#Colors and blend modes</p>
<hr />
<div>#REDIRECT [[Direct Drawing#Colors and blend modes]]<br />
[[Category:OpenBOR Index]]<br />
[[Category:Script Functions]]<br />
[[Category:Graphics]]</div>Dcurrenthttps://chronocrash.com/openbor/wiki/index.php?title=OpenBOR_Overview&diff=1100OpenBOR Overview2026-09-11T18:33:04Z<p>Dcurrent: /* Animations */</p>
<hr />
<div>This article provides a general overview of how the OpenBOR engine organizes and operates a game module. Individual systems and commands are covered in their respective articles.<br />
<br />
'''Rule 0:''' OpenBOR’s native behaviors are starting defaults, not immutable rules. Virtually every system can be adjusted, extended, or replaced through configuration and script.<br />
<br />
== Engine Structure ==<br />
An OpenBOR game consists of two principal components:<br />
<br />
* '''Engine''' – The executable and supporting platform files that provide OpenBOR’s runtime systems.<br />
* '''Module''' – The game’s configuration, models, levels, scripts, graphics, and audio.<br />
<br />
During development, a module may be loaded directly from an unpacked <code>data</code> directory. For distribution, the same directory can be packaged into a <code>.pak</code> file.<br />
<br />
Packaged game modules may contain up to 2 GB of data in the legacy pack format, or about 9 exabytes in the modern 64-bit format. <br />
<br />
== Module Layout ==<br />
A typical unpacked module has the following layout:<pre><br />
data/<br />
├── models.txt<br />
├── levels.txt<br />
├── video.txt<br />
├── lifebar.txt<br />
├── menu.txt<br />
├── script.txt<br />
├── bgs/<br />
├── chars/<br />
├── levels/<br />
├── music/<br />
├── scenes/<br />
├── sounds/<br />
├── sprites/<br />
└── scripts/<br />
</pre>The subdirectory names are organizational conventions. Creators may use any directory structure they prefer as long as referenced paths are correct. <br />
<br />
The principal root files are:<br />
<br />
* [[Model Registry|models.txt]] – Registers entity models, controls how they are loaded, and provides several model-related module settings.<br />
* <code>levels.txt</code> – Defines level sets, game modes, stage order, and several general level and interface settings.<br />
* <code>video.txt</code> – Optional display and video configuration.<br />
* <code>lifebar.txt</code> – Optional lifebar presentation configuration.<br />
* <code>menu.txt</code> – Optional menu configuration.<br />
* <code>script.txt</code> – Optional scripting limits and global script behavior.<br />
Do not be misled by the use of .txt format. OpenBOR’s configuration files are declarative object and asset definitions, not a linear instruction stream. The engine parses them into structured runtime data used by native systems and scripts.<br />
<br />
== Models and Entities ==<br />
A '''model''' is a template describing an object available to the engine. Players, enemies, items, obstacles, projectiles, effects, and many utility objects are all models.<br />
<br />
An '''entity''' is a runtime instance of a model. When OpenBOR spawns a model, it creates an entity and copies the model’s initial properties into it. Native logic and scripts may then modify that entity independently.<br />
<br />
Model files may define statistics, movement, artificial intelligence, animations, attacks, defense, collision, palettes, sounds, projectiles, and event scripts.<br />
<br />
See [[Models]] and [[Entities]].<br />
<br />
== Animations ==<br />
Animations organize an entity’s visual frames, timing, and actions. OpenBOR recognizes animation types such as <code>IDLE</code>, <code>WALK</code>, <code>ATTACK</code>, <code>PAIN</code>, <code>FALL</code>, and <code>RISE</code> and uses them to control common entity behavior.<br />
<br />
Animation data may include:<br />
<br />
* Sprite frames and delays.<br />
* Entity-origin offsets.<br />
* Attack and body collision boxes.<br />
* Movement and velocity instructions.<br />
* Sounds and visual effects.<br />
* Spawned entities.<br />
* Frame-specific commands and scripts.<br />
<br />
Animations therefore serve as both visual sequences and configurable entity states.<br />
<br />
See [[Animation Overview|Animations]].<br />
<br />
== Levels and Level Sets ==<br />
A '''level''' describes a playable area. Level files arrange backgrounds, terrain, boundaries, spawn points, music, environmental objects, and other stage content.<br />
<br />
A '''level set''' is an ordered collection of levels and scenes declared in <code>levels.txt</code>. Level sets may represent game modes, routes, episodes, or difficulty selections.<br />
<br />
See [[Levels]], [[Level Sets]], and [[Scenes]].<br />
<br />
== Scenes and Media Playback ==<br />
OpenBOR provides native facilities for assembling audiovisual scenes and presenting prerecorded media. The scene system can combine music with animated .gif graphics, while .webm playback provides streamed full-motion video with no length or size limitations.<br />
<br />
These features are not limited to transitions or narrative cutscenes. Creators may use them for introductions, presentations, galleries, continuous media playback, or as a module’s primary content. OpenBOR may therefore function as a general multimedia framework or even a dedicated video player.<br />
<br />
See [[Scenes]] and [[WebM]].<br />
<br />
== Game World ==<br />
OpenBOR places entities in a three-dimensional Cartesian game field:<br />
<br />
* '''X''' – Horizontal position.<br />
* '''Y''' – Height.<br />
* '''Z''' – Lateral depth toward or away from the camera.<br />
* '''Base''' – The height on which an entity currently stands.<br />
<br />
The game world supports floating-point positions and velocity. OpenBOR projects these positions onto the two-dimensional display while managing screen placement, depth sorting, and smooth subpixel movement. For strictly 2D environments, creators may set Z position limits to identical values, and the engine will natively invoke two-dimensional world behaviors, including control maps like ducking.<br />
<br />
See [[Geometry Overview]].<br />
<br />
== Collision and Combat ==<br />
Collision boxes describe the physical areas used for attacks, damage reception, terrain, and entity contact.<br />
<br />
Attack properties determine the initial force and behavior of a hit. The attacker’s offense properties modify its damage output, after which the target’s defense properties modify the incoming result. Other properties control pain, knockdown, blocking, effects, and death behavior. <br />
<br />
* [[Collision]] - Defining collision boxes, including body (hurt) and attack.<br />
* [[Attack Type|Attack Types]] - Native reactive system to differing attack types.<br />
* [[Damage Control]] - Damage mitigation - defense and offense - for differing attack types.<br />
<br />
== Native Functionality ==<br />
OpenBOR provides native systems for common game functionality, including:<br />
<br />
* Player input and control mapping.<br />
* Movement, jumping, gravity, and platforms.<br />
* Enemy targeting and artificial intelligence.<br />
* Attacks, blocking, grabbing, throwing, and counters.<br />
* Damage, pain, knockdown, and death.<br />
* Projectiles, weapons, items, and summoned entities.<br />
* Cameras, scrolling, layers, palettes, and shadows.<br />
* Menus, player selection, HUD elements, and saved progress.<br />
* Music and sound effects.<br />
<br />
Creators may use these systems directly, combine their settings into new behaviors, or modify them through script.<br />
<br />
== Time ==<br />
OpenBOR separates gameplay timing from display updates. Its logical clock runs at 200 ticks per second by default and drives entity simulation, animations, effects, and most game logic, while the outer update and rendering loop may run independently at the selected frame rate. Scripts may also access host system time for real-world dates and timestamps. In addition, a traditional game countdown timer is enabled by default, beginning at 99 and decrementing once every two seconds, but creators may configure, hide, disable, or replace it.<br />
<br />
See [[Time]].<br />
<br />
== Scripting ==<br />
OpenBOR includes a C-like scripting engine for functionality beyond native configuration. Scripts can execute in response to engine updates, animation frames, input, collisions, damage, entity events, level events, and many other conditions.<br />
<br />
Scripts may inspect or modify engine objects, implement custom mechanics, draw graphics, control audio, manage data, and create reusable function libraries. See the following. <br />
<br />
* [[Script Overview]] - Detailed overview of script syntax and operators.<br />
* [[:Category:Script Functions|Script Functions]] - List of native script functions.<br />
* [[Variables Overview|Variables]] - Variable types and implications. <br />
* [[Strings]] - String specific functions.<br />
* [[Arrays]] - Arracy ad linked list API.<br />
* [[File Operations]] - File CRUD API.<br />
<br />
== Runtime Layout ==<br />
<br />
Module files provide the engine with models, levels, assets, and scripts. OpenBOR uses this information to construct the runtime game world, then continuously processes input, game logic, entity behavior, collision, and drawing.<br />
<br />
<pre><br />
MODULE DATA<br />
┌──────────────────┼──────────────────┐<br />
│ │ │<br />
models.txt levels.txt Assets and scripts<br />
│ │ │<br />
▼ ▼ ▼<br />
Model files Levels and scenes Graphics, audio,<br />
│ and custom logic<br />
└──────────────────┬──────────────────┘<br />
▼<br />
RUNTIME WORLD<br />
│<br />
▼<br />
┌──────────────── REPEATING ENGINE CYCLE ────────────────┐<br />
│ │<br />
│ Read player input │<br />
│ └─ Input and key script hooks │<br />
│ │<br />
│ Run global and level update scripts │<br />
│ │<br />
│ Update entities │<br />
│ ├─ Entity update and think script hooks │<br />
│ ├─ Player control and artificial intelligence │<br />
│ ├─ Animation and frame script hooks │<br />
│ ├─ Movement, gravity, and terrain │<br />
│ └─ Collision, attacks, damage, and reaction hooks │<br />
│ │<br />
│ Queue graphics │<br />
│ └─ Entity drawing script hooks │<br />
│ │<br />
│ Run post-update scripts │<br />
│ │<br />
│ Draw the completed frame and continue │<br />
│ │<br />
└────────────────────────────────────────────────────────┘<br />
</pre><br />
<br />
Script entry points are distributed throughout the runtime and may execute before, during, or after many engine operations. Hooks are available for input, updates, animation frames, movement, collisions, attacks, blocking, damage, spawning, drawing, death, level events, and numerous other conditions.<br />
<br />
When no script is supplied, OpenBOR performs its native behavior normally. Creators may therefore use the engine as provided, alter selected events, or replace large portions of the runtime with custom logic. This integration between native systems and event scripts is the basis of OpenBOR’s extensibility.<br />
<br />
== Graphic Layout ==<br />
OpenBOR’s native graphics pipeline uses WYSIWYG image assets that are automatically prepared and optimized for runtime. Background layers, sprites, shadows, effects, interface elements, and script-created subscreens are composited through a depth-sorted draw queue, with native support for effects like palette remapping, transparency, blending, scaling, rotation, and clipping. Script hooks allow creators to customize or replace rendering behavior throughout the pipeline. See [[Graphics Overview]].<br />
<br />
As of OpenBOR 4.x, all rendering and composition prior to the final <code>video_copy_screen()</code> presentation step are performed in software. This architecture is a legacy of OpenBOR’s historically broad platform support and is being phased out in favor of hardware-accelerated rendering.<pre><br />
Graphics Sources<br />
│<br />
├── Loaded Assets<br />
│ ├── Animation frames and sprites<br />
│ ├── Level backgrounds and graphic layers<br />
│ ├── Fonts and interface graphics<br />
│ └── Menu and scene graphics<br />
│<br />
├── Native Engine Rendering<br />
│ ├── Level layers and terrain<br />
│ ├── Entities, shadows, and effects<br />
│ ├── HUD and status displays<br />
│ └── Menus, text, and overlays<br />
│<br />
└── Script Rendering<br />
├── Sprites<br />
├── Text<br />
├── Lines, boxes, and other primitives<br />
└── Subscreen surfaces (s_screen)<br />
├── Allocate an off-screen surface<br />
├── Draw graphics onto the surface<br />
├── Combine multiple elements or surfaces<br />
└── Queue the completed surface with drawscreen()<br />
│<br />
▼<br />
Sprite/Draw Queue<br />
│<br />
├── Layer and Z ordering<br />
├── Position and clipping<br />
├── Palette and remap<br />
├── Transparency and blending<br />
└── Scaling, rotation, and other draw methods<br />
│<br />
▼<br />
Main Virtual Screen (vscreen)<br />
─────────────────────────────<br />
Queue contents are composited<br />
into the current video frame.<br />
│<br />
├── Optional screenshot capture<br />
└── Debug and final overlays<br />
│<br />
▼<br />
video_copy_screen()<br />
│<br />
├── Output scaling<br />
├── Video filtering<br />
├── Color adjustment<br />
└── Window or fullscreen presentation<br />
│<br />
▼<br />
Physical Display<br />
</pre><br />
[[Category:Openbor]]</div>Dcurrenthttps://chronocrash.com/openbor/wiki/index.php?title=Time&diff=1099Time2026-08-26T15:29:24Z<p>Dcurrent: /* Introduction */</p>
<hr />
<div>== Introduction ==<br />
<br />
Timing is crucial to OpenBOR, as it is to most game engines. Understanding how the engine measures time, and how those measurements affect a project, is therefore essential.<br />
<br />
OpenBOR uses a modern decoupled timing model by default. This means gameplay simulation and display rendering operate as independent loops, with the simulation advancing at regular 5-millisecond intervals.<br />
<br />
The gameplay loop advances movement, animation, collision, combat, entity behavior, and other world systems according to the logical clock. The rendering loop draws the latest available world state according to the selected display rate. Since neither loop depends on the other to advance, changes in display performance, refresh rate, or VSync behavior do not ordinarily change the speed or timing of gameplay.<br />
<br />
=== Logical Time vs. FPS ===<br />
<br />
Logical time controls how frequently OpenBOR updates the simulated game world. Frames per second, or FPS, control how frequently the display loop renders that world. These are separate rates serving different purposes.<br />
<br />
OpenBOR’s logical clock runs at 200 ticks per second by default. Each logical tick therefore represents 5 milliseconds. The display loop, running at 60 FPS, renders once every 16.67 milliseconds. Since the two loops are decoupled, they do not need to align one-to-one. Under these default rates, OpenBOR ordinarily processes three or four logical ticks between displayed frames.<br />
<br />
Gameplay durations remain based on logical time regardless of how often the world is drawn. Running the display loop at 60, 200, 500, VSync, or an unrestricted rate does not reinterpret an animation delay, effect duration, movement timer, or other logical-time value.<br />
<br />
OpenBOR also provides an optional frame-aligned timing mode for projects that use traditional frame-count conventions. Creators may configure the logical clock to a rate evenly divisible by the desired frame rate and express animation delays as direct logical ticks. For example, a 180 Hz logical clock provides exactly three logical ticks for every interval of a 60 Hz timeline:<br />
<br />
<code>delay 3 direct</code><br />
<br />
This represents one 60 Hz frame interval. Values of <code>6 direct</code>, <code>9 direct</code>, and <code>12 direct</code> represent two, three, and four frame intervals respectively. Frame-based timing can therefore be expressed exactly without coupling gameplay simulation to display rendering.<br />
<br />
See [[Animation Overview#Logical clock precision|Logical clock precision]] for more information about animation timing and direct delays.<br />
<br />
OpenBOR exposes the following primary measurements of time:<br />
<br />
=== Game Time ===<br />
<br />
Game Time is the traditional beat ’em up countdown used to maintain the pace of a level. It is a gameplay rule rather than the engine’s logical clock.<br />
<br />
When Game Time expires, players ordinarily lose a life. Creators may disable, remove, replace, or otherwise modify this behavior.<br />
<br />
See [[#Game Time|Game Time]].<br />
<br />
=== Elapsed Time ===<br />
<br />
Elapsed Time is the current level’s logical clock. It begins at `0` when active level gameplay starts and increments once for every processed logical tick.<br />
<br />
At the default 200 Hz logical rate, each increment represents 5 milliseconds. Animation timing, effect durations, entity simulation, and most other gameplay processes use Elapsed Time or values derived from it.<br />
<br />
See [[#Elapsed Time|Elapsed Time]].<br />
<br />
=== Ticks ===<br />
<br />
Ticks measure the number of milliseconds elapsed since OpenBOR started. Unlike Elapsed Time, Ticks are not limited to an active level and do not reset when a level begins.<br />
<br />
Ticks are useful for loading operations, menus, recorded input, diagnostics, and script timers that must remain available outside active gameplay.<br />
<br />
See [[#Ticks|Ticks]].<br />
<br />
=== System Time ===<br />
<br />
System Time provides optional access to the host device’s real-world clock, including Unix timestamps, calendar dates, local time, and Coordinated Universal Time.<br />
<br />
Native gameplay does not depend on System Time. Creators may use it through script for features such as dated save files, logging, calendar events, or other intentionally real-world behavior.<br />
<br />
See [[#System Time|System Time]].<br />
== Game Time ==<br />
Game time is a default countdown timer that appears at top center of the screen during an active level. It starts at 99 and decrements once every two real world seconds. At 0, all active players take damage equal to their current HP, and the game is over if no lives or credits remain. Time resets automatically when players clear a designated level wait and at the start of each new level. [[File:Batman savage dawn a.png|alt=Batman Savage Dawn screenshot.|center|frame|The Batman Savage Dawn fan game demonstrates OpenBOR's default game timer in action at top center of the screen.]]<br />
<br />
=== Set Time ===<br />
<syntaxhighlight lang="text">settime {int time}<br />
<br />
#default<br />
settime 99</syntaxhighlight><br />
<br />
Level header command that sets value applied to timer on level start and native resets.<br />
<br />
* Accepts any integer value from <code>0</code> to <code>99</code>. Out of bounds values are ignored. <br />
* <code>0</code> = infinite time.<br />
<br />
=== HUD Display ===<br />
For configuring how timer displays on screen, see [[Heads Up Display]].<br />
<br />
* [[Heads Up Display#Disable Time Display|Disable Time Display]]<br />
* [[Heads Up Display#Timer Font|Timer Font]]<br />
* [[Heads Up Display#Timer Location and Border|Timer Location]]<br />
* [[Heads Up Display#Timer Icon|Timer Icon]]<br />
<br />
=== Other ===<br />
<br />
==== data/sounds/timeover.wav ====<br />
If available, plays once when the game timer expires.<br />
<br />
==== anim lose ====<br />
If available, entity plays this animation in place of normal death when game timer expires. <br />
<br />
* Accessible to script as <code>openborconstant("ANI_LOSE")</code>.<br />
<br />
==== anim falllose ====<br />
If available and entity does not have a lose animation, entity plays this animation in place of normal fall death when game timer expires.<br />
<br />
* Accessible to script as <code>openborconstant("ANI_FALLLOSE")</code>.<br />
<br />
==== Attack types ====<br />
Attack types applied to players when game time expires.<br />
<br />
* <code>openborconstant("ATK_TIMEOVER")</code> - Applied to players without a lose animation.<br />
* <code>openborconstant("ATK_LOSE")</code> - Applied to players with a lose animation.<br />
<br />
=== Script API ===<br />
<br />
==== Game Time ====<br />
Current game time is read and write accessible.<br />
<br />
===== Get =====<br />
<syntaxhighlight lang="c++" line="1"><br />
int time = openborvariant("game_time");<br />
</syntaxhighlight>Get integer representing game time remaining.<br />
<br />
===== Set =====<br />
<syntaxhighlight lang="c" line="1"><br />
int new_time = 50;<br />
<br />
setopenborvariat("game_time", new_time);<br />
</syntaxhighlight>Set game time remaining.<br />
<br />
==== Timetick Event ====<br />
If available, <code>data/scripts/timetick.c</code> fires on each game time decrement. Populates the following local variables.<br />
<br />
* <code>time</code> - Current game time value.<br />
<br />
== Elapsed Time ==<br />
In terms of game mechanics, Elapsed Time is OpenBOR’s most important and frequently used time measurement because it represents the engine’s logical clock. Its implementation, however, is relatively simple.<br />
<br />
At the beginning of each level, a global elapsed-time counter is initialized to <code>0</code>. OpenBOR’s logical clock runs at 200 ticks per second (200 Hz) by default, and the counter increments by <code>1</code> for every processed logical tick.<br />
<br />
At 200 Hz, each logical tick represents 5 milliseconds, or one-half of a centisecond. Therefore:<br />
<br />
* 2 elapsed-time ticks equal 1 centisecond.<br />
* 200 elapsed-time ticks equal 1 second.<br />
<br />
OpenBOR’s logical clock operates independently of its outer update and rendering rate. Depending on the selected FPS setting and display synchronization, the outer update cycle may execute faster or slower than the logical clock. Available FPS settings include VSync, fixed limits of 60, 200, or 500 FPS, and an unrestricted option.<br />
<br />
Some operations execute once per outer update cycle. These include the global <code>update.c</code> and <code>updated.c</code> script events. Such scripts may therefore execute at a different frequency than the logical clock.<br />
<br />
Other operations, including entity simulation and entity update scripts, execute according to logical ticks.<br />
<br />
Elapsed Time is therefore reliable as a gameplay timer regardless of the selected outer frame rate. Manually incremented script timers may produce inconsistent results when incremented from an event that executes once per outer update cycle. For timing operations outside active gameplay, where Elapsed Time is unavailable, consider using [[Time#Ticks|Ticks]] instead.<br />
<br />
=== Duration Testing ===<br />
Most timed systems operate by setting an expiration value equal to the current Elapsed Time plus a predetermined duration. The engine then compares that expiration value against the elapsed-time counter. Once Elapsed Time reaches or passes the expiration value, the timed item may complete, expire, continue to another state, or perform whatever other action its system requires.<syntaxhighlight lang="c" line="1"><br />
/* Set expiration. */<br />
int expiration = elapsed_time + duration;<br />
<br />
/*<br />
* "Reach or exceed" logic downstream.<br />
*/<br />
if(elapsed_time >= expiration) {<br />
// Take action.<br />
}<br />
</syntaxhighlight>'''Note:''' In case it matters, the Elapsed Time counter is stored as a 64-bit unsigned integer. At 200 increments per second, a single level could run continuously for roughly 2.9 billion years before the counter rolls over.<br />
<br />
=== Script API ===<br />
<br />
==== Get Elapsed Time ====<br />
<syntaxhighlight lang="c" line="1"><br />
int elapsed_time = openborvariant("elapsed_time");<br />
</syntaxhighlight><br />
<br />
==== Set Elapsed Time ====<br />
Be careful about setting elapsed time during game-play, as again, virtually every active game timing property depends on it.<syntaxhighlight lang="c" line="1"><br />
int new_time = 100<br />
<br />
setopenborvariant("elapsed_time", new_time); <br />
</syntaxhighlight><br />
<br />
== Ticks ==<br />
Ticks is a read only measure of milliseconds starting from game boot. OpenBOR natively uses ticks for the player input recording feature and for timing during load screens. Ticks therefore do not generally affect active game-play, but are useful for user content, scripting, and keeping time outside of active game-play elements when Elapsed Time is not natively incremented. <br />
<br />
=== Script API ===<br />
<br />
==== Get Ticks ====<br />
<syntaxhighlight lang="c" line="1"><br />
int ticks = openborvariant("ticks");<br />
</syntaxhighlight><br />
<br />
== System Time ==<br />
System time is entirely optional and provided for creator defined script use. It is not accessed by native engine logic in any way. System time is available as a Unix timestamp in either seconds or milliseconds where supported by hardware. Conversion functions allow outputting a custom formatted string or time parts as integer values for use in logic expressions.<br />
<br />
=== Script API ===<br />
<br />
==== Get Current Unix Timestamp ====<br />
<br />
Returns the current system time as the number of seconds elapsed since <code>1970-01-01 00:00:00 UTC</code>.<br />
<br />
<syntaxhighlight lang="c" line="1"><br />
int timestamp = datetime_gettimestamp();<br />
</syntaxhighlight><br />
<br />
==== Get Current Unix Timestamp in Milliseconds ====<br />
<br />
Returns the current system time as the number of milliseconds elapsed since <code>1970-01-01 00:00:00 UTC</code>.<br />
<br />
'''Note:''' Millisecond Unix timestamps require a 64-bit integer value.<br />
<br />
<syntaxhighlight lang="c" line="1"><br />
int timestamp = datetime_gettimestampms();<br />
</syntaxhighlight><br />
<br />
==== Format Current Local Date and Time ====<br />
<br />
Formats the current system time as a string using the host system's local time standard. The format string uses standard [https://pubs.opengroup.org/onlinepubs/007904875/utilities/date.html datetime conversion codes].<br />
<br />
'''Note:''' Names such as weekdays and months may vary according to the host system's configured language and locale.<br />
<br />
<syntaxhighlight lang="c" line="1"><br />
void date_time = datetime_format("%Y-%m-%d %H:%M:%S");<br />
</syntaxhighlight><br />
<br />
The following examples demonstrate several common formats:<br />
<br />
<syntaxhighlight lang="c"><br />
/*<br />
* ISO-style date and 24-hour time:<br />
* 2026-07-12 14:35:08<br />
*/<br />
void date_time = datetime_format("%Y-%m-%d %H:%M:%S");<br />
<br />
/*<br />
* Month, day, and year:<br />
* 07/12/2026<br />
*/<br />
void date = datetime_format("%m/%d/%Y");<br />
<br />
/*<br />
* Full weekday and month names:<br />
* Sunday, July 12, 2026<br />
*/<br />
void written_date = datetime_format("%A, %B %d, %Y");<br />
<br />
/*<br />
* Abbreviated weekday and month names:<br />
* Sun, Jul 12, 2026<br />
*/<br />
void short_date = datetime_format("%a, %b %d, %Y");<br />
<br />
/*<br />
* 12-hour time with AM or PM:<br />
* 02:35:08 PM<br />
*/<br />
void time_12_hour = datetime_format("%I:%M:%S %p");<br />
<br />
/*<br />
* 24-hour time:<br />
* 14:35:08<br />
*/<br />
void time_24_hour = datetime_format("%H:%M:%S");<br />
<br />
/*<br />
* Year, month, day, hour, and minute:<br />
* 20260712_1435<br />
*<br />
* Useful for save names, logs, and generated filenames.<br />
*/<br />
void file_timestamp = datetime_format("%Y%m%d_%H%M");<br />
<br />
/*<br />
* Day of the year:<br />
* Day 193 of 2026<br />
*/<br />
void year_progress = datetime_format("Day %j of %Y");<br />
<br />
/*<br />
* Weekday name:<br />
* Sunday<br />
*/<br />
void weekday = datetime_format("%A");<br />
</syntaxhighlight><br />
<br />
==== Format a Unix Timestamp ====<br />
<br />
Formats a supplied Unix timestamp expressed in milliseconds.<br />
<br />
<syntaxhighlight lang="c" line="1"><br />
int timestamp = 1783890000000;<br />
<br />
void date_time = datetime_format("%Y-%m-%d %H:%M:%S", timestamp);<br />
</syntaxhighlight><br />
<br />
==== Format Date and Time as UTC ====<br />
All format and date part functions can accept the following constants:<br />
<br />
* <code>opeborcosntat("DATETIME_STANDARD_LOCAL")</code> - Use local system time (default).<br />
* <code>opeborcosntat("DATETIME_STANDARD_UTC")</code> - Use Coordinated Universal Time.<br />
<br />
Formats a supplied Unix timestamp using Coordinated Universal Time instead of the host system's local time.<br />
<br />
<syntaxhighlight lang="c" line="1"><br />
int timestamp = datetime_gettimestampms();<br />
<br />
void date_time = datetime_format("%Y-%m-%d %H:%M:%S", timestamp, opeborcosntat("DATETIME_STANDARD_UTC")); </syntaxhighlight><br />
<br />
==== Get Current Year ====<br />
<br />
Returns the current four-digit year using the host system's local time standard.<br />
<br />
<syntaxhighlight lang="c" line="1"><br />
int year = datetime_getyear();<br />
</syntaxhighlight><br />
<br />
==== Get Current Month ====<br />
<br />
Returns the current calendar month as an integer.<br />
<br />
<syntaxhighlight lang="c" line="1"><br />
int month = datetime_getmonth();<br />
</syntaxhighlight><br />
<br />
==== Get Current Day ====<br />
<br />
Returns the current day of the month as an integer.<br />
<br />
<syntaxhighlight lang="c" line="1"><br />
int day = datetime_getday();<br />
</syntaxhighlight><br />
<br />
==== Get Current Weekday ====<br />
Return the current day of the week as an integer corresponding to one of the following constants:<syntaxhighlight lang="c" line="1"><br />
openborconstant("DATETIME_WEEKDAY_SUNDAY")<br />
openborconstant("DATETIME_WEEKDAY_MONDAY")<br />
openborconstant("DATETIME_WEEKDAY_TUESDAY")<br />
openborconstant("DATETIME_WEEKDAY_WEDNESDAY")<br />
openborconstant("DATETIME_WEEKDAY_THURSDAY")<br />
openborconstant("DATETIME_WEEKDAY_FRIDAY")<br />
openborconstant("DATETIME_WEEKDAY_SATURDAY")<br />
</syntaxhighlight><syntaxhighlight lang="c" line="1"><br />
int weekday = datetime_getweekday();<br />
<br />
/* Is it Monday? */<br />
if(weekday == openborconstant("DATETIME_WEEKDAY_MONDAY")){<br />
log("Just another Manic Monday.");<br />
}<br />
</syntaxhighlight><br />
<br />
==== Get Current Hour ====<br />
<br />
Returns the current hour using the host system's local time standard.<br />
<br />
<syntaxhighlight lang="c" line="1"><br />
int hour = datetime_gethour();<br />
</syntaxhighlight><br />
<br />
==== Get Current Minute ====<br />
<br />
Returns the current minute of the hour.<br />
<br />
<syntaxhighlight lang="c" line="1"><br />
int minute = datetime_getminute();<br />
</syntaxhighlight><br />
<br />
==== Get Current Second ====<br />
<br />
Returns the current second of the minute.<br />
<br />
<syntaxhighlight lang="c" line="1"><br />
int second = datetime_getsecond();<br />
</syntaxhighlight><br />
<br />
==== Get Date and Time Parts from a Unix Timestamp ====<br />
<br />
Each component function optionally accepts a Unix timestamp expressed in milliseconds. This allows creators to extract individual date and time values from a stored timestamp.<br />
<br />
<syntaxhighlight lang="c" line="1"><br />
int timestamp = 1783890000000;<br />
<br />
int year = datetime_getyear(timestamp);<br />
int month = datetime_getmonth(timestamp);<br />
int day = datetime_getday(timestamp);<br />
int hour = datetime_gethour(timestamp);<br />
int minute = datetime_getminute(timestamp);<br />
int second = datetime_getsecond(timestamp); </syntaxhighlight><br />
<br />
==== Get Date and Time Parts as UTC ====<br />
<br />
Pass <code>opeborcosntat("DATETIME_STANDARD_UTC")</code> as the second argument to interpret the supplied timestamp as Coordinated Universal Time.<br />
<br />
<syntaxhighlight lang="c" line="1"><br />
int timestamp = datetime_gettimestampms();<br />
<br />
int year = datetime_getyear(timestamp, opeborcosntat("DATETIME_STANDARD_UTC"));<br />
<br />
int month = datetime_getmonth(timestamp, opeborcosntat("DATETIME_STANDARD_UTC"));<br />
<br />
int day = datetime_getday(timestamp, opeborcosntat("DATETIME_STANDARD_UTC"));<br />
<br />
int hour = datetime_gethour(timestamp, opeborcosntat("DATETIME_STANDARD_UTC")); </syntaxhighlight><br />
<br />
==== Use Current Time with an Explicit Time Standard ====<br />
<br />
Pass `NULL()` for the optional timestamp argument when selecting a time standard without supplying a custom timestamp.<br />
<br />
<syntaxhighlight lang="c" line="1"><br />
int utc_hour = datetime_gethour(NULL(), opeborcosntat("DATETIME_STANDARD_UTC"));<br />
</syntaxhighlight><br />
<br />
<br />
[[Category:Script]]<br />
[[Category:Openbor]]<br />
[[Category:Game Mechanics]]</div>Dcurrenthttps://chronocrash.com/openbor/wiki/index.php?title=Animation_Overview&diff=1098Animation Overview2026-08-26T03:53:31Z<p>Dcurrent: </p>
<hr />
<div>Animations are one of OpenBOR's fundamental building blocks. Models use animations to describe how they look and behave over time. Walking, standing, attacking, falling, taking damage, and many other actions are represented by ordered animation frames.<br />
<br />
Each animation belongs to a model and occupies a recognized animation slot such as <code>idle</code>, <code>walk</code>, <code>jump</code>, <code>pain</code>, or <code>attack1</code>. OpenBOR's native logic selects many of these slots automatically. Scripts may also select an animation or frame directly.<br />
<br />
An animation frame is more than an image. It may also contain timing, offsets, collision boxes, movement, sounds, draw settings, entity spawns, and other behavior.__TOC__<br />
<br />
== Basic structure ==<br />
<br />
The <code>anim</code> command begins an animation definition. Commands following it configure the animation or prepare properties for its frames. Each <code>frame</code> command adds one frame using the properties currently in effect.<br />
<br />
<syntaxhighlight lang="text"><br />
anim idle<br />
loop 1<br />
delay 12<br />
offset 32 96<br />
<br />
frame data/chars/example/idle_01.png<br />
frame data/chars/example/idle_02.png<br />
frame data/chars/example/idle_03.png<br />
</syntaxhighlight><br />
<br />
This example creates a looping idle animation with three frames. With the default centisecond delay unit, each frame lasts 0.12 seconds.<br />
<br />
Indentation and blank lines are optional, but they make animation blocks easier to read.<br />
<br />
=== Animation identifiers ===<br />
<br />
The value following <code>anim</code> identifies the animation's purpose. Common examples include:<br />
<br />
{| class="wikitable"<br />
! Identifier<br />
! Typical purpose<br />
|-<br />
| <code>idle</code><br />
| Standing without moving.<br />
|-<br />
| <code>walk</code><br />
| Ordinary movement.<br />
|-<br />
| <code>jump</code><br />
| Initial or rising jump state.<br />
|-<br />
| <code>land</code><br />
| Landing from a jump or fall.<br />
|-<br />
| <code>pain</code><br />
| Reacting to damage.<br />
|-<br />
| <code>fall</code><br />
| Knockdown or falling reaction.<br />
|-<br />
| <code>rise</code><br />
| Recovering from a fall.<br />
|-<br />
| <code>attack1</code><br />
| A native attack animation.<br />
|-<br />
| <code>freespecial1</code><br />
| A creator-configured special move.<br />
|}<br />
<br />
Animation identifiers are behavioral slots, not arbitrary labels. Supplying an animation makes the corresponding behavior available to native engine logic and scripts. Some model types require certain animations to operate normally, while others are optional.<br />
<br />
== Frame construction ==<br />
<br />
OpenBOR reads model files from top to bottom. Frame property commands update temporary state, and <code>frame</code> commits a copy of that state to the animation.<br />
<br />
<syntaxhighlight lang="text"><br />
anim idle<br />
loop 1<br />
offset 32 96<br />
<br />
delay 10<br />
frame data/chars/example/idle_01.png<br />
<br />
delay 25<br />
frame data/chars/example/idle_02.png<br />
</syntaxhighlight><br />
<br />
The first frame receives a delay of 10. The second receives a delay of 25 because the delay changes before its <code>frame</code> command.<br />
<br />
Commands placed after a <code>frame</code> line cannot alter the frame that was already added. Most frame properties remain active for subsequent frames until another command changes or disables them. Some one-shot properties, such as a frame sound, reset after the frame is added.<br />
<br />
Define important state explicitly in each animation. In particular, specifying a delay inside every animation avoids accidentally inheriting a previously active delay while the model file is being parsed.<br />
=== Frame numbering ===<br />
Frames use zero-based indexes. The first frame line is frame 0, the second is frame 1, and so on. Commands that target a frame number use these indexes unless their own documentation states otherwise.<br />
<br />
The same image may appear more than once when different timing or behavior is needed. OpenBOR reuses its globally cached pixel data, so repeating an image does not require another pixel-data allocation.<br />
<br />
Frame <code>none</code> adds a logical frame without a visible sprite, which can be useful for invisible states or script-controlled behavior.<br />
<br />
== Offsets ==<br />
<br />
The <code>offset</code> command selects the anchor point inside a frame image.<br />
<br />
<syntaxhighlight lang="text"><br />
offset 32 96<br />
frame data/chars/example/idle_01.png<br />
</syntaxhighlight><br />
<br />
OpenBOR places the selected point at the entity's world position. For a standing character, the anchor is usually near the ground between the character's feet.<br />
<br />
Choose a consistent animation canvas size during production and align every source frame to the same anchor before export. Guides for the ground line and horizontal center make this much faster than correcting alignment one frame at a time in the model file.<br />
<br />
OpenBOR automatically trims unused image space when it loads sprites. Consistent source canvases are still useful because the trimming process preserves the intended relationship between the artwork and its anchor without retaining transparent padding in memory.<br />
<br />
Poor source alignment makes an entity appear to shake, slide, or change height when frames cycle. Per-frame offset changes remain available for deliberate repositioning or assets that cannot be realigned, but they should generally be the exception rather than the primary production workflow.<br />
<br />
== Looping ==<br />
Animations do not loop unless looping is enabled.<syntaxhighlight lang="text"><br />
loop {enable} {loop frame - optional} {end frame - optional}<br />
<br />
# Default<br />
loop 0 0 0<br />
</syntaxhighlight>loop <code>1</code> repeats the animation. loop <code>0</code> disables looping.<br />
<br />
The optional loop frame selects the zero-based frame to return to when the animation repeats. The optional end frame is an exclusive boundary - when playback reaches that frame index, it returns to the selected loop frame instead of displaying the boundary frame. <br />
<br />
For example, if end frame is <code>7</code>, frame <code>7</code> - the sixth frame, does not display - the animation instantly loops on reaching that frame. If end frame is not provided animation proceeds to the last frame and loops.<br />
<br />
Idle and walk animations commonly loop. Attacks, pain reactions, falls, and transitions commonly play once and stop on their final frame until native logic or a script selects another animation.<br />
<br />
== Delay ==<br />
<br />
Delay controls how long a frame remains active before OpenBOR advances the animation. The command is stateful and applies to each following frame until another <code>delay</code> command changes it.<br />
<br />
=== Syntax ===<br />
<br />
<syntaxhighlight lang="text"><br />
delay <value> [unit]<br />
</syntaxhighlight><br />
<br />
The unit is optional. Omitting it is equivalent to selecting <code>global</code>.<br />
<br />
<syntaxhighlight lang="text"><br />
delay 10<br />
delay 10 global<br />
</syntaxhighlight><br />
<br />
Both examples use the module's global delay unit.<br />
<br />
=== Delay units ===<br />
Optional time unit setting. <br />
{| class="wikitable"<br />
! Unit<br />
! Meaning<br />
|-<br />
| <code>global</code><br />
| Uses the unit selected by <code>global_config_delay_unit</code> in <code>data/models.txt</code>. This is the default mode.<br />
|-<br />
| <code>millisecond</code><br />
| Interprets the value as thousandths of a second.<br />
|-<br />
| <code>centisecond</code><br />
| Interprets the value as hundredths of a second. This is the default global unit and preserves traditional OpenBOR timing.<br />
|-<br />
| <code>second</code><br />
| Interprets the value as seconds.<br />
|-<br />
| <code>minute</code><br />
| Interprets the value as minutes.<br />
|-<br />
| <code>direct</code><br />
| Stores the value directly as logical clock ticks without time-unit conversion.<br />
|}<br />
<br />
OpenBOR converts the supplied value from the selected unit into logical clock ticks. See [[Animation Overview#Logical clock precision|Logical clock precision]].<br />
<br />
Examples:<br />
<br />
<syntaxhighlight lang="text"><br />
delay 250 millisecond<br />
delay 25 centisecond<br />
delay 2 second<br />
delay 1 minute<br />
delay 50 direct<br />
</syntaxhighlight><br />
<br />
Singular unit names are required.<br />
<br />
=== Global delay unit ===<br />
<br />
Use <code>global_config_delay_unit</code> in <code>data/models.txt</code> to select the unit used by unqualified and explicitly global delays.<br />
<br />
<syntaxhighlight lang="text"><br />
global_config_delay_unit centisecond<br />
</syntaxhighlight><br />
<br />
The setting accepts <code>millisecond</code>, <code>centisecond</code>, <code>second</code>, <code>minute</code>, or <code>direct</code>. It does not accept <code>global</code>, because the global setting must resolve to a concrete unit.<br />
<br />
If the command is omitted, the global unit is <code>centisecond</code>. Changing the setting reinterprets every model delay that uses <code>global</code>, so modules should choose a unit deliberately. Explicit frame units remain independent of the global selection.<br />
<br />
The setting is read while models are loaded. OpenBOR converts each delay to logical ticks and stores the converted result with the animation frame. It is not a runtime timing switch for animations that are already loaded.<br />
<br />
=== Logical clock precision ===<br />
<br />
OpenBOR animation timing ultimately uses whole logical clock ticks. Unit conversion follows these relationships:<br />
<br />
<syntaxhighlight lang="text"><br />
millisecond = value * game speed / 1000<br />
centisecond = value * game speed / 100<br />
second = value * game speed<br />
minute = value * game speed * 60<br />
direct = value<br />
</syntaxhighlight><br />
<br />
Fractional results truncate. No time unit can represent a duration smaller than the module's logical clock precision, and any fractional remainder is discarded.<br />
<br />
For example, at the default game speed of 200 ticks per second, each logical tick represents 5 milliseconds. Any value from 15 through 19 milliseconds therefore converts to three ticks, representing 15 milliseconds, while 20 milliseconds converts exactly to four ticks.<br />
<br />
The <code>direct</code> unit is useful when exact integration with the logical clock matters. Its real-time duration changes with game speed because its value is already a tick count. By pairing a game speed evenly divisible by a target frame rate with direct delays, creators can time animations in exact frame intervals. For example, a game speed of 240 provides four logical ticks for each frame at 60 Hz. This supports frame-based timing conventions commonly used by the fighting game community and fixed-refresh console games.<br />
<br />
=== Infinite delay ===<br />
<br />
Use <code>infinite</code> or the infinity symbol <code>∞</code> when a frame should not advance through ordinary clock timing.<br />
<br />
<syntaxhighlight lang="text"><br />
anim idle<br />
delay infinite<br />
offset 32 96<br />
frame data/chars/example/idle_01.png<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="text"><br />
delay ∞<br />
</syntaxhighlight><br />
<br />
An infinite frame remains active until something outside normal timing changes its animation or frame. Scripts may use the <code>DELAY_INFINITE</code> constant for the same engine value.<br />
<br />
The word <code>infinite</code> is the most portable model-file spelling. The <code>∞</code> form is UTF-8 text and may be damaged by old Windows editors, archive tools, or other utilities that do not preserve Unicode correctly.<br />
<br />
Any negative numeric delay also becomes infinite for backward compatibility. New content should use <code>infinite</code> or <code>∞</code> so its intent is explicit.<br />
<br />
=== Finite range and behavior flags ===<br />
<br />
Finite delay values use the lower 32 bits of an unsigned 64-bit value. The largest finite value is 4,294,967,295. Conversions that would exceed this limit clamp to the largest finite delay instead of overflowing or accidentally becoming infinite.<br />
<br />
The upper 32 bits are reserved for delay behavior flags. Bit 63 is the infinite flag. Enhanced-delay calculations modify only the finite lower value and preserve behavior flags, so an infinite frame cannot accidentally become finite.<br />
<br />
=== Enhanced delay ===<br />
<br />
[[Enhanced Delay|Enhanced delay]], or <code>edelay</code>, adjusts frame delays through a model's multiplier, modifier, range, and cap settings. These calculations occur after time-unit conversion, so enhanced-delay ranges, modifiers, and caps operate on logical tick values rather than the source unit written in the animation.<br />
<br />
Enhanced-delay arithmetic is bounded to the finite delay range. It cannot overflow into behavior flags or create an infinite delay through calculation.<br />
<br />
== Frame properties ==<br />
<br />
Timing and graphics form only the minimum animation. Frame property commands can add behavior such as:<br />
<br />
{| class="wikitable"<br />
! Property<br />
! Purpose<br />
|-<br />
| <code>bbox</code><br />
| Defines the frame's body collision area. Use <code>bbox none</code> to disable it.<br />
|-<br />
| Attack collision commands<br />
| Define areas that damage or otherwise affect targets.<br />
|-<br />
| <code>move</code>, <code>movea</code>, and <code>movez</code><br />
| Apply frame movement along the model's axes.<br />
|-<br />
| <code>sound</code><br />
| Plays a sound when the frame begins.<br />
|-<br />
| Draw commands<br />
| Change scaling, rotation, transparency, remapping, clipping, and other rendering behavior.<br />
|-<br />
| Spawn commands<br />
| Create or summon child entities on selected frames.<br />
|-<br />
| Animation scripts<br />
| Execute creator-defined logic as frames change.<br />
|}<br />
<br />
Property commands normally appear before the <code>frame</code> they configure:<br />
<br />
<syntaxhighlight lang="text"><br />
anim idle<br />
loop 1<br />
delay 10<br />
offset 32 96<br />
<br />
bbox 12 20 40 76 10<br />
frame data/chars/example/idle_01.png<br />
<br />
bbox none<br />
frame data/chars/example/idle_02.png<br />
</syntaxhighlight><br />
<br />
The first frame has a body collision box. The second does not because <code>bbox none</code> changes the pending frame state before the second <code>frame</code> command.<br />
<br />
== Practical example ==<br />
<br />
<syntaxhighlight lang="text"><br />
anim idle<br />
loop 1<br />
offset 32 96<br />
bbox 12 20 40 76 10<br />
<br />
delay 100 millisecond<br />
frame data/chars/example/idle_01.png<br />
<br />
delay 150 millisecond<br />
frame data/chars/example/idle_02.png<br />
<br />
delay 100 millisecond<br />
frame data/chars/example/idle_03.png<br />
<br />
<br />
anim attack1<br />
loop 0<br />
offset 40 96<br />
delay 80 millisecond<br />
<br />
frame data/chars/example/attack_01.png<br />
<br />
move 4<br />
frame data/chars/example/attack_02.png<br />
<br />
move 0<br />
delay 160 millisecond<br />
frame data/chars/example/attack_03.png<br />
</syntaxhighlight><br />
<br />
The idle animation loops with intentionally uneven timing. The attack plays once, moves the entity during its second frame, stops that movement before the third frame, and holds the final attack pose longer.<br />
<br />
== Common problems ==<br />
<br />
{| class="wikitable"<br />
! Symptom<br />
! Likely cause<br />
|-<br />
| Frames appear to shake or slide.<br />
| Offsets do not align the same visual anchor across images.<br />
|-<br />
| A property affects the wrong frame.<br />
| The property command appears after the intended <code>frame</code> line, or persistent frame state was not changed before the next frame.<br />
|-<br />
| An animation plays much too quickly or slowly.<br />
| The delay unit or <code>global_config_delay_unit</code> does not match the values used by the model.<br />
|-<br />
| Very small delays appear identical.<br />
| Both values truncate to the same logical tick count at the selected game speed.<br />
|-<br />
| An animation never advances.<br />
| Its delay is infinite, its animation has stopped, or external logic is holding or replacing its state.<br />
|-<br />
| A non-looping animation does not repeat.<br />
| This is expected unless native logic or a script selects the animation again.<br />
|}<br />
<br />
When debugging an animation, begin with a minimal definition containing <code>anim</code>, <code>delay</code>, <code>offset</code>, and <code>frame</code>. Confirm its images, alignment, and timing before adding collision, movement, effects, or scripts.<br />
[[Category:Openbor]]<br />
[[Category:Animation]]<br />
[[Category:Model]]</div>Dcurrenthttps://chronocrash.com/openbor/wiki/index.php?title=Main_Page&diff=1097Main Page2026-08-26T03:49:26Z<p>Dcurrent: /* Why OpenBOR? */</p>
<hr />
<div>== Introduction ==<br />
<br />
=== What is OpenBOR? ===<br />
OpenBOR is a royalty-free, open-source engine for sprite-based games. It combines a complete native game framework - including controls, movement, combat, artificial intelligence, levels, audio, menus, saving, and local multiplayer - with an integrated C-like scripting language that can extend or replace nearly every system.<br />
<br />
OpenBOR specializes in side-scrolling action games such as Double Dragon and Streets of Rage, but its three-dimensional game world, configurable simulation, declarative object system, and scriptable graphics pipeline also support platformers, shooters, role-playing games, puzzle games, and other genres.<br />
<br />
Beginners can build complete games primarily from assets and configuration. Advanced creators can manipulate engine objects, replace native behavior, construct rendering pipelines, and even compile new script programs while a module is running.<br />
<br />
=== Why OpenBOR? ===<br />
What sets OpenBOR apart is how we define its scope. Some engines concentrate on a particular result: role-playing games, one-on-one fighters, shoot-’em-ups, real-time strategy, or puzzles. Others attempt to support every technical medium, leaving developers to build most game-specific functionality themselves. Both are valid approaches. We take a third path by specializing in a technical medium without prescribing the result.<br />
<br />
OpenBOR deliberately limits itself to the simulation and presentation of flat, two-dimensional visual assets in an effectively limitless three-dimensional world. No polygons. No meshes. No skeletal rigs. Just raster graphics moving through three axes. Within that foundation, virtually any sprite-powered concept is possible.<br />
<br />
That focus means we spend our development resources on performance and depth: butter-smooth motion, asset handling, controls, gravity, collision, combat, blocking, grabbing, throwing, artificial intelligence, cameras, level trees, audio, menus, HUDs, saving, and local multiplayer are integrated and ready to use. Everything works together out of the box, with no need to build these foundations or assemble them from plugins.<br />
<br />
Then we layer beat ’em up-oriented behavior over those systems as the default starting point. Supply the necessary assets and configuration, and characters can already move, fight, react, navigate depth, cooperate, and progress through levels. You can have a functional game running within hours, but those defaults don't dictate the finished product.<br />
<br />
Configuration and script expose the same engine objects, properties, and low-level primitives beneath that native behavior. Creators can inspect runtime state, customize selected operations, replace complete subsystems, or combine the primitives into something we never anticipated. The same technical model can support platformers, shooters, role-playing games, puzzles, and other designs far removed from the default.<br />
<br />
The result is a deliberately bounded medium, a complete starting point, and an ending defined only by your imagination.<br />
* '''Complete native gameplay''' - Controls, movement, gravity, level trees, platforms, combat, blocking, grabbing, throwing, artificial intelligence, cameras, audio, menus, HUDs, and saving work without custom code.<br />
* '''[[Script Overview|Engine-wide scripting]]''' - Object APIs and [[:Category:Script Events|more than 70 event hooks]] expose input, animation, movement, collision, damage, spawning, audio, drawing, and other runtime systems for inspection, modification, or replacement.<br />
* '''[[Time|High-resolution simulation]]''' - The configurable logical clock runs at 200 Hz by default and remains independent of display updates.<br />
* '''[[Geometry Overview|Three-dimensional sprite worlds]]''' - Floating-point X, Y, and Z geometry provides subpixel movement, terrain, altitude, and depth sorting. Set an area's Z axis to bounded values and the engine natively assumes 2D world behaviors.<br />
* '''[[Collision|Declarative combat collision]]''' - Indexed three-dimensional attack and body boxes carry damage, reaction, motion, status, and presentation behavior.<br />
* '''[[Factions|Composable relationships]]''' - Four independent 52-bit faction masks provide hardware-speed membership, hostility, direct-damage, and indirect-damage rules.<br />
* '''[[Subscreens|Recursive graphics composition]]''' - Script-created subscreens support nested rendering, layer capture, transformations, masks, split screens, and feedback effects.<br />
* '''[[Runtime Script Compilation|Runtime metaprogramming]]''' - Modules can load and combine source files, compile them into independently owned programs, retain persistent state, execute them repeatedly, and replace them during play.<br />
* '''Optimized performance''' - Native systems, high-frequency simulation, and script integration are engineered to maintain steady frame rates and seamless motion with dozens or hundreds of active objects.<br />
<br />
== Getting Started ==<br />
<br />
'''[https://www.chronocrash.com/forum/resources/openbor.1/ Download OpenBOR]''' | '''[https://www.chronocrash.com/forum/resources/categories/samples-and-tutorials.5/?prefix_id=3 Start Building]''' | '''[[:Category:Openbor|Browse the Reference]]''' | '''[https://chronocrash.com Visit the Community]''' | '''[https://github.com/DCurrent/openbor View the Source]'''<br />
<br />
This wiki is the comprehensive technical reference for OpenBOR, but please note it is not intended as a walk-through. For more in-depth instruction, consult the tutorials and guides available through the [https://chronocrash.com/forum ChronoCrash community].<br />
<br />
=== Guides and Resources ===<br />
<br />
* [[OpenBOR Overview]] – General overview of OpenBOR functionality and runtime layout.<br />
* [[:Category:Openbor|OpenBOR Hub]] – Main jumping off point for categories and individual wiki articles.<br />
* [[:Category:OpenBOR Index|OpenBOR Index]] – Simple index of OpenBOR commands, settings, and functions.<br />
* [[Legacy Manual]] – Archival monolithic manual.<br />
* [https://chronocrash.com/ ChronoCrash] – OpenBOR’s home community, including its help forum, downloadable games, and in-depth tutorials.<br />
* [https://github.com/DCurrent/openbor OpenBOR Repository] – Public-facing OpenBOR code base.<br />
<br />
== Development Environment ==<br />
<br />
=== Essential Tools ===<br />
<br />
The following tools are needed to begin building games with OpenBOR. You will need a [https://chronocrash.com/forum ChronoCrash community] account to download some resources.<br />
<br />
* [https://www.chronocrash.com/forum/resources/categories/engine.3/ OpenBOR engine executable] – The latest stable engine release.<br />
* '''[https://www.chronocrash.com/forum/resources/neo-edit-pack.2/ Edit Pack]''' – Tools for packing and unpacking OpenBOR game modules.<br />
* '''Development environment''' – OpenBOR uses a combination of text files and optional script files to configure game functionality. Any text editor may be used. [https://code.visualstudio.com/ Visual Studio Code] is recommended, together with [https://github.com Git] or another version-control system for managing project files.<br />
* '''Graphics software''' – Any graphics-editing application capable of exporting <code>.png</code> images. [https://www.adobe.com Adobe Photoshop] or [https://www.gimp.org/ GIMP] are recommended.<br />
* '''Audio software''' – An audio-editing application capable of exporting <code>.wav</code> files for sound effects and, optionally, <code>.ogg</code> files for music. [https://www.adobe.com/products/audition.html Adobe Audition] or [https://www.audacityteam.org/ Audacity] are recommended.<br />
<br />
=== Optional Tools ===<br />
<br />
These tools are optional but highly recommended.<br />
<br />
* '''[https://www.chronocrash.com/forum/resources/chronocrash-modders-tools.139/ ChronoCrash Modders Tools (CMT)]''' – Visual editing application for building OpenBOR games.<br />
* '''[https://www.chronocrash.com/forum/resources/palapply.15/ PalApply]''' – Applies a palette to one or more images and exports optimized <code>.png</code> files ready for use with OpenBOR.<br />
<br />
== What Open Source Means ==<br />
Because the term has caused confusion and disputes in the past, it is important to clarify what open source means in the context of OpenBOR.<br />
<br />
OpenBOR’s existing codebase is available under a permissive [https://github.com/DCurrent/openbor/blob/master/LICENSE BSD-derived license]. '''Creators may use the engine to make, license, and sell games and other content they rightfully own.''' The OpenBOR license does not claim or control that content.<br />
<br />
Open source does not mean a free-for-all. It provides no implied permission to modify or redistribute another creator’s work without consent. The license also permits binary distribution without requiring source disclosure - it does not compel the team to release existing or future source code, and by extension it does not entitle anyone to the source code of closed-source extensions or obligate the development team to release it. The public repository is provided and maintained as a voluntary act of good faith, not as an obligation imposed by the license.<br />
<br />
The OpenBOR development team may produce proprietary features, such as encrypted pack handling, and license them separately at its discretion.</div>Dcurrenthttps://chronocrash.com/openbor/wiki/index.php?title=Main_Page&diff=1096Main Page2026-08-26T03:45:04Z<p>Dcurrent: /* Why OpenBOR? */</p>
<hr />
<div>== Introduction ==<br />
<br />
=== What is OpenBOR? ===<br />
OpenBOR is a royalty-free, open-source engine for sprite-based games. It combines a complete native game framework - including controls, movement, combat, artificial intelligence, levels, audio, menus, saving, and local multiplayer - with an integrated C-like scripting language that can extend or replace nearly every system.<br />
<br />
OpenBOR specializes in side-scrolling action games such as Double Dragon and Streets of Rage, but its three-dimensional game world, configurable simulation, declarative object system, and scriptable graphics pipeline also support platformers, shooters, role-playing games, puzzle games, and other genres.<br />
<br />
Beginners can build complete games primarily from assets and configuration. Advanced creators can manipulate engine objects, replace native behavior, construct rendering pipelines, and even compile new script programs while a module is running.<br />
<br />
=== Why OpenBOR? ===<br />
What sets OpenBOR apart is how we define its scope. Some engines concentrate on a particular result: role-playing games, one-on-one fighters, shoot-’em-ups, real-time strategy, or puzzles. Others attempt to support every technical medium, leaving developers to build most game-specific functionality themselves. Both are valid approaches. We take a third path by specializing in a technical medium without prescribing the result.<br />
<br />
OpenBOR deliberately limits itself to the simulation and presentation of flat, two-dimensional visual assets in an effectively limitless three-dimensional world. No polygons. No meshes. No skeletal rigs. Just raster graphics moving through three axes. Within that foundation, virtually any sprite-powered concept is possible.<br />
<br />
That focus means we spend our development resources on performance and depth: butter-smooth motion, asset handling, controls, gravity, collision, combat, blocking, grabbing, throwing, artificial intelligence, cameras, level trees, audio, menus, HUDs, saving, and local multiplayer are integrated and ready to use. Everything works together out of the box, with no need to build these foundations or assemble them from plugins.<br />
<br />
Then we layer beat ’em up-oriented behavior over those systems as the default starting point. Supply the necessary assets and configuration, and characters can already move, fight, react, navigate depth, cooperate, and progress through levels. You can have a functional game running within hours, but those defaults don't dictate the finished product.<br />
<br />
Configuration and script expose the same engine objects, properties, and low-level primitives beneath that native behavior. Creators can inspect runtime state, customize selected operations, replace complete subsystems, or combine the primitives into something we never anticipated. The same technical model can support platformers, shooters, role-playing games, puzzles, and other designs far removed from the default.<br />
<br />
The result is a deliberately bounded medium, a complete starting point, and an ending defined only by your imagination.<br />
* '''Complete native gameplay''' - Controls, movement, gravity, level trees, platforms, combat, blocking, grabbing, throwing, artificial intelligence, cameras, audio, menus, HUDs, and saving work without custom code.<br />
* '''[[Script Overview|Engine-wide scripting]]''' - Object APIs and [[:Category:Script Events|more than 70 event hooks]] expose input, animation, movement, collision, damage, spawning, audio, drawing, and other runtime systems for inspection, modification, or replacement.<br />
* '''[[Time|High-resolution simulation]]''' - The configurable logical clock runs at 200 Hz by default and remains independent of display updates.<br />
* '''[[Geometry Overview|Three-dimensional sprite worlds]]''' - Floating-point X, Y, and Z geometry provides subpixel movement, terrain, altitude, and depth sorting. Set an area's Z axis to a bounded value and the engine natively assumes 2D world behaviors.<br />
* '''[[Collision|Declarative combat collision]]''' - Indexed three-dimensional attack and body boxes carry damage, reaction, motion, status, and presentation behavior.<br />
* '''[[Factions|Composable relationships]]''' - Four independent 52-bit faction masks provide hardware-speed membership, hostility, direct-damage, and indirect-damage rules.<br />
* '''[[Subscreens|Recursive graphics composition]]''' - Script-created subscreens support nested rendering, layer capture, transformations, masks, split screens, and feedback effects.<br />
* '''[[Runtime Script Compilation|Runtime metaprogramming]]''' - Modules can load and combine source files, compile them into independently owned programs, retain persistent state, execute them repeatedly, and replace them during play.<br />
* '''Optimized performance''' - Native systems, high-frequency simulation, and script integration are engineered to maintain steady frame rates and seamless motion with dozens or hundreds of active objects.<br />
<br />
== Getting Started ==<br />
<br />
'''[https://www.chronocrash.com/forum/resources/openbor.1/ Download OpenBOR]''' | '''[https://www.chronocrash.com/forum/resources/categories/samples-and-tutorials.5/?prefix_id=3 Start Building]''' | '''[[:Category:Openbor|Browse the Reference]]''' | '''[https://chronocrash.com Visit the Community]''' | '''[https://github.com/DCurrent/openbor View the Source]'''<br />
<br />
This wiki is the comprehensive technical reference for OpenBOR, but please note it is not intended as a walk-through. For more in-depth instruction, consult the tutorials and guides available through the [https://chronocrash.com/forum ChronoCrash community].<br />
<br />
=== Guides and Resources ===<br />
<br />
* [[OpenBOR Overview]] – General overview of OpenBOR functionality and runtime layout.<br />
* [[:Category:Openbor|OpenBOR Hub]] – Main jumping off point for categories and individual wiki articles.<br />
* [[:Category:OpenBOR Index|OpenBOR Index]] – Simple index of OpenBOR commands, settings, and functions.<br />
* [[Legacy Manual]] – Archival monolithic manual.<br />
* [https://chronocrash.com/ ChronoCrash] – OpenBOR’s home community, including its help forum, downloadable games, and in-depth tutorials.<br />
* [https://github.com/DCurrent/openbor OpenBOR Repository] – Public-facing OpenBOR code base.<br />
<br />
== Development Environment ==<br />
<br />
=== Essential Tools ===<br />
<br />
The following tools are needed to begin building games with OpenBOR. You will need a [https://chronocrash.com/forum ChronoCrash community] account to download some resources.<br />
<br />
* [https://www.chronocrash.com/forum/resources/categories/engine.3/ OpenBOR engine executable] – The latest stable engine release.<br />
* '''[https://www.chronocrash.com/forum/resources/neo-edit-pack.2/ Edit Pack]''' – Tools for packing and unpacking OpenBOR game modules.<br />
* '''Development environment''' – OpenBOR uses a combination of text files and optional script files to configure game functionality. Any text editor may be used. [https://code.visualstudio.com/ Visual Studio Code] is recommended, together with [https://github.com Git] or another version-control system for managing project files.<br />
* '''Graphics software''' – Any graphics-editing application capable of exporting <code>.png</code> images. [https://www.adobe.com Adobe Photoshop] or [https://www.gimp.org/ GIMP] are recommended.<br />
* '''Audio software''' – An audio-editing application capable of exporting <code>.wav</code> files for sound effects and, optionally, <code>.ogg</code> files for music. [https://www.adobe.com/products/audition.html Adobe Audition] or [https://www.audacityteam.org/ Audacity] are recommended.<br />
<br />
=== Optional Tools ===<br />
<br />
These tools are optional but highly recommended.<br />
<br />
* '''[https://www.chronocrash.com/forum/resources/chronocrash-modders-tools.139/ ChronoCrash Modders Tools (CMT)]''' – Visual editing application for building OpenBOR games.<br />
* '''[https://www.chronocrash.com/forum/resources/palapply.15/ PalApply]''' – Applies a palette to one or more images and exports optimized <code>.png</code> files ready for use with OpenBOR.<br />
<br />
== What Open Source Means ==<br />
Because the term has caused confusion and disputes in the past, it is important to clarify what open source means in the context of OpenBOR.<br />
<br />
OpenBOR’s existing codebase is available under a permissive [https://github.com/DCurrent/openbor/blob/master/LICENSE BSD-derived license]. '''Creators may use the engine to make, license, and sell games and other content they rightfully own.''' The OpenBOR license does not claim or control that content.<br />
<br />
Open source does not mean a free-for-all. It provides no implied permission to modify or redistribute another creator’s work without consent. The license also permits binary distribution without requiring source disclosure - it does not compel the team to release existing or future source code, and by extension it does not entitle anyone to the source code of closed-source extensions or obligate the development team to release it. The public repository is provided and maintained as a voluntary act of good faith, not as an obligation imposed by the license.<br />
<br />
The OpenBOR development team may produce proprietary features, such as encrypted pack handling, and license them separately at its discretion.</div>Dcurrenthttps://chronocrash.com/openbor/wiki/index.php?title=Main_Page&diff=1095Main Page2026-08-25T17:39:31Z<p>Dcurrent: /* Why OpenBOR? */</p>
<hr />
<div>== Introduction ==<br />
<br />
=== What is OpenBOR? ===<br />
OpenBOR is a royalty-free, open-source engine for sprite-based games. It combines a complete native game framework - including controls, movement, combat, artificial intelligence, levels, audio, menus, saving, and local multiplayer - with an integrated C-like scripting language that can extend or replace nearly every system.<br />
<br />
OpenBOR specializes in side-scrolling action games such as Double Dragon and Streets of Rage, but its three-dimensional game world, configurable simulation, declarative object system, and scriptable graphics pipeline also support platformers, shooters, role-playing games, puzzle games, and other genres.<br />
<br />
Beginners can build complete games primarily from assets and configuration. Advanced creators can manipulate engine objects, replace native behavior, construct rendering pipelines, and even compile new script programs while a module is running.<br />
<br />
=== Why OpenBOR? ===<br />
What sets OpenBOR apart is how we define its scope. Some engines concentrate on a particular result: role-playing games, one-on-one fighters, shoot-’em-ups, real-time strategy, or puzzles. Others attempt to support every technical medium, leaving developers to build most game-specific functionality themselves. Both are valid approaches. We take a third path by specializing in a technical medium without prescribing the result.<br />
<br />
OpenBOR deliberately limits itself to the simulation and presentation of flat, two-dimensional visual assets in an effectively limitless three-dimensional world. No polygons. No meshes. No skeletal rigs. Just raster graphics moving through three axes. Within that foundation, virtually any sprite-powered concept is possible.<br />
<br />
That focus means we spend our development resources on quality and depth: butter-smooth motion, asset handling, controls, gravity, collision, combat, blocking, grabbing, throwing, artificial intelligence, cameras, level trees, audio, menus, HUDs, saving, and local multiplayer are integrated and ready to use. Everything works together out of the box, with no need to build these foundations or assemble them from third-party plugins.<br />
<br />
Then we layer beat ’em up-oriented behavior over those systems as the default starting point. Supply the necessary assets and configuration, and characters can already move, fight, react, navigate depth, cooperate, and progress through levels. You can have a functional game running within hours, but those defaults don't dictate the finished product.<br />
<br />
Configuration and script expose the same engine objects, properties, and low-level primitives beneath that native behavior. Creators can inspect runtime state, customize selected operations, replace complete subsystems, or combine the primitives into something we never anticipated. The same technical model can support platformers, shooters, role-playing games, puzzles, and other designs far removed from the default.<br />
<br />
The result is a deliberately bounded medium, a complete starting point, and an ending defined only by your imagination.<br />
* '''Complete native gameplay''' - Controls, movement, gravity, level trees, platforms, combat, blocking, grabbing, throwing, artificial intelligence, cameras, audio, menus, HUDs, and saving work without custom code.<br />
* '''[[Script Overview|Engine-wide scripting]]''' - Object APIs and [[:Category:Script Events|more than 70 event hooks]] expose input, animation, movement, collision, damage, spawning, audio, drawing, and other runtime systems for inspection, modification, or replacement.<br />
* '''[[Time|High-resolution simulation]]''' - The configurable logical clock runs at 200 Hz by default and remains independent of display updates.<br />
* '''[[Geometry Overview|Three-dimensional sprite worlds]]''' - Floating-point X, Y, and Z geometry provides subpixel movement, terrain, altitude, and depth sorting. Set an area's Z axis to a bounded value and the engine natively assumes 2D world behaviors.<br />
* '''[[Collision|Declarative combat collision]]''' - Indexed three-dimensional attack and body boxes carry damage, reaction, motion, status, and presentation behavior.<br />
* '''[[Factions|Composable relationships]]''' - Four independent 52-bit faction masks provide hardware-speed membership, hostility, direct-damage, and indirect-damage rules.<br />
* '''[[Subscreens|Recursive graphics composition]]''' - Script-created subscreens support nested rendering, layer capture, transformations, masks, split screens, and feedback effects.<br />
* '''[[Runtime Script Compilation|Runtime metaprogramming]]''' - Modules can load and combine source files, compile them into independently owned programs, retain persistent state, execute them repeatedly, and replace them during play.<br />
* '''Optimized performance''' - Native systems, high-frequency simulation, and script integration are engineered to maintain steady frame rates and seamless motion with dozens or hundreds of active objects.<br />
<br />
== Getting Started ==<br />
<br />
'''[https://www.chronocrash.com/forum/resources/openbor.1/ Download OpenBOR]''' | '''[https://www.chronocrash.com/forum/resources/categories/samples-and-tutorials.5/?prefix_id=3 Start Building]''' | '''[[:Category:Openbor|Browse the Reference]]''' | '''[https://chronocrash.com Visit the Community]''' | '''[https://github.com/DCurrent/openbor View the Source]'''<br />
<br />
This wiki is the comprehensive technical reference for OpenBOR, but please note it is not intended as a walk-through. For more in-depth instruction, consult the tutorials and guides available through the [https://chronocrash.com/forum ChronoCrash community].<br />
<br />
=== Guides and Resources ===<br />
<br />
* [[OpenBOR Overview]] – General overview of OpenBOR functionality and runtime layout.<br />
* [[:Category:Openbor|OpenBOR Hub]] – Main jumping off point for categories and individual wiki articles.<br />
* [[:Category:OpenBOR Index|OpenBOR Index]] – Simple index of OpenBOR commands, settings, and functions.<br />
* [[Legacy Manual]] – Archival monolithic manual.<br />
* [https://chronocrash.com/ ChronoCrash] – OpenBOR’s home community, including its help forum, downloadable games, and in-depth tutorials.<br />
* [https://github.com/DCurrent/openbor OpenBOR Repository] – Public-facing OpenBOR code base.<br />
<br />
== Development Environment ==<br />
<br />
=== Essential Tools ===<br />
<br />
The following tools are needed to begin building games with OpenBOR. You will need a [https://chronocrash.com/forum ChronoCrash community] account to download some resources.<br />
<br />
* [https://www.chronocrash.com/forum/resources/categories/engine.3/ OpenBOR engine executable] – The latest stable engine release.<br />
* '''[https://www.chronocrash.com/forum/resources/neo-edit-pack.2/ Edit Pack]''' – Tools for packing and unpacking OpenBOR game modules.<br />
* '''Development environment''' – OpenBOR uses a combination of text files and optional script files to configure game functionality. Any text editor may be used. [https://code.visualstudio.com/ Visual Studio Code] is recommended, together with [https://github.com Git] or another version-control system for managing project files.<br />
* '''Graphics software''' – Any graphics-editing application capable of exporting <code>.png</code> images. [https://www.adobe.com Adobe Photoshop] or [https://www.gimp.org/ GIMP] are recommended.<br />
* '''Audio software''' – An audio-editing application capable of exporting <code>.wav</code> files for sound effects and, optionally, <code>.ogg</code> files for music. [https://www.adobe.com/products/audition.html Adobe Audition] or [https://www.audacityteam.org/ Audacity] are recommended.<br />
<br />
=== Optional Tools ===<br />
<br />
These tools are optional but highly recommended.<br />
<br />
* '''[https://www.chronocrash.com/forum/resources/chronocrash-modders-tools.139/ ChronoCrash Modders Tools (CMT)]''' – Visual editing application for building OpenBOR games.<br />
* '''[https://www.chronocrash.com/forum/resources/palapply.15/ PalApply]''' – Applies a palette to one or more images and exports optimized <code>.png</code> files ready for use with OpenBOR.<br />
<br />
== What Open Source Means ==<br />
Because the term has caused confusion and disputes in the past, it is important to clarify what open source means in the context of OpenBOR.<br />
<br />
OpenBOR’s existing codebase is available under a permissive [https://github.com/DCurrent/openbor/blob/master/LICENSE BSD-derived license]. '''Creators may use the engine to make, license, and sell games and other content they rightfully own.''' The OpenBOR license does not claim or control that content.<br />
<br />
Open source does not mean a free-for-all. It provides no implied permission to modify or redistribute another creator’s work without consent. The license also permits binary distribution without requiring source disclosure - it does not compel the team to release existing or future source code, and by extension it does not entitle anyone to the source code of closed-source extensions or obligate the development team to release it. The public repository is provided and maintained as a voluntary act of good faith, not as an obligation imposed by the license.<br />
<br />
The OpenBOR development team may produce proprietary features, such as encrypted pack handling, and license them separately at its discretion.</div>Dcurrenthttps://chronocrash.com/openbor/wiki/index.php?title=Main_Page&diff=1094Main Page2026-08-25T17:38:05Z<p>Dcurrent: /* Why OpenBOR? */</p>
<hr />
<div>== Introduction ==<br />
<br />
=== What is OpenBOR? ===<br />
OpenBOR is a royalty-free, open-source engine for sprite-based games. It combines a complete native game framework - including controls, movement, combat, artificial intelligence, levels, audio, menus, saving, and local multiplayer - with an integrated C-like scripting language that can extend or replace nearly every system.<br />
<br />
OpenBOR specializes in side-scrolling action games such as Double Dragon and Streets of Rage, but its three-dimensional game world, configurable simulation, declarative object system, and scriptable graphics pipeline also support platformers, shooters, role-playing games, puzzle games, and other genres.<br />
<br />
Beginners can build complete games primarily from assets and configuration. Advanced creators can manipulate engine objects, replace native behavior, construct rendering pipelines, and even compile new script programs while a module is running.<br />
<br />
=== Why OpenBOR? ===<br />
What sets OpenBOR apart is how we define its scope. Some engines concentrate on a particular result: role-playing games, one-on-one fighters, shoot-’em-ups, real-time strategy, or puzzles. Others attempt to support every technical medium, leaving developers to build most game-specific functionality themselves. Both are valid approaches. We take a third path by specializing in a technical medium without prescribing the result.<br />
<br />
OpenBOR deliberately limits itself to the simulation and presentation of flat, two-dimensional visual assets in an effectively limitless three-dimensional world. No polygons. No meshes. No skeletal rigs. Just raster graphics moving through three axes. Within that foundation, virtually any sprite-powered concept is possible.<br />
<br />
That focus means we spend our development resources on quality and depth: butter-smooth motion, asset handling, controls, gravity, collision, combat, blocking, grabbing, throwing, artificial intelligence, cameras, level trees, audio, menus, HUDs, saving, and local multiplayer are integrated and ready to use. Everything works together out of the box, with no need to build these foundations or assemble them from third-party plugins.<br />
<br />
Then we layer beat ’em up-oriented behavior over those systems as the default starting point. Supply the necessary assets and configuration, and characters can already move, fight, react, navigate depth, cooperate, and progress through levels. You can have a functional game running within hours, but those defaults don't dictate the finished product.<br />
<br />
Configuration and script expose the same engine objects, properties, and low-level primitives beneath that native behavior. Creators can inspect runtime state, customize selected operations, replace complete subsystems, or combine the primitives into something we never anticipated. The same technical model can support platformers, shooters, role-playing games, puzzles, and other designs far removed from the default.<br />
<br />
The result is a deliberately bounded medium, a complete starting point, and an ending defined only by your imagination.<br />
* '''Complete native gameplay''' - Controls, movement, gravity, level trees, platforms, combat, blocking, grabbing, throwing, artificial intelligence, cameras, audio, menus, HUDs, and saving work without custom code.<br />
* '''[[Script Overview|Engine-wide scripting]]''' - Object APIs and [[:Category:Script Events|more than 70 event hooks]] expose input, animation, movement, collision, damage, spawning, audio, drawing, and other runtime systems for inspection, modification, or replacement.<br />
* '''[[Time|High-resolution simulation]]''' - The configurable logical clock runs at 200 Hz by default and remains independent of display updates.<br />
* '''[[Geometry Overview|Three-dimensional sprite worlds]]''' - Floating-point X, Y, and Z geometry provides subpixel movement, terrain, altitude, and depth sorting. Set an area's Z axis to a bounded value and the engine natively assumes 2D world behaviors.<br />
* '''[[Collision|Declarative combat collision]]''' - Indexed three-dimensional attack and body boxes carry damage, reaction, motion, status, and presentation behavior.<br />
* '''[[Factions|Composable relationships]]''' - Four independent 52-bit faction masks provide hardware-speed membership, hostility, direct-damage, and indirect-damage rules.<br />
* '''[[Subscreens|Recursive graphics composition]]''' - Script-created subscreens support nested rendering, layer capture, transformations, masks, split screens, and feedback effects.<br />
* '''[[Runtime Script Compilation|Runtime metaprogramming]]''' - Modules can load and combine source files, compile them into independently owned programs, retain persistent state, execute them repeatedly, and replace them during play.<br />
* '''Optimized performance''' - Native systems, high-frequency simulation, and script integration are engineered to maintain steady frame rates and butter-smooth motion with dozens or hundreds of active objects.<br />
<br />
== Getting Started ==<br />
<br />
'''[https://www.chronocrash.com/forum/resources/openbor.1/ Download OpenBOR]''' | '''[https://www.chronocrash.com/forum/resources/categories/samples-and-tutorials.5/?prefix_id=3 Start Building]''' | '''[[:Category:Openbor|Browse the Reference]]''' | '''[https://chronocrash.com Visit the Community]''' | '''[https://github.com/DCurrent/openbor View the Source]'''<br />
<br />
This wiki is the comprehensive technical reference for OpenBOR, but please note it is not intended as a walk-through. For more in-depth instruction, consult the tutorials and guides available through the [https://chronocrash.com/forum ChronoCrash community].<br />
<br />
=== Guides and Resources ===<br />
<br />
* [[OpenBOR Overview]] – General overview of OpenBOR functionality and runtime layout.<br />
* [[:Category:Openbor|OpenBOR Hub]] – Main jumping off point for categories and individual wiki articles.<br />
* [[:Category:OpenBOR Index|OpenBOR Index]] – Simple index of OpenBOR commands, settings, and functions.<br />
* [[Legacy Manual]] – Archival monolithic manual.<br />
* [https://chronocrash.com/ ChronoCrash] – OpenBOR’s home community, including its help forum, downloadable games, and in-depth tutorials.<br />
* [https://github.com/DCurrent/openbor OpenBOR Repository] – Public-facing OpenBOR code base.<br />
<br />
== Development Environment ==<br />
<br />
=== Essential Tools ===<br />
<br />
The following tools are needed to begin building games with OpenBOR. You will need a [https://chronocrash.com/forum ChronoCrash community] account to download some resources.<br />
<br />
* [https://www.chronocrash.com/forum/resources/categories/engine.3/ OpenBOR engine executable] – The latest stable engine release.<br />
* '''[https://www.chronocrash.com/forum/resources/neo-edit-pack.2/ Edit Pack]''' – Tools for packing and unpacking OpenBOR game modules.<br />
* '''Development environment''' – OpenBOR uses a combination of text files and optional script files to configure game functionality. Any text editor may be used. [https://code.visualstudio.com/ Visual Studio Code] is recommended, together with [https://github.com Git] or another version-control system for managing project files.<br />
* '''Graphics software''' – Any graphics-editing application capable of exporting <code>.png</code> images. [https://www.adobe.com Adobe Photoshop] or [https://www.gimp.org/ GIMP] are recommended.<br />
* '''Audio software''' – An audio-editing application capable of exporting <code>.wav</code> files for sound effects and, optionally, <code>.ogg</code> files for music. [https://www.adobe.com/products/audition.html Adobe Audition] or [https://www.audacityteam.org/ Audacity] are recommended.<br />
<br />
=== Optional Tools ===<br />
<br />
These tools are optional but highly recommended.<br />
<br />
* '''[https://www.chronocrash.com/forum/resources/chronocrash-modders-tools.139/ ChronoCrash Modders Tools (CMT)]''' – Visual editing application for building OpenBOR games.<br />
* '''[https://www.chronocrash.com/forum/resources/palapply.15/ PalApply]''' – Applies a palette to one or more images and exports optimized <code>.png</code> files ready for use with OpenBOR.<br />
<br />
== What Open Source Means ==<br />
Because the term has caused confusion and disputes in the past, it is important to clarify what open source means in the context of OpenBOR.<br />
<br />
OpenBOR’s existing codebase is available under a permissive [https://github.com/DCurrent/openbor/blob/master/LICENSE BSD-derived license]. '''Creators may use the engine to make, license, and sell games and other content they rightfully own.''' The OpenBOR license does not claim or control that content.<br />
<br />
Open source does not mean a free-for-all. It provides no implied permission to modify or redistribute another creator’s work without consent. The license also permits binary distribution without requiring source disclosure - it does not compel the team to release existing or future source code, and by extension it does not entitle anyone to the source code of closed-source extensions or obligate the development team to release it. The public repository is provided and maintained as a voluntary act of good faith, not as an obligation imposed by the license.<br />
<br />
The OpenBOR development team may produce proprietary features, such as encrypted pack handling, and license them separately at its discretion.</div>Dcurrenthttps://chronocrash.com/openbor/wiki/index.php?title=Main_Page&diff=1093Main Page2026-08-25T17:34:52Z<p>Dcurrent: /* Why OpenBOR? */</p>
<hr />
<div>== Introduction ==<br />
<br />
=== What is OpenBOR? ===<br />
OpenBOR is a royalty-free, open-source engine for sprite-based games. It combines a complete native game framework - including controls, movement, combat, artificial intelligence, levels, audio, menus, saving, and local multiplayer - with an integrated C-like scripting language that can extend or replace nearly every system.<br />
<br />
OpenBOR specializes in side-scrolling action games such as Double Dragon and Streets of Rage, but its three-dimensional game world, configurable simulation, declarative object system, and scriptable graphics pipeline also support platformers, shooters, role-playing games, puzzle games, and other genres.<br />
<br />
Beginners can build complete games primarily from assets and configuration. Advanced creators can manipulate engine objects, replace native behavior, construct rendering pipelines, and even compile new script programs while a module is running.<br />
<br />
=== Why OpenBOR? ===<br />
What sets OpenBOR apart is how we define its scope. Some engines concentrate on a particular result: role-playing games, one-on-one fighters, shoot-’em-ups, real-time strategy, or puzzles. Others attempt to support every technical medium, leaving developers to build most game-specific functionality themselves. Both are valid approaches. We take a third path by specializing in a technical medium without prescribing the result.<br />
<br />
OpenBOR deliberately limits itself to the simulation and presentation of flat, two-dimensional visual assets in an effectively limitless three-dimensional world. No polygons. No meshes. No skeletal rigs. Just raster graphics moving through three axes. Within that foundation, virtually any sprite-powered concept is possible.<br />
<br />
That focus means we spend our development resources on quality and depth: butter-smooth motion, asset handling, controls, gravity, collision, combat, blocking, grabbing, throwing, artificial intelligence, cameras, level trees, audio, menus, HUDs, saving, and local multiplayer are integrated and ready to use. Everything works together out of the box, with no need to build these foundations or assemble them from third-party plugins.<br />
<br />
Then we layer beat ’em up-oriented behavior over those systems as the default starting point. Supply the necessary assets and configuration, and characters can already move, fight, react, navigate depth, cooperate, and progress through levels. You can have a functional game running within hours, but those defaults don't dictate the finished product.<br />
<br />
Configuration and script expose the same engine objects, properties, and low-level primitives beneath that native behavior. Creators can inspect runtime state, customize selected operations, replace complete subsystems, or combine the primitives into something we never anticipated. The same technical model can support platformers, shooters, role-playing games, puzzles, and other designs far removed from the default.<br />
<br />
The result is a deliberately bounded medium, a complete starting point, and an ending defined only by your imagination.<br />
* '''Complete native gameplay''' - Controls, movement, gravity, level trees, platforms, combat, blocking, grabbing, throwing, artificial intelligence, cameras, audio, menus, HUDs, and saving work without custom code.<br />
* '''[[Script Overview|Engine-wide scripting]]''' - Object APIs and [[:Category:Script Events|more than 70 event hooks]] expose input, animation, movement, collision, damage, spawning, audio, drawing, and other runtime systems for inspection, modification, or replacement.<br />
* '''[[Time|High-resolution simulation]]''' - The configurable logical clock runs at 200 Hz by default and remains independent of display updates.<br />
* '''[[Geometry Overview|Three-dimensional sprite worlds]]''' - Floating-point X, Y, and Z geometry provides subpixel movement, terrain, altitude, and depth sorting. Set a bounded Z axis and the engine natively assumes 2D world behaviors.<br />
* '''[[Collision|Declarative combat collision]]''' - Indexed three-dimensional attack and body boxes carry damage, reaction, motion, status, and presentation behavior.<br />
* '''[[Factions|Composable relationships]]''' - Four independent 52-bit faction masks provide hardware-speed membership, hostility, direct-damage, and indirect-damage rules.<br />
* '''[[Subscreens|Recursive graphics composition]]''' - Script-created subscreens support nested rendering, layer capture, transformations, masks, split screens, and feedback effects.<br />
* '''[[Runtime Script Compilation|Runtime metaprogramming]]''' - Modules can load and combine source files, compile them into independently owned programs, retain persistent state, execute them repeatedly, and replace them during play.<br />
* '''Optimized performance''' - Native systems, high-frequency simulation, and script integration are engineered to maintain steady frame rates and butter-smooth motion with dozens or hundreds of active objects.<br />
<br />
== Getting Started ==<br />
<br />
'''[https://www.chronocrash.com/forum/resources/openbor.1/ Download OpenBOR]''' | '''[https://www.chronocrash.com/forum/resources/categories/samples-and-tutorials.5/?prefix_id=3 Start Building]''' | '''[[:Category:Openbor|Browse the Reference]]''' | '''[https://chronocrash.com Visit the Community]''' | '''[https://github.com/DCurrent/openbor View the Source]'''<br />
<br />
This wiki is the comprehensive technical reference for OpenBOR, but please note it is not intended as a walk-through. For more in-depth instruction, consult the tutorials and guides available through the [https://chronocrash.com/forum ChronoCrash community].<br />
<br />
=== Guides and Resources ===<br />
<br />
* [[OpenBOR Overview]] – General overview of OpenBOR functionality and runtime layout.<br />
* [[:Category:Openbor|OpenBOR Hub]] – Main jumping off point for categories and individual wiki articles.<br />
* [[:Category:OpenBOR Index|OpenBOR Index]] – Simple index of OpenBOR commands, settings, and functions.<br />
* [[Legacy Manual]] – Archival monolithic manual.<br />
* [https://chronocrash.com/ ChronoCrash] – OpenBOR’s home community, including its help forum, downloadable games, and in-depth tutorials.<br />
* [https://github.com/DCurrent/openbor OpenBOR Repository] – Public-facing OpenBOR code base.<br />
<br />
== Development Environment ==<br />
<br />
=== Essential Tools ===<br />
<br />
The following tools are needed to begin building games with OpenBOR. You will need a [https://chronocrash.com/forum ChronoCrash community] account to download some resources.<br />
<br />
* [https://www.chronocrash.com/forum/resources/categories/engine.3/ OpenBOR engine executable] – The latest stable engine release.<br />
* '''[https://www.chronocrash.com/forum/resources/neo-edit-pack.2/ Edit Pack]''' – Tools for packing and unpacking OpenBOR game modules.<br />
* '''Development environment''' – OpenBOR uses a combination of text files and optional script files to configure game functionality. Any text editor may be used. [https://code.visualstudio.com/ Visual Studio Code] is recommended, together with [https://github.com Git] or another version-control system for managing project files.<br />
* '''Graphics software''' – Any graphics-editing application capable of exporting <code>.png</code> images. [https://www.adobe.com Adobe Photoshop] or [https://www.gimp.org/ GIMP] are recommended.<br />
* '''Audio software''' – An audio-editing application capable of exporting <code>.wav</code> files for sound effects and, optionally, <code>.ogg</code> files for music. [https://www.adobe.com/products/audition.html Adobe Audition] or [https://www.audacityteam.org/ Audacity] are recommended.<br />
<br />
=== Optional Tools ===<br />
<br />
These tools are optional but highly recommended.<br />
<br />
* '''[https://www.chronocrash.com/forum/resources/chronocrash-modders-tools.139/ ChronoCrash Modders Tools (CMT)]''' – Visual editing application for building OpenBOR games.<br />
* '''[https://www.chronocrash.com/forum/resources/palapply.15/ PalApply]''' – Applies a palette to one or more images and exports optimized <code>.png</code> files ready for use with OpenBOR.<br />
<br />
== What Open Source Means ==<br />
Because the term has caused confusion and disputes in the past, it is important to clarify what open source means in the context of OpenBOR.<br />
<br />
OpenBOR’s existing codebase is available under a permissive [https://github.com/DCurrent/openbor/blob/master/LICENSE BSD-derived license]. '''Creators may use the engine to make, license, and sell games and other content they rightfully own.''' The OpenBOR license does not claim or control that content.<br />
<br />
Open source does not mean a free-for-all. It provides no implied permission to modify or redistribute another creator’s work without consent. The license also permits binary distribution without requiring source disclosure - it does not compel the team to release existing or future source code, and by extension it does not entitle anyone to the source code of closed-source extensions or obligate the development team to release it. The public repository is provided and maintained as a voluntary act of good faith, not as an obligation imposed by the license.<br />
<br />
The OpenBOR development team may produce proprietary features, such as encrypted pack handling, and license them separately at its discretion.</div>Dcurrenthttps://chronocrash.com/openbor/wiki/index.php?title=Main_Page&diff=1092Main Page2026-08-25T17:30:48Z<p>Dcurrent: /* Why OpenBOR? */</p>
<hr />
<div>== Introduction ==<br />
<br />
=== What is OpenBOR? ===<br />
OpenBOR is a royalty-free, open-source engine for sprite-based games. It combines a complete native game framework - including controls, movement, combat, artificial intelligence, levels, audio, menus, saving, and local multiplayer - with an integrated C-like scripting language that can extend or replace nearly every system.<br />
<br />
OpenBOR specializes in side-scrolling action games such as Double Dragon and Streets of Rage, but its three-dimensional game world, configurable simulation, declarative object system, and scriptable graphics pipeline also support platformers, shooters, role-playing games, puzzle games, and other genres.<br />
<br />
Beginners can build complete games primarily from assets and configuration. Advanced creators can manipulate engine objects, replace native behavior, construct rendering pipelines, and even compile new script programs while a module is running.<br />
<br />
=== Why OpenBOR? ===<br />
What sets OpenBOR apart is how we define its scope. Some engines concentrate on a particular result: role-playing games, one-on-one fighters, shoot-’em-ups, real-time strategy, or puzzles. Others attempt to support every technical medium, leaving developers to build most game-specific functionality themselves. Both are valid approaches. We take a third path by specializing in a technical medium without prescribing the result.<br />
<br />
OpenBOR deliberately limits itself to the simulation and presentation of flat, two-dimensional visual assets in an effectively limitless three-dimensional world. No polygons. No meshes. No skeletal rigs. Just raster graphics moving through three axes. Within that foundation, virtually any sprite-powered concept is possible.<br />
<br />
That focus means we spend our development resources on quality and depth: butter-smooth motion, asset handling, controls, gravity, collision, combat, blocking, grabbing, throwing, artificial intelligence, cameras, level trees, audio, menus, HUDs, saving, and local multiplayer are integrated and ready to use. Everything works together out of the box, with no need to build these foundations or assemble them from third-party plugins.<br />
<br />
Then we layer beat ’em up-oriented behavior over those systems as the default starting point. Supply the necessary assets and configuration, and characters can already move, fight, react, navigate depth, cooperate, and progress through levels. You can have a functional game running within hours, but those defaults don't dictate the finished product.<br />
<br />
Configuration and script expose the same engine objects, properties, and low-level primitives beneath that native behavior. Creators can inspect runtime state, customize selected operations, replace complete subsystems, or combine the primitives into something we never anticipated. The same technical model can support platformers, shooters, role-playing games, puzzles, and other designs far removed from the default.<br />
<br />
The result is a deliberately bounded medium, a complete starting point, and an ending defined only by your imagination.<br />
* '''Complete native gameplay''' - Controls, movement, gravity, level trees, platforms, combat, blocking, grabbing, throwing, artificial intelligence, cameras, audio, menus, HUDs, and saving work without custom code.<br />
* '''[[Script Overview|Engine-wide scripting]]''' - Object APIs and [[:Category:Script Events|more than 70 event hooks]] expose input, animation, movement, collision, damage, spawning, audio, drawing, and other runtime systems for inspection, modification, or replacement.<br />
* '''[[Time|High-resolution simulation]]''' - The configurable logical clock runs at 200 Hz by default and remains independent of display updates.<br />
* '''[[Geometry Overview|Three-dimensional sprite worlds]]''' - Floating-point X, Y, and Z geometry provides subpixel movement, terrain, altitude, and depth sorting.<br />
* '''[[Collision|Declarative combat collision]]''' - Indexed three-dimensional attack and body boxes carry damage, reaction, motion, status, and presentation behavior.<br />
* '''[[Factions|Composable relationships]]''' - Four independent 52-bit faction masks provide hardware-speed membership, hostility, direct-damage, and indirect-damage rules.<br />
* '''[[Subscreens|Recursive graphics composition]]''' - Script-created subscreens support nested rendering, layer capture, transformations, masks, split screens, and feedback effects.<br />
* '''[[Runtime Script Compilation|Runtime metaprogramming]]''' - Modules can load and combine source files, compile them into independently owned programs, retain persistent state, execute them repeatedly, and replace them during play.<br />
* '''Optimized performance''' - Native systems, high-frequency simulation, and script integration are engineered to maintain steady frame rates and butter-smooth motion with dozens or hundreds of active objects.<br />
<br />
== Getting Started ==<br />
<br />
'''[https://www.chronocrash.com/forum/resources/openbor.1/ Download OpenBOR]''' | '''[https://www.chronocrash.com/forum/resources/categories/samples-and-tutorials.5/?prefix_id=3 Start Building]''' | '''[[:Category:Openbor|Browse the Reference]]''' | '''[https://chronocrash.com Visit the Community]''' | '''[https://github.com/DCurrent/openbor View the Source]'''<br />
<br />
This wiki is the comprehensive technical reference for OpenBOR, but please note it is not intended as a walk-through. For more in-depth instruction, consult the tutorials and guides available through the [https://chronocrash.com/forum ChronoCrash community].<br />
<br />
=== Guides and Resources ===<br />
<br />
* [[OpenBOR Overview]] – General overview of OpenBOR functionality and runtime layout.<br />
* [[:Category:Openbor|OpenBOR Hub]] – Main jumping off point for categories and individual wiki articles.<br />
* [[:Category:OpenBOR Index|OpenBOR Index]] – Simple index of OpenBOR commands, settings, and functions.<br />
* [[Legacy Manual]] – Archival monolithic manual.<br />
* [https://chronocrash.com/ ChronoCrash] – OpenBOR’s home community, including its help forum, downloadable games, and in-depth tutorials.<br />
* [https://github.com/DCurrent/openbor OpenBOR Repository] – Public-facing OpenBOR code base.<br />
<br />
== Development Environment ==<br />
<br />
=== Essential Tools ===<br />
<br />
The following tools are needed to begin building games with OpenBOR. You will need a [https://chronocrash.com/forum ChronoCrash community] account to download some resources.<br />
<br />
* [https://www.chronocrash.com/forum/resources/categories/engine.3/ OpenBOR engine executable] – The latest stable engine release.<br />
* '''[https://www.chronocrash.com/forum/resources/neo-edit-pack.2/ Edit Pack]''' – Tools for packing and unpacking OpenBOR game modules.<br />
* '''Development environment''' – OpenBOR uses a combination of text files and optional script files to configure game functionality. Any text editor may be used. [https://code.visualstudio.com/ Visual Studio Code] is recommended, together with [https://github.com Git] or another version-control system for managing project files.<br />
* '''Graphics software''' – Any graphics-editing application capable of exporting <code>.png</code> images. [https://www.adobe.com Adobe Photoshop] or [https://www.gimp.org/ GIMP] are recommended.<br />
* '''Audio software''' – An audio-editing application capable of exporting <code>.wav</code> files for sound effects and, optionally, <code>.ogg</code> files for music. [https://www.adobe.com/products/audition.html Adobe Audition] or [https://www.audacityteam.org/ Audacity] are recommended.<br />
<br />
=== Optional Tools ===<br />
<br />
These tools are optional but highly recommended.<br />
<br />
* '''[https://www.chronocrash.com/forum/resources/chronocrash-modders-tools.139/ ChronoCrash Modders Tools (CMT)]''' – Visual editing application for building OpenBOR games.<br />
* '''[https://www.chronocrash.com/forum/resources/palapply.15/ PalApply]''' – Applies a palette to one or more images and exports optimized <code>.png</code> files ready for use with OpenBOR.<br />
<br />
== What Open Source Means ==<br />
Because the term has caused confusion and disputes in the past, it is important to clarify what open source means in the context of OpenBOR.<br />
<br />
OpenBOR’s existing codebase is available under a permissive [https://github.com/DCurrent/openbor/blob/master/LICENSE BSD-derived license]. '''Creators may use the engine to make, license, and sell games and other content they rightfully own.''' The OpenBOR license does not claim or control that content.<br />
<br />
Open source does not mean a free-for-all. It provides no implied permission to modify or redistribute another creator’s work without consent. The license also permits binary distribution without requiring source disclosure - it does not compel the team to release existing or future source code, and by extension it does not entitle anyone to the source code of closed-source extensions or obligate the development team to release it. The public repository is provided and maintained as a voluntary act of good faith, not as an obligation imposed by the license.<br />
<br />
The OpenBOR development team may produce proprietary features, such as encrypted pack handling, and license them separately at its discretion.</div>Dcurrenthttps://chronocrash.com/openbor/wiki/index.php?title=Main_Page&diff=1091Main Page2026-08-25T17:28:46Z<p>Dcurrent: /* Why OpenBOR? */</p>
<hr />
<div>== Introduction ==<br />
<br />
=== What is OpenBOR? ===<br />
OpenBOR is a royalty-free, open-source engine for sprite-based games. It combines a complete native game framework - including controls, movement, combat, artificial intelligence, levels, audio, menus, saving, and local multiplayer - with an integrated C-like scripting language that can extend or replace nearly every system.<br />
<br />
OpenBOR specializes in side-scrolling action games such as Double Dragon and Streets of Rage, but its three-dimensional game world, configurable simulation, declarative object system, and scriptable graphics pipeline also support platformers, shooters, role-playing games, puzzle games, and other genres.<br />
<br />
Beginners can build complete games primarily from assets and configuration. Advanced creators can manipulate engine objects, replace native behavior, construct rendering pipelines, and even compile new script programs while a module is running.<br />
<br />
=== Why OpenBOR? ===<br />
What sets OpenBOR apart is how we define its scope. Some engines concentrate on a particular result: role-playing games, one-on-one fighters, shoot-’em-ups, real-time strategy, or puzzles. Others attempt to support every technical medium, leaving developers to build most game-specific functionality themselves. Both are valid approaches. We take a third path by specializing in a technical medium without prescribing the result.<br />
<br />
OpenBOR deliberately limits itself to the simulation and presentation of flat, two-dimensional visual assets in an effectively limitless three-dimensional world. No polygons. No meshes. No skeletal rigs. Just raster graphics moving through three axes. Within that foundation, virtually any sprite-powered concept is possible.<br />
<br />
That focus means we spend our development resources on quality and depth: butter-smooth motion, asset handling, controls, gravity, collision, combat, blocking, grabbing, throwing, artificial intelligence, cameras, level trees, audio, menus, HUDs, saving, and local multiplayer are integrated and ready to use. Everything works together out of the box, with no need to build these foundations or assemble them from third-party plugins.<br />
<br />
We layer beat ’em up-oriented behavior over those systems as the default starting point. Supply the necessary assets and configuration, and characters can already move, fight, react, navigate depth, cooperate, and progress through levels. You can have a functional game running within hours, but those defaults don't dictate the finished product.<br />
<br />
Configuration and script expose the same engine objects, properties, and low-level primitives beneath that native behavior. Creators can inspect runtime state, customize selected operations, replace complete subsystems, or combine the primitives into something we never anticipated. The same technical model can support platformers, shooters, role-playing games, puzzles, and other designs far removed from the default.<br />
<br />
The result is a deliberately bounded medium, a complete starting point, and an ending defined only by your imagination.<br />
* '''Complete native gameplay''' - Controls, movement, gravity, level trees, platforms, combat, blocking, grabbing, throwing, artificial intelligence, cameras, audio, menus, HUDs, and saving work without custom code.<br />
* '''[[Script Overview|Engine-wide scripting]]''' - Object APIs and [[:Category:Script Events|more than 70 event hooks]] expose input, animation, movement, collision, damage, spawning, audio, drawing, and other runtime systems for inspection, modification, or replacement.<br />
* '''[[Time|High-resolution simulation]]''' - The configurable logical clock runs at 200 Hz by default and remains independent of display updates.<br />
* '''[[Geometry Overview|Three-dimensional sprite worlds]]''' - Floating-point X, Y, and Z geometry provides subpixel movement, terrain, altitude, and depth sorting.<br />
* '''[[Collision|Declarative combat collision]]''' - Indexed three-dimensional attack and body boxes carry damage, reaction, motion, status, and presentation behavior.<br />
* '''[[Factions|Composable relationships]]''' - Four independent 52-bit faction masks provide hardware-speed membership, hostility, direct-damage, and indirect-damage rules.<br />
* '''[[Subscreens|Recursive graphics composition]]''' - Script-created subscreens support nested rendering, layer capture, transformations, masks, split screens, and feedback effects.<br />
* '''[[Runtime Script Compilation|Runtime metaprogramming]]''' - Modules can load and combine source files, compile them into independently owned programs, retain persistent state, execute them repeatedly, and replace them during play.<br />
* '''Optimized performance''' - Native systems, high-frequency simulation, and script integration are engineered to maintain steady frame rates and butter-smooth motion with dozens or hundreds of active objects.<br />
<br />
== Getting Started ==<br />
<br />
'''[https://www.chronocrash.com/forum/resources/openbor.1/ Download OpenBOR]''' | '''[https://www.chronocrash.com/forum/resources/categories/samples-and-tutorials.5/?prefix_id=3 Start Building]''' | '''[[:Category:Openbor|Browse the Reference]]''' | '''[https://chronocrash.com Visit the Community]''' | '''[https://github.com/DCurrent/openbor View the Source]'''<br />
<br />
This wiki is the comprehensive technical reference for OpenBOR, but please note it is not intended as a walk-through. For more in-depth instruction, consult the tutorials and guides available through the [https://chronocrash.com/forum ChronoCrash community].<br />
<br />
=== Guides and Resources ===<br />
<br />
* [[OpenBOR Overview]] – General overview of OpenBOR functionality and runtime layout.<br />
* [[:Category:Openbor|OpenBOR Hub]] – Main jumping off point for categories and individual wiki articles.<br />
* [[:Category:OpenBOR Index|OpenBOR Index]] – Simple index of OpenBOR commands, settings, and functions.<br />
* [[Legacy Manual]] – Archival monolithic manual.<br />
* [https://chronocrash.com/ ChronoCrash] – OpenBOR’s home community, including its help forum, downloadable games, and in-depth tutorials.<br />
* [https://github.com/DCurrent/openbor OpenBOR Repository] – Public-facing OpenBOR code base.<br />
<br />
== Development Environment ==<br />
<br />
=== Essential Tools ===<br />
<br />
The following tools are needed to begin building games with OpenBOR. You will need a [https://chronocrash.com/forum ChronoCrash community] account to download some resources.<br />
<br />
* [https://www.chronocrash.com/forum/resources/categories/engine.3/ OpenBOR engine executable] – The latest stable engine release.<br />
* '''[https://www.chronocrash.com/forum/resources/neo-edit-pack.2/ Edit Pack]''' – Tools for packing and unpacking OpenBOR game modules.<br />
* '''Development environment''' – OpenBOR uses a combination of text files and optional script files to configure game functionality. Any text editor may be used. [https://code.visualstudio.com/ Visual Studio Code] is recommended, together with [https://github.com Git] or another version-control system for managing project files.<br />
* '''Graphics software''' – Any graphics-editing application capable of exporting <code>.png</code> images. [https://www.adobe.com Adobe Photoshop] or [https://www.gimp.org/ GIMP] are recommended.<br />
* '''Audio software''' – An audio-editing application capable of exporting <code>.wav</code> files for sound effects and, optionally, <code>.ogg</code> files for music. [https://www.adobe.com/products/audition.html Adobe Audition] or [https://www.audacityteam.org/ Audacity] are recommended.<br />
<br />
=== Optional Tools ===<br />
<br />
These tools are optional but highly recommended.<br />
<br />
* '''[https://www.chronocrash.com/forum/resources/chronocrash-modders-tools.139/ ChronoCrash Modders Tools (CMT)]''' – Visual editing application for building OpenBOR games.<br />
* '''[https://www.chronocrash.com/forum/resources/palapply.15/ PalApply]''' – Applies a palette to one or more images and exports optimized <code>.png</code> files ready for use with OpenBOR.<br />
<br />
== What Open Source Means ==<br />
Because the term has caused confusion and disputes in the past, it is important to clarify what open source means in the context of OpenBOR.<br />
<br />
OpenBOR’s existing codebase is available under a permissive [https://github.com/DCurrent/openbor/blob/master/LICENSE BSD-derived license]. '''Creators may use the engine to make, license, and sell games and other content they rightfully own.''' The OpenBOR license does not claim or control that content.<br />
<br />
Open source does not mean a free-for-all. It provides no implied permission to modify or redistribute another creator’s work without consent. The license also permits binary distribution without requiring source disclosure - it does not compel the team to release existing or future source code, and by extension it does not entitle anyone to the source code of closed-source extensions or obligate the development team to release it. The public repository is provided and maintained as a voluntary act of good faith, not as an obligation imposed by the license.<br />
<br />
The OpenBOR development team may produce proprietary features, such as encrypted pack handling, and license them separately at its discretion.</div>Dcurrenthttps://chronocrash.com/openbor/wiki/index.php?title=Main_Page&diff=1090Main Page2026-08-25T17:23:32Z<p>Dcurrent: /* Why OpenBOR? */</p>
<hr />
<div>== Introduction ==<br />
<br />
=== What is OpenBOR? ===<br />
OpenBOR is a royalty-free, open-source engine for sprite-based games. It combines a complete native game framework - including controls, movement, combat, artificial intelligence, levels, audio, menus, saving, and local multiplayer - with an integrated C-like scripting language that can extend or replace nearly every system.<br />
<br />
OpenBOR specializes in side-scrolling action games such as Double Dragon and Streets of Rage, but its three-dimensional game world, configurable simulation, declarative object system, and scriptable graphics pipeline also support platformers, shooters, role-playing games, puzzle games, and other genres.<br />
<br />
Beginners can build complete games primarily from assets and configuration. Advanced creators can manipulate engine objects, replace native behavior, construct rendering pipelines, and even compile new script programs while a module is running.<br />
<br />
=== Why OpenBOR? ===<br />
What sets OpenBOR apart is how we define its scope. Some engines concentrate on a particular result: role-playing games, one-on-one fighters, shoot-’em-ups, real-time strategy, or puzzles. Others attempt to support every technical medium, leaving developers to build most game-specific functionality themselves. Both are valid approaches. We take a third path by specializing in a technical medium without prescribing the result.<br />
<br />
OpenBOR deliberately limits itself to the simulation and presentation of flat, two-dimensional visual assets in an effectively limitless three-dimensional world. No polygons. No meshes. No skeletal rigs. Just raster graphics moving through three axes. Within that foundation, virtually any sprite-powered concept is possible.<br />
<br />
That focus lets us invest our development resources on quality and depth. Butter smooth motion, asset handling, controls, gravity, collision, combat, blocking, grabbing, throwing, artificial intelligence, cameras, level trees, audio, menus, HUDs, saving, and local multiplayer are integrated and ready to use. Everything works together out of the box, with no need to build these foundations or assemble them from third-party plugins.<br />
<br />
We layer beat ’em up-oriented behavior over those systems as the default starting point. Supply the necessary assets and configuration, and characters can already move, fight, react, navigate depth, cooperate, and progress through levels. You can have a functional game running within hours, but those defaults don't dictate the finished product.<br />
<br />
Configuration and script expose the same engine objects, properties, and low-level primitives beneath that native behavior. Creators can inspect runtime state, customize selected operations, replace complete subsystems, or combine the primitives into something we never anticipated. The same technical model can support platformers, shooters, role-playing games, puzzles, and other designs far removed from the default.<br />
<br />
The result is a deliberately bounded medium, a complete starting point, and an ending defined only by your imagination.<br />
* '''Complete native gameplay''' - Controls, movement, gravity, level trees, platforms, combat, blocking, grabbing, throwing, artificial intelligence, cameras, audio, menus, HUDs, and saving work without custom code.<br />
* '''[[Script Overview|Engine-wide scripting]]''' - Object APIs and [[:Category:Script Events|more than 70 event hooks]] expose input, animation, movement, collision, damage, spawning, audio, drawing, and other runtime systems for inspection, modification, or replacement.<br />
* '''[[Time|High-resolution simulation]]''' - The configurable logical clock runs at 200 Hz by default and remains independent of display updates.<br />
* '''[[Geometry Overview|Three-dimensional sprite worlds]]''' - Floating-point X, Y, and Z geometry provides subpixel movement, terrain, altitude, and depth sorting.<br />
* '''[[Collision|Declarative combat collision]]''' - Indexed three-dimensional attack and body boxes carry damage, reaction, motion, status, and presentation behavior.<br />
* '''[[Factions|Composable relationships]]''' - Four independent 52-bit faction masks provide hardware-speed membership, hostility, direct-damage, and indirect-damage rules.<br />
* '''[[Subscreens|Recursive graphics composition]]''' - Script-created subscreens support nested rendering, layer capture, transformations, masks, split screens, and feedback effects.<br />
* '''[[Runtime Script Compilation|Runtime metaprogramming]]''' - Modules can load and combine source files, compile them into independently owned programs, retain persistent state, execute them repeatedly, and replace them during play.<br />
* '''Optimized performance''' - Native systems, high-frequency simulation, and script integration are engineered to maintain steady frame rates and butter-smooth motion with dozens or hundreds of active objects.<br />
<br />
== Getting Started ==<br />
<br />
'''[https://www.chronocrash.com/forum/resources/openbor.1/ Download OpenBOR]''' | '''[https://www.chronocrash.com/forum/resources/categories/samples-and-tutorials.5/?prefix_id=3 Start Building]''' | '''[[:Category:Openbor|Browse the Reference]]''' | '''[https://chronocrash.com Visit the Community]''' | '''[https://github.com/DCurrent/openbor View the Source]'''<br />
<br />
This wiki is the comprehensive technical reference for OpenBOR, but please note it is not intended as a walk-through. For more in-depth instruction, consult the tutorials and guides available through the [https://chronocrash.com/forum ChronoCrash community].<br />
<br />
=== Guides and Resources ===<br />
<br />
* [[OpenBOR Overview]] – General overview of OpenBOR functionality and runtime layout.<br />
* [[:Category:Openbor|OpenBOR Hub]] – Main jumping off point for categories and individual wiki articles.<br />
* [[:Category:OpenBOR Index|OpenBOR Index]] – Simple index of OpenBOR commands, settings, and functions.<br />
* [[Legacy Manual]] – Archival monolithic manual.<br />
* [https://chronocrash.com/ ChronoCrash] – OpenBOR’s home community, including its help forum, downloadable games, and in-depth tutorials.<br />
* [https://github.com/DCurrent/openbor OpenBOR Repository] – Public-facing OpenBOR code base.<br />
<br />
== Development Environment ==<br />
<br />
=== Essential Tools ===<br />
<br />
The following tools are needed to begin building games with OpenBOR. You will need a [https://chronocrash.com/forum ChronoCrash community] account to download some resources.<br />
<br />
* [https://www.chronocrash.com/forum/resources/categories/engine.3/ OpenBOR engine executable] – The latest stable engine release.<br />
* '''[https://www.chronocrash.com/forum/resources/neo-edit-pack.2/ Edit Pack]''' – Tools for packing and unpacking OpenBOR game modules.<br />
* '''Development environment''' – OpenBOR uses a combination of text files and optional script files to configure game functionality. Any text editor may be used. [https://code.visualstudio.com/ Visual Studio Code] is recommended, together with [https://github.com Git] or another version-control system for managing project files.<br />
* '''Graphics software''' – Any graphics-editing application capable of exporting <code>.png</code> images. [https://www.adobe.com Adobe Photoshop] or [https://www.gimp.org/ GIMP] are recommended.<br />
* '''Audio software''' – An audio-editing application capable of exporting <code>.wav</code> files for sound effects and, optionally, <code>.ogg</code> files for music. [https://www.adobe.com/products/audition.html Adobe Audition] or [https://www.audacityteam.org/ Audacity] are recommended.<br />
<br />
=== Optional Tools ===<br />
<br />
These tools are optional but highly recommended.<br />
<br />
* '''[https://www.chronocrash.com/forum/resources/chronocrash-modders-tools.139/ ChronoCrash Modders Tools (CMT)]''' – Visual editing application for building OpenBOR games.<br />
* '''[https://www.chronocrash.com/forum/resources/palapply.15/ PalApply]''' – Applies a palette to one or more images and exports optimized <code>.png</code> files ready for use with OpenBOR.<br />
<br />
== What Open Source Means ==<br />
Because the term has caused confusion and disputes in the past, it is important to clarify what open source means in the context of OpenBOR.<br />
<br />
OpenBOR’s existing codebase is available under a permissive [https://github.com/DCurrent/openbor/blob/master/LICENSE BSD-derived license]. '''Creators may use the engine to make, license, and sell games and other content they rightfully own.''' The OpenBOR license does not claim or control that content.<br />
<br />
Open source does not mean a free-for-all. It provides no implied permission to modify or redistribute another creator’s work without consent. The license also permits binary distribution without requiring source disclosure - it does not compel the team to release existing or future source code, and by extension it does not entitle anyone to the source code of closed-source extensions or obligate the development team to release it. The public repository is provided and maintained as a voluntary act of good faith, not as an obligation imposed by the license.<br />
<br />
The OpenBOR development team may produce proprietary features, such as encrypted pack handling, and license them separately at its discretion.</div>Dcurrenthttps://chronocrash.com/openbor/wiki/index.php?title=Main_Page&diff=1089Main Page2026-08-25T17:21:14Z<p>Dcurrent: /* Why OpenBOR? */</p>
<hr />
<div>== Introduction ==<br />
<br />
=== What is OpenBOR? ===<br />
OpenBOR is a royalty-free, open-source engine for sprite-based games. It combines a complete native game framework - including controls, movement, combat, artificial intelligence, levels, audio, menus, saving, and local multiplayer - with an integrated C-like scripting language that can extend or replace nearly every system.<br />
<br />
OpenBOR specializes in side-scrolling action games such as Double Dragon and Streets of Rage, but its three-dimensional game world, configurable simulation, declarative object system, and scriptable graphics pipeline also support platformers, shooters, role-playing games, puzzle games, and other genres.<br />
<br />
Beginners can build complete games primarily from assets and configuration. Advanced creators can manipulate engine objects, replace native behavior, construct rendering pipelines, and even compile new script programs while a module is running.<br />
<br />
=== Why OpenBOR? ===<br />
What sets OpenBOR apart is how we define its scope. Some engines concentrate on a particular result: role-playing games, one-on-one fighters, shoot-’em-ups, real-time strategy, or puzzles. Others attempt to support every technical medium, leaving developers to build most game-specific functionality themselves. Both are valid approaches. We take a third path by specializing in a technical medium without prescribing the result.<br />
<br />
OpenBOR deliberately limits itself to the simulation and presentation of flat, two-dimensional visual assets in an effectively limitless three-dimensional world. No polygons. No meshes. No skeletal rigs. Just raster graphics moving through three axes. Within that foundation, virtually any sprite-powered concept is possible.<br />
<br />
That focus lets us invest our development resources in depth. Asset handling, controls, movement, gravity, collision, combat, blocking, grabbing, throwing, artificial intelligence, cameras, level trees, audio, menus, HUDs, saving, and local multiplayer are integrated and ready to use. Everything works together out of the box, with no need to build these foundations or assemble them from third-party plugins.<br />
<br />
We layer beat ’em up-oriented behavior over those systems as the default starting point. Supply the necessary assets and configuration, and characters can already move, fight, react, navigate depth, cooperate, and progress through levels. You can have a functional game running within hours, but those defaults don't dictate the finished product.<br />
<br />
Configuration and script expose the same engine objects, properties, and low-level primitives beneath that native behavior. Creators can inspect runtime state, customize selected operations, replace complete subsystems, or combine the primitives into something we never anticipated. The same technical model can support platformers, shooters, role-playing games, puzzles, and other designs far removed from the default.<br />
<br />
The result is a deliberately bounded medium, a complete starting point, and an ending defined only by your imagination.<br />
* '''Complete native gameplay''' - Controls, movement, gravity, level trees, platforms, combat, blocking, grabbing, throwing, artificial intelligence, cameras, audio, menus, HUDs, and saving work without custom code.<br />
* '''[[Script Overview|Engine-wide scripting]]''' - Object APIs and [[:Category:Script Events|more than 70 event hooks]] expose input, animation, movement, collision, damage, spawning, audio, drawing, and other runtime systems for inspection, modification, or replacement.<br />
* '''[[Time|High-resolution simulation]]''' - The configurable logical clock runs at 200 Hz by default and remains independent of display updates.<br />
* '''[[Geometry Overview|Three-dimensional sprite worlds]]''' - Floating-point X, Y, and Z geometry provides subpixel movement, terrain, altitude, and depth sorting.<br />
* '''[[Collision|Declarative combat collision]]''' - Indexed three-dimensional attack and body boxes carry damage, reaction, motion, status, and presentation behavior.<br />
* '''[[Factions|Composable relationships]]''' - Four independent 52-bit faction masks provide hardware-speed membership, hostility, direct-damage, and indirect-damage rules.<br />
* '''[[Subscreens|Recursive graphics composition]]''' - Script-created subscreens support nested rendering, layer capture, transformations, masks, split screens, and feedback effects.<br />
* '''[[Runtime Script Compilation|Runtime metaprogramming]]''' - Modules can load and combine source files, compile them into independently owned programs, retain persistent state, execute them repeatedly, and replace them during play.<br />
* '''Optimized performance''' - Native systems, high-frequency simulation, and script integration are engineered to maintain steady frame rates and butter-smooth motion with dozens or hundreds of active objects.<br />
<br />
== Getting Started ==<br />
<br />
'''[https://www.chronocrash.com/forum/resources/openbor.1/ Download OpenBOR]''' | '''[https://www.chronocrash.com/forum/resources/categories/samples-and-tutorials.5/?prefix_id=3 Start Building]''' | '''[[:Category:Openbor|Browse the Reference]]''' | '''[https://chronocrash.com Visit the Community]''' | '''[https://github.com/DCurrent/openbor View the Source]'''<br />
<br />
This wiki is the comprehensive technical reference for OpenBOR, but please note it is not intended as a walk-through. For more in-depth instruction, consult the tutorials and guides available through the [https://chronocrash.com/forum ChronoCrash community].<br />
<br />
=== Guides and Resources ===<br />
<br />
* [[OpenBOR Overview]] – General overview of OpenBOR functionality and runtime layout.<br />
* [[:Category:Openbor|OpenBOR Hub]] – Main jumping off point for categories and individual wiki articles.<br />
* [[:Category:OpenBOR Index|OpenBOR Index]] – Simple index of OpenBOR commands, settings, and functions.<br />
* [[Legacy Manual]] – Archival monolithic manual.<br />
* [https://chronocrash.com/ ChronoCrash] – OpenBOR’s home community, including its help forum, downloadable games, and in-depth tutorials.<br />
* [https://github.com/DCurrent/openbor OpenBOR Repository] – Public-facing OpenBOR code base.<br />
<br />
== Development Environment ==<br />
<br />
=== Essential Tools ===<br />
<br />
The following tools are needed to begin building games with OpenBOR. You will need a [https://chronocrash.com/forum ChronoCrash community] account to download some resources.<br />
<br />
* [https://www.chronocrash.com/forum/resources/categories/engine.3/ OpenBOR engine executable] – The latest stable engine release.<br />
* '''[https://www.chronocrash.com/forum/resources/neo-edit-pack.2/ Edit Pack]''' – Tools for packing and unpacking OpenBOR game modules.<br />
* '''Development environment''' – OpenBOR uses a combination of text files and optional script files to configure game functionality. Any text editor may be used. [https://code.visualstudio.com/ Visual Studio Code] is recommended, together with [https://github.com Git] or another version-control system for managing project files.<br />
* '''Graphics software''' – Any graphics-editing application capable of exporting <code>.png</code> images. [https://www.adobe.com Adobe Photoshop] or [https://www.gimp.org/ GIMP] are recommended.<br />
* '''Audio software''' – An audio-editing application capable of exporting <code>.wav</code> files for sound effects and, optionally, <code>.ogg</code> files for music. [https://www.adobe.com/products/audition.html Adobe Audition] or [https://www.audacityteam.org/ Audacity] are recommended.<br />
<br />
=== Optional Tools ===<br />
<br />
These tools are optional but highly recommended.<br />
<br />
* '''[https://www.chronocrash.com/forum/resources/chronocrash-modders-tools.139/ ChronoCrash Modders Tools (CMT)]''' – Visual editing application for building OpenBOR games.<br />
* '''[https://www.chronocrash.com/forum/resources/palapply.15/ PalApply]''' – Applies a palette to one or more images and exports optimized <code>.png</code> files ready for use with OpenBOR.<br />
<br />
== What Open Source Means ==<br />
Because the term has caused confusion and disputes in the past, it is important to clarify what open source means in the context of OpenBOR.<br />
<br />
OpenBOR’s existing codebase is available under a permissive [https://github.com/DCurrent/openbor/blob/master/LICENSE BSD-derived license]. '''Creators may use the engine to make, license, and sell games and other content they rightfully own.''' The OpenBOR license does not claim or control that content.<br />
<br />
Open source does not mean a free-for-all. It provides no implied permission to modify or redistribute another creator’s work without consent. The license also permits binary distribution without requiring source disclosure - it does not compel the team to release existing or future source code, and by extension it does not entitle anyone to the source code of closed-source extensions or obligate the development team to release it. The public repository is provided and maintained as a voluntary act of good faith, not as an obligation imposed by the license.<br />
<br />
The OpenBOR development team may produce proprietary features, such as encrypted pack handling, and license them separately at its discretion.</div>Dcurrenthttps://chronocrash.com/openbor/wiki/index.php?title=Main_Page&diff=1088Main Page2026-08-25T17:13:11Z<p>Dcurrent: /* Why OpenBOR? */</p>
<hr />
<div>== Introduction ==<br />
<br />
=== What is OpenBOR? ===<br />
OpenBOR is a royalty-free, open-source engine for sprite-based games. It combines a complete native game framework - including controls, movement, combat, artificial intelligence, levels, audio, menus, saving, and local multiplayer - with an integrated C-like scripting language that can extend or replace nearly every system.<br />
<br />
OpenBOR specializes in side-scrolling action games such as Double Dragon and Streets of Rage, but its three-dimensional game world, configurable simulation, declarative object system, and scriptable graphics pipeline also support platformers, shooters, role-playing games, puzzle games, and other genres.<br />
<br />
Beginners can build complete games primarily from assets and configuration. Advanced creators can manipulate engine objects, replace native behavior, construct rendering pipelines, and even compile new script programs while a module is running.<br />
<br />
=== Why OpenBOR? ===<br />
What sets OpenBOR apart is how we define its scope. Some engines concentrate on a particular genre. Role-playing games. One-on-one fighters. Shoot-’em-ups. Real-time strategy. Puzzle games. Others attempt to support every technical medium, leaving developers to build most game-specific functionality themselves. Both are valid approaches. We take a third path by choosing a technical lane rather than a result lane.<br />
<br />
OpenBOR deliberately stays within the simulation and presentation of flat, two-dimensional visual assets in an effectively limitless three-dimensional world. No polygons. No meshes. No skeletal rigs. Just raster graphics moving through three axes. Within that foundation, virtually any sprite powered concept is possible.<br />
<br />
That focus lets us concentrate our development resources on making OpenBOR the most capable, efficient, and complete engine possible for its chosen medium. Asset handling, controls, movement, gravity, collision, combat, blocking, grabbing, throwing, artificial intelligence, cameras, level trees, audio, menus, HUDs, saving, and local multiplayer are fully integrated and ready to use. Creators do not need to build these foundations or assemble them from third-party plugins before they can begin making a game.<br />
<br />
We then layer beat ’em up-oriented behavior over those systems as the default starting point. Characters can move, fight, react, navigate depth, cooperate, and progress through levels as soon as creators supply the necessary assets and configuration. Those defaults can put a functional game on screen within hours, though they do not dictate what the finished game must become.<br />
<br />
The same engine objects, properties, and low-level primitives remain exposed through configuration and script. Creators can inspect runtime state, customize selected behavior, replace complete subsystems, or combine the primitives into something we never anticipated. Platformers, shooters, role-playing games, puzzle games, and other designs can all operate within the same technical model.<br />
<br />
Staying within a technical lane therefore allows us to make OpenBOR more complete without making it less versatile. Native functionality provides a high starting point, not a boundary. We are not trying to make an engine that does everything. We are working to make the most complete, efficient, and open-ended engine possible for the medium we have chosen.<br />
* '''Complete native gameplay''' - Controls, movement, gravity, level trees, platforms, combat, blocking, grabbing, throwing, artificial intelligence, cameras, audio, menus, HUDs, and saving work without custom code.<br />
* '''[[Script Overview|Engine-wide scripting]]''' - Object APIs and [[:Category:Script Events|more than 70 event hooks]] expose input, animation, movement, collision, damage, spawning, audio, drawing, and other runtime systems for inspection, modification, or replacement.<br />
* '''[[Time|High-resolution simulation]]''' - The configurable logical clock runs at 200 Hz by default and remains independent of display updates.<br />
* '''[[Geometry Overview|Three-dimensional sprite worlds]]''' - Floating-point X, Y, and Z geometry provides subpixel movement, terrain, altitude, and depth sorting.<br />
* '''[[Collision|Declarative combat collision]]''' - Indexed three-dimensional attack and body boxes carry damage, reaction, motion, status, and presentation behavior.<br />
* '''[[Factions|Composable relationships]]''' - Four independent 52-bit faction masks provide hardware-speed membership, hostility, direct-damage, and indirect-damage rules.<br />
* '''[[Subscreens|Recursive graphics composition]]''' - Script-created subscreens support nested rendering, layer capture, transformations, masks, split screens, and feedback effects.<br />
* '''[[Runtime Script Compilation|Runtime metaprogramming]]''' - Modules can load and combine source files, compile them into independently owned programs, retain persistent state, execute them repeatedly, and replace them during play.<br />
* '''Optimized performance''' - Native systems, high-frequency simulation, and script integration are engineered to maintain steady frame rates and butter-smooth motion with dozens or hundreds of active objects.<br />
<br />
== Getting Started ==<br />
<br />
'''[https://www.chronocrash.com/forum/resources/openbor.1/ Download OpenBOR]''' | '''[https://www.chronocrash.com/forum/resources/categories/samples-and-tutorials.5/?prefix_id=3 Start Building]''' | '''[[:Category:Openbor|Browse the Reference]]''' | '''[https://chronocrash.com Visit the Community]''' | '''[https://github.com/DCurrent/openbor View the Source]'''<br />
<br />
This wiki is the comprehensive technical reference for OpenBOR, but please note it is not intended as a walk-through. For more in-depth instruction, consult the tutorials and guides available through the [https://chronocrash.com/forum ChronoCrash community].<br />
<br />
=== Guides and Resources ===<br />
<br />
* [[OpenBOR Overview]] – General overview of OpenBOR functionality and runtime layout.<br />
* [[:Category:Openbor|OpenBOR Hub]] – Main jumping off point for categories and individual wiki articles.<br />
* [[:Category:OpenBOR Index|OpenBOR Index]] – Simple index of OpenBOR commands, settings, and functions.<br />
* [[Legacy Manual]] – Archival monolithic manual.<br />
* [https://chronocrash.com/ ChronoCrash] – OpenBOR’s home community, including its help forum, downloadable games, and in-depth tutorials.<br />
* [https://github.com/DCurrent/openbor OpenBOR Repository] – Public-facing OpenBOR code base.<br />
<br />
== Development Environment ==<br />
<br />
=== Essential Tools ===<br />
<br />
The following tools are needed to begin building games with OpenBOR. You will need a [https://chronocrash.com/forum ChronoCrash community] account to download some resources.<br />
<br />
* [https://www.chronocrash.com/forum/resources/categories/engine.3/ OpenBOR engine executable] – The latest stable engine release.<br />
* '''[https://www.chronocrash.com/forum/resources/neo-edit-pack.2/ Edit Pack]''' – Tools for packing and unpacking OpenBOR game modules.<br />
* '''Development environment''' – OpenBOR uses a combination of text files and optional script files to configure game functionality. Any text editor may be used. [https://code.visualstudio.com/ Visual Studio Code] is recommended, together with [https://github.com Git] or another version-control system for managing project files.<br />
* '''Graphics software''' – Any graphics-editing application capable of exporting <code>.png</code> images. [https://www.adobe.com Adobe Photoshop] or [https://www.gimp.org/ GIMP] are recommended.<br />
* '''Audio software''' – An audio-editing application capable of exporting <code>.wav</code> files for sound effects and, optionally, <code>.ogg</code> files for music. [https://www.adobe.com/products/audition.html Adobe Audition] or [https://www.audacityteam.org/ Audacity] are recommended.<br />
<br />
=== Optional Tools ===<br />
<br />
These tools are optional but highly recommended.<br />
<br />
* '''[https://www.chronocrash.com/forum/resources/chronocrash-modders-tools.139/ ChronoCrash Modders Tools (CMT)]''' – Visual editing application for building OpenBOR games.<br />
* '''[https://www.chronocrash.com/forum/resources/palapply.15/ PalApply]''' – Applies a palette to one or more images and exports optimized <code>.png</code> files ready for use with OpenBOR.<br />
<br />
== What Open Source Means ==<br />
Because the term has caused confusion and disputes in the past, it is important to clarify what open source means in the context of OpenBOR.<br />
<br />
OpenBOR’s existing codebase is available under a permissive [https://github.com/DCurrent/openbor/blob/master/LICENSE BSD-derived license]. '''Creators may use the engine to make, license, and sell games and other content they rightfully own.''' The OpenBOR license does not claim or control that content.<br />
<br />
Open source does not mean a free-for-all. It provides no implied permission to modify or redistribute another creator’s work without consent. The license also permits binary distribution without requiring source disclosure - it does not compel the team to release existing or future source code, and by extension it does not entitle anyone to the source code of closed-source extensions or obligate the development team to release it. The public repository is provided and maintained as a voluntary act of good faith, not as an obligation imposed by the license.<br />
<br />
The OpenBOR development team may produce proprietary features, such as encrypted pack handling, and license them separately at its discretion.</div>Dcurrenthttps://chronocrash.com/openbor/wiki/index.php?title=Main_Page&diff=1087Main Page2026-08-25T17:10:36Z<p>Dcurrent: /* Why OpenBOR? */</p>
<hr />
<div>== Introduction ==<br />
<br />
=== What is OpenBOR? ===<br />
OpenBOR is a royalty-free, open-source engine for sprite-based games. It combines a complete native game framework - including controls, movement, combat, artificial intelligence, levels, audio, menus, saving, and local multiplayer - with an integrated C-like scripting language that can extend or replace nearly every system.<br />
<br />
OpenBOR specializes in side-scrolling action games such as Double Dragon and Streets of Rage, but its three-dimensional game world, configurable simulation, declarative object system, and scriptable graphics pipeline also support platformers, shooters, role-playing games, puzzle games, and other genres.<br />
<br />
Beginners can build complete games primarily from assets and configuration. Advanced creators can manipulate engine objects, replace native behavior, construct rendering pipelines, and even compile new script programs while a module is running.<br />
<br />
=== Why OpenBOR? ===<br />
What sets OpenBOR apart is how we define its scope. Some engines concentrate on a particular genre. Role-playing games. One-on-one fighters. Shoot-’em-ups. Real-time strategy. Puzzle games. Others attempt to support every technical medium, leaving developers to build most game-specific functionality themselves. Both are valid approaches. We take a third path by choosing a technical lane rather than a result lane.<br />
<br />
OpenBOR deliberately stays within the simulation and presentation of flat, two-dimensional visual assets in an effectively limitless three-dimensional world. No polygons. No meshes. No skeletal rigs. Just raster graphics moving through three axes. Those choices limit how an OpenBOR world is represented, not what creators can produce within it.<br />
<br />
That focus lets us concentrate our development resources on making OpenBOR the most capable, efficient, and complete engine possible for its chosen medium. Asset handling, controls, movement, gravity, collision, combat, blocking, grabbing, throwing, artificial intelligence, cameras, level trees, audio, menus, HUDs, saving, and local multiplayer are fully integrated and ready to use. Creators do not need to build these foundations or assemble them from third-party plugins before they can begin making a game.<br />
<br />
We then layer beat ’em up-oriented behavior over those systems as the default starting point. Characters can move, fight, react, navigate depth, cooperate, and progress through levels as soon as creators supply the necessary assets and configuration. Those defaults can put a functional game on screen within hours, though they do not dictate what the finished game must become.<br />
<br />
The same engine objects, properties, and low-level primitives remain exposed through configuration and script. Creators can inspect runtime state, customize selected behavior, replace complete subsystems, or combine the primitives into something we never anticipated. Platformers, shooters, role-playing games, puzzle games, and other designs can all operate within the same technical model.<br />
<br />
Staying within a technical lane therefore allows us to make OpenBOR more complete without making it less versatile. Native functionality provides a high starting point, not a boundary. We are not trying to make an engine that does everything. We are working to make the most complete, efficient, and open-ended engine possible for the medium we have chosen.<br />
* '''Complete native gameplay''' - Controls, movement, gravity, level trees, platforms, combat, blocking, grabbing, throwing, artificial intelligence, cameras, audio, menus, HUDs, and saving work without custom code.<br />
* '''[[Script Overview|Engine-wide scripting]]''' - Object APIs and [[:Category:Script Events|more than 70 event hooks]] expose input, animation, movement, collision, damage, spawning, audio, drawing, and other runtime systems for inspection, modification, or replacement.<br />
* '''[[Time|High-resolution simulation]]''' - The configurable logical clock runs at 200 Hz by default and remains independent of display updates.<br />
* '''[[Geometry Overview|Three-dimensional sprite worlds]]''' - Floating-point X, Y, and Z geometry provides subpixel movement, terrain, altitude, and depth sorting.<br />
* '''[[Collision|Declarative combat collision]]''' - Indexed three-dimensional attack and body boxes carry damage, reaction, motion, status, and presentation behavior.<br />
* '''[[Factions|Composable relationships]]''' - Four independent 52-bit faction masks provide hardware-speed membership, hostility, direct-damage, and indirect-damage rules.<br />
* '''[[Subscreens|Recursive graphics composition]]''' - Script-created subscreens support nested rendering, layer capture, transformations, masks, split screens, and feedback effects.<br />
* '''[[Runtime Script Compilation|Runtime metaprogramming]]''' - Modules can load and combine source files, compile them into independently owned programs, retain persistent state, execute them repeatedly, and replace them during play.<br />
* '''Optimized performance''' - Native systems, high-frequency simulation, and script integration are engineered to maintain steady frame rates and butter-smooth motion with dozens or hundreds of active objects.<br />
<br />
== Getting Started ==<br />
<br />
'''[https://www.chronocrash.com/forum/resources/openbor.1/ Download OpenBOR]''' | '''[https://www.chronocrash.com/forum/resources/categories/samples-and-tutorials.5/?prefix_id=3 Start Building]''' | '''[[:Category:Openbor|Browse the Reference]]''' | '''[https://chronocrash.com Visit the Community]''' | '''[https://github.com/DCurrent/openbor View the Source]'''<br />
<br />
This wiki is the comprehensive technical reference for OpenBOR, but please note it is not intended as a walk-through. For more in-depth instruction, consult the tutorials and guides available through the [https://chronocrash.com/forum ChronoCrash community].<br />
<br />
=== Guides and Resources ===<br />
<br />
* [[OpenBOR Overview]] – General overview of OpenBOR functionality and runtime layout.<br />
* [[:Category:Openbor|OpenBOR Hub]] – Main jumping off point for categories and individual wiki articles.<br />
* [[:Category:OpenBOR Index|OpenBOR Index]] – Simple index of OpenBOR commands, settings, and functions.<br />
* [[Legacy Manual]] – Archival monolithic manual.<br />
* [https://chronocrash.com/ ChronoCrash] – OpenBOR’s home community, including its help forum, downloadable games, and in-depth tutorials.<br />
* [https://github.com/DCurrent/openbor OpenBOR Repository] – Public-facing OpenBOR code base.<br />
<br />
== Development Environment ==<br />
<br />
=== Essential Tools ===<br />
<br />
The following tools are needed to begin building games with OpenBOR. You will need a [https://chronocrash.com/forum ChronoCrash community] account to download some resources.<br />
<br />
* [https://www.chronocrash.com/forum/resources/categories/engine.3/ OpenBOR engine executable] – The latest stable engine release.<br />
* '''[https://www.chronocrash.com/forum/resources/neo-edit-pack.2/ Edit Pack]''' – Tools for packing and unpacking OpenBOR game modules.<br />
* '''Development environment''' – OpenBOR uses a combination of text files and optional script files to configure game functionality. Any text editor may be used. [https://code.visualstudio.com/ Visual Studio Code] is recommended, together with [https://github.com Git] or another version-control system for managing project files.<br />
* '''Graphics software''' – Any graphics-editing application capable of exporting <code>.png</code> images. [https://www.adobe.com Adobe Photoshop] or [https://www.gimp.org/ GIMP] are recommended.<br />
* '''Audio software''' – An audio-editing application capable of exporting <code>.wav</code> files for sound effects and, optionally, <code>.ogg</code> files for music. [https://www.adobe.com/products/audition.html Adobe Audition] or [https://www.audacityteam.org/ Audacity] are recommended.<br />
<br />
=== Optional Tools ===<br />
<br />
These tools are optional but highly recommended.<br />
<br />
* '''[https://www.chronocrash.com/forum/resources/chronocrash-modders-tools.139/ ChronoCrash Modders Tools (CMT)]''' – Visual editing application for building OpenBOR games.<br />
* '''[https://www.chronocrash.com/forum/resources/palapply.15/ PalApply]''' – Applies a palette to one or more images and exports optimized <code>.png</code> files ready for use with OpenBOR.<br />
<br />
== What Open Source Means ==<br />
Because the term has caused confusion and disputes in the past, it is important to clarify what open source means in the context of OpenBOR.<br />
<br />
OpenBOR’s existing codebase is available under a permissive [https://github.com/DCurrent/openbor/blob/master/LICENSE BSD-derived license]. '''Creators may use the engine to make, license, and sell games and other content they rightfully own.''' The OpenBOR license does not claim or control that content.<br />
<br />
Open source does not mean a free-for-all. It provides no implied permission to modify or redistribute another creator’s work without consent. The license also permits binary distribution without requiring source disclosure - it does not compel the team to release existing or future source code, and by extension it does not entitle anyone to the source code of closed-source extensions or obligate the development team to release it. The public repository is provided and maintained as a voluntary act of good faith, not as an obligation imposed by the license.<br />
<br />
The OpenBOR development team may produce proprietary features, such as encrypted pack handling, and license them separately at its discretion.</div>Dcurrenthttps://chronocrash.com/openbor/wiki/index.php?title=Collision&diff=1086Collision2026-08-25T16:32:16Z<p>Dcurrent: /* Multiple Boxes */</p>
<hr />
<div>Collision boxes tell OpenBOR (or any other game engine) what portions of an entity are able to hit or get hit and what areas of a level are walls or platforms. In OpenBOR these boxes are geometric cubes the engine continuously compares to each other – whenever two or more cubes overlap, that’s a collision and the engine will react accordingly.<br />
<br />
Depending on the type of collision box, it will have other properties that tell the engine how to handle the collision event. This article focuses on Attack (hitting with attacks) and Body (Receiving attacks and taking up space). Walls and platforms work on a similar principal and are covered in level design.<br />
<br />
== Multiple Boxes ==<br />
<br />
OpenBOR supports multiple collision boxes per frame, up to 64 of each type. To define a second box of any type, add <code>collision.index {index}</code> with your desired index and then define a set of properties for the next box. You may use any integer value from <code>0 - 63</code> for <code>{index}</code>. All subsequent collision box properties below <code>collision.index {index}</code> now act on the new index.<br />
<br />
You can repeat this process to add a third box, a fourth box, and so on. To adjust or disable the boxes, again use <code>collision.index {index}</code> to define which box you wish to act on, then disable or adjust the box properties as you would a single occurrence.<br />
<br />
When two or more attack boxes overlap a body box or body boxes, OpenBOR will acknowledge a single collision with the lowest index attack and body boxes taking priority.<br />
<br />
'''Tip:''' Don’t get carried away with multiple boxes. Collision boxes are meant to describe practical contact areas, not trace literal sprite pixels. Even high precision versus fighters like ''Street Fighter'' and ''King of Fighters'' typically use only two or three body boxes and one attack box. Beat em’ ups and action games almost invariably use only one of each outside of edge cases.<br />
<br />
Take the following two examples. The first is an unfortunately real amateur design with impressive-looking but needlessly wasteful boxes. This is not precise collision – it is a pointless flex. In game, it will likely feel janky and inconsistent.<br />
[[File:Collision bad.webp|none|frame|Eight times the work - half the precision.]]<br />
Now observe this design – a professional example straight from Capcom’s ''Capcom vs. SNK'' series. It uses only the minimum needed: broad, readable body coverage and a clear attack area. That is not just more optimal – it is mechanically stronger in play.<br />
[[File:Collision cvs a.webp|none|frame|The pros know.]]<br />
<br />
== Attack ==<br />
<br />
Attacks hit and presumably cause damage to other entities. To define an attack, add the necessary attack commands from list below immediately before the frame. In most cases you only need the basic dimensions and damage value. The other attack properties are optional and most are disabled by default.<br />
<br />
Once defined, an attack remains active throughout remainder of the animation unless you redefine it. To disable an attack, add <code>attack 0</code> or <code>attack none</code> before a frame.<br />
<br />
=== Command List ===<br />
<br />
{| class="wikitable"<br />
|-<br />
! Command<br />
! Default<br />
! Description<br />
|-<br />
| attack.block.cost<br />
| 0<br />
| Amount attack removes from target’s ''guardpoints'' when blocked.<br />
|-<br />
| attack.block.penetrate<br />
| 0<br />
| If this meets or exceeds target’s block threshold, target cannot block attack.<br />
|-<br />
| attack.counter<br />
| 0<br />
| If 1+, this attack treats target’s attack boxes as body boxes. If both attacks have counter value, highest value has priority.<br />
|-<br />
|attack.coordinates<br />
|0 0 0 0 0 0<br />
|Shortcut for setting all basic coordinates in a single line: <code>x, y, width, height, depth background, depth foreground</code>. <br />
'''Note:''' All <code>0</code> disables the collision box. If any other values are defined and both z depth values are <code>0</code> or undefined, they will be replaced with a default value of <code>''grabdistance'' setting / 3 + 1</code>. Assuming the [[Grabdistance]] default of <code>36</code>, this gives the box a depth of 13 pixels in each direction.<br />
|-<br />
| attack.damage.force<br />
| 0<br />
| Value deducted from target’s hit points.<br />
|-<br />
| attack.damage.land.force<br />
| 0<br />
| If attack causes a fall, value deducted from target’s hit points on landing.<br />
|-<br />
| attack.damage.land.mode<br />
| 0<br />
| If attack causes knockdown, target’s projectile status and landing ability. Projectile status has no effect if target’s fall animations do not have an attack box.<br />
* <code>0</code> – Normal fall. Target’s attack boxes are disabled until landing.<br />
* <code>1</code> – Target’s attack boxes are enabled in projectile mode until landing, meaning target will hit its allies.<br />
* <code>2</code> – Same as 1. Additionally, if player controlled targets have LAND animation available, they may play it on landing and nullify land force by holding Up + Jump.<br />
|-<br />
| attack.damage.lethal.disable<br />
| 0<br />
| If true, attack cannot reduce target’s hit points below 1.<br />
|-<br />
| attack.damage.recursive.force<br />
| 0<br />
| Amount deducted from target’s hitpoints on each recursive tick. See [https://chronocrash.com/obor/wiki/recursive-damage/ Recursive Damage].<br />
|-<br />
| attack.damage.recursive.index<br />
| 0<br />
| Index ID applied to recursive damage. See [https://chronocrash.com/obor/wiki/recursive-damage/ Recursive Damage].<br />
|-<br />
| attack.damage.recursive.mode<br />
| 0<br />
| How recursive damage applies to target’s hit points or magic points. See [https://chronocrash.com/obor/wiki/recursive-damage/ Recursive Damage].<br />
|-<br />
| attack.damage.recursive.tag<br />
| 0<br />
| Creator defined value ignored by native engine logic. See [https://chronocrash.com/obor/wiki/recursive-damage/ Recursive Damage].<br />
|-<br />
| attack.damage.recursive.time<br />
| 0<br />
| How long in [[Time#Elapsed Time 2|elapsed time]] the recursive damage effect will last. See [https://chronocrash.com/obor/wiki/recursive-damage/ Recursive Damage].<br />
|-<br />
| attack.damage.recursive.rate<br />
| 0<br />
| How long in [[Time#Elapsed Time 2|elapsed time]] between each tick of recursive damage. See [https://chronocrash.com/obor/wiki/recursive-damage/ Recursive Damage].<br />
|-<br />
| attack.damage.steal<br />
| 0<br />
| If true, <code> attack.damage.force </code> is added to attacking entity’s hit points.<br />
|-<br />
| attack.damage.type<br />
| 1<br />
| Attacking type. Works with target’s defense values and reacting animations. Accepts following values:<br />
* Any <code>1</code>+ number. For legacy compatibility, attacks are NOT 0 indexed. If you provide a value of <code>0</code>, <code>1</code> is used instead.<br />
* <code>Blast</code><br />
* <code>Burn</code><br />
* <code>Freeze</code><br />
* <code>Shock</code><br />
* <code>Steal</code><br />
See [[Attack Type|Attack Types]] for details.<br />
|-<br />
| attack.effect.block.flash.model<br />
| None<br />
| Name of model to spawn when target blocks attack.<br />
|-<br />
| attack.effect.block.sound.path<br />
| None<br />
| Path to sound file that plays when target blocks attack.<br />
|-<br />
| attack.effect.hit.flash.layer.adjust<br />
| 0<br />
| Added to global layer adjustment of flash spawn drawing layer. See [[Hit Effects]].<br />
|-<br />
| attack.effect.hit.flash.layer.source<br />
| 0<br />
| Added to global hit flash layer source value for controlling source of flash spawn drawing layer. See [[Hit Effects]].<br />
|-<br />
| attack.effect.hit.flash.model<br />
| None<br />
| Name of model to spawn when attack hits target. If undefined, the global flash model spawns.<br />
|-<br />
| attack.effect.hit.flash.disable<br />
| 0<br />
| If true, no model spawns when attack hits target.<br />
|-<br />
| attack.effect.hit.sound.path<br />
| None<br />
| Path to sound file that plays when attack hits target.<br />
|-<br />
| attack.ground.mode<br />
| 0<br />
| Ability to hit fallen targets on the ground.<br />
* <code>0</code> - Attack cannot hit lying targets.<br />
* <code>1</code> - Attack can hit lying targets.<br />
* <code>2</code> - Attack only hits lying targets.<br />
|-<br />
| collision.index<br />
| 0<br />
| Used for multiple attack boxes on one animation frame. 0 is the first attack box. 1 is the second, and so on. Place this immediately before other properties to have them act on that index. See ''multiple collision boxes'' for details.<br />
|-<br />
| attack.map.index<br />
| 0<br />
|<br />
* If <code>1+</code>, target entity switches to this palette index. For example, if hit by <code>attack.map.index 3</code>, the target switches to palette <code>3</code> if available.<br />
* If <code>-1</code>, target applies its freeze palette.<br />
<br />
You can also use one of following named indexes. If the defending target has a matching named palette index defined, it will apply that palette index.<br />
<br />
* <code>burn</code><br />
* <code>freeze</code><br />
* <code>ko</code><br />
* <code>shock</code><br />
|-<br />
| attack.map.time<br />
| 0<br />
| [[Time#Elapsed Time 2|Elapsed time]] to maintain <code>attack.map.index</code> effect. Target reverts to previous palette afterward.<br />
|-<br />
| attack.position.x<br />
| 0<br />
| [[Geometry Overview|X position]] of attack box, starting from far left of image. Positive integers move right, negative moves left.<br />
|-<br />
| attack.position.y<br />
| 0<br />
| [[Geometry Overview|Y position]] of attack box, starting from far top image. Positive integers move down, negative moves up.<br />
|-<br />
| attack.reaction.fall.force<br />
| 0<br />
| Amount deducted from target’s ''knockdowncount''. If this value is <code>1+</code> and target’s ''knockdowncount'' is <code>0</code>, target is knocked down. Note the knock down check is made immediately after deduction, so if the target has a knockdowncount of <code>1</code> and is hit attack with <code>attack.reaction.fall.force 1</code>, the target falls.<br />
<br />'''Note:''' Default ''knockdowncount'' is <code>0</code>, so unless the target is set up with a specific ''knockdowncount'' or some other means to resist falling, setting this value to any causes knockdown.<br />
|-<br />
| attack.reaction.fall.velocity.x<br />
| 1.2<br />
| [[Geometry Overview|X axis]] toss velocity applied to target if attack knocks it down.<br />
|-<br />
| attack.reaction.fall.velocity.y<br />
| 3.0<br />
| [[Geometry Overview|Y axis]] toss velocity applied to target if attack knocks it down.<br />
|-<br />
| attack.reaction.fall.velocity.z<br />
| 0.0<br />
| [[Geometry Overview|Z axis]] toss velocity applied to target if attack knocks it down.<br />
|-<br />
| attack.reaction.freeze.mode<br />
| 0<br />
| Freeze effect.<br /><br />
* <code>0</code> – No freeze effect.<br />
<br />
* <code>1</code> – Target freezes in place.<br />
|-<br />
| attack.reaction.freeze.time<br />
| 0<br />
| [[Time#Elapsed Time 2|Elapsed time]] to maintain <code>attack.reaction.freeze.mode</code> effect.<br />
|-<br />
| attack.reaction.invincible.time<br />
| 0<br />
| [[Time#Elapsed Time 2|Elapsed time]] target is invincible to subsequent hits.<br />
<br /><br />
'''Note:''' <code>0</code> is allowed and is the default property value. However, the engine will substitute a 0 value with <code>40</code> when applying the invincibility time. The legacy ''fastattack'' command works by setting this property to <code>10</code>.<br />
|-<br />
| attack.reaction.pain.disable<br />
| 0<br />
| If true, target does not play a reaction animation when hit by attack.<br />
|-<br />
| attack.reaction.pause.time<br />
| 0<br />
| [[Time#Elapsed Time 2|Elapsed time]] target and attacker pause (freeze) when attack hits.<br />
|-<br />
| attack.reaction.reposition.direction<br />
| None<br />
| Force target to face specific direction when attack hits.<br /><br />
* <code>Left</code> – Target faces left.<br />
* <code>Opposite</code> – Target faces opposite direction of attacker.<br />
* <code>None</code> – No direction adjustment.<br />
* <code>Same</code> – Target faces same direction as attacker.<br />
* <code>Right</code> – Target faces right.<br />
* <code>Toward</code> – Face toward attacker position.<br />
* <code>Away</code> – Face away from attacker position.<br />
|-<br />
| attack.reaction.reposition.distance<br />
| 0<br />
| Horizontal distance between attacker and target when applying <code>attack.reaction.reposition.mode</code>.<br />
|-<br />
| attack.reaction.reposition.mode<br />
| 0<br />
| Horizontal position adjustment when attack hits and does not knock down.<br />
* <code>0</code> – None.<br />
* <code>1</code> - Target moves to attacker.<br />
* <code>2</code> - Target and attacker move to each other, splitting distance.<br />
|-<br />
| attack.seal.cost<br />
| 0<br />
| If <code>1+</code>, this is maximum allowed MP cost target for target specials. For example, if target is hit with seal <code>10</code>, the target may only use specials that cost <code>10</code> MP or less each.<br />
|-<br />
| attack.seal.time<br />
| 0<br />
| [[Time#Elapsed Time 2|Elapsed time]] to apply <code>attack.seal.cost</code>.<br />
|-<br />
| attack.size.x<br />
| 0<br />
| [[Geometry Overview|X size]] in pixels, moving right from <code>attack.position.x</code>.<br />
|-<br />
| attack.size.y<br />
| 0<br />
| [[Geometry Overview|Y size]] in pixels, moving down from <code>attack.position.y</code>.<br />
|-<br />
| attack.size.z.background<br />
| ''grabdistance'' setting / 3 + 1<br />
| [[Geometry Overview|Z size]] in pixels, moving further from player’s viewpoint from entity position.<br />
'''Note:''' For legacy compatibility, it is impossible to set a <code>0</code> value using native text. If you do, it is replaced with the default value.<br />
|-<br />
| attack.size.z.foreground<br />
| ''grabdistance'' setting / 3 + 1<br />
| [[Geometry Overview|Z size]] in pixels, moving toward player’s viewpoint from entity position.<br />'''Note:''' For legacy compatibility, it is impossible to set a <code>0</code> value using native text. If you do, it is replaced with the default value.<br />
|-<br />
| attack.staydown.rise.time<br />
| 0<br />
| [[Time#Elapsed Time 2|Elapsed time]] added to target’s ''risetime'' if knocked down.<br />
|-<br />
| attack.staydown.attack.time<br />
| 0<br />
| [[Time#Elapsed Time 2|Elapsed time]] before target can use its RISEATTACK animation if knocked down.<br />
'''Note:''' Normally, RISEATTACK is available immediately after a knockdown.<br />
|-<br />
| attack.tag<br />
| 0<br />
| Creator defined integer ignored by engine logic. Note: Subject to removal on completion of meta_data feature.<br />
|}<br />
<br />
=== Example ===<br />
<br />
==== Single ====<br />
<br />
This example defines a single attack box that knocks down and does 10 points of damage, then closes the box on the subsequent frame. Notice only the necessary properties are defined. Order is irrelevant.<br />
<br />
<pre>attack.position.x 58<br />
attack.position.y 90<br />
attack.size.x 92<br />
attack.size.y 25<br />
attack.reaction.fall.force 1<br />
attack.reaction.pause.time 10<br />
attack.damage.force 15<br />
attack.effect.hit.flash.model flash_fatal_fury<br />
<br />
frame data/chars/terry/atk_j_side_kick_c_1.png<br />
<br />
attack none<br />
<br />
frame data/chars/terry/atk_j_side_kick_c_1.png</pre><br />
[[File:Fatal fury terry collision atk 2.webp|none|frame|Terry Bogard attacks with a typical hit box.]]<br />
<br />
==== Multiple ====<br />
<br />
This example takes advantage of multiple boxes to place a more accurate attack area around Ryu’s leg. The second box has an index of 1. Since we didn’t bother to define an index for the first box, it gets a default index of 0. Unless the target is really close, we want the contact area (and thus flash spawns) to be around Ryu’s foot, so we let it have the default index of <code>0</code> to give it higher priority over <code>1</code>. The attack definitions are otherwise identical to single boxes. On the following frame, we close both the attack boxes.<br />
<br />
<pre>attack.damage.force 12<br />
attack.effect.hit.flash.model flash_fatal_fury<br />
attack.reaction.fall.force 1<br />
attack.reaction.pause.time 12<br />
attack.position.x 138<br />
attack.position.y 44<br />
attack.size.x 32<br />
attack.size.y 26<br />
<br />
collision.index 1<br />
<br />
attack.damage.force 12<br />
attack.effect.hit.flash.model flash_fatal_fury<br />
attack.reaction.fall.force 1<br />
attack.reaction.pause.time 12<br />
attack.position.x 112<br />
attack.position.y 61<br />
attack.size.x 33<br />
attack.size.y 25<br />
<br />
frame data/chars/ryu/20_3.png<br />
<br />
collision.index 0<br />
attack none<br />
<br />
collision.index 1<br />
attack none<br />
<br />
frame data/chars/ryu/20_4.png</pre><br />
[[File:Fatal fury ryu collision atk 0-2.webp|none|frame|Two boxes are better than one?]]<br />
[[File:Fatal fury ryu collision atk 1-1.webp|none|frame|Take it on the chin!]]<br />
'''Tip:''' As noted above, it is usually an anti-pattern to try and trace collision over the sprite too closely - the multiple box example here is just to demonstrate the principal. In most cases, best practice is to add a body box for head and torso rather than more attack boxes.<br />
<br />
== Body ==<br />
<br />
Body boxes detect incoming attacks. If an entity doesn’t have a body box on a given frame, it can’t detect attacks and is effectively invincible from conventional hits. Defining a body box is nearly identical to attack boxes, except body boxes are far simpler as they have fewer properties.<br />
<br />
To end a body box, add <code>bbox 0</code> or <code>bbox none</code> before a frame.<br />
<br />
{| class="wikitable"<br />
|-<br />
! Command<br />
! Default<br />
! Description<br />
|-<br />
| bbox.effect.hit.flash.layer.adjust<br />
| 0<br />
| Added to global layer adjustment of flash spawn drawing layer. See [https://chronocrash.com/obor/wiki/hit-effects-flash/ Hit Effects].<br />
|-<br />
| bbox.effect.hit.flash.layer.source<br />
| 0<br />
| Added to global hit flash layer source value for controlling source of flash spawn drawing layer. See [https://chronocrash.com/obor/wiki/hit-effects-flash/ Hit Effects].<br />
|-<br />
| bbox.defense<br />
| None<br />
| At time of writing, no function. This is a feature in progress that will allow setting up defense properties for individual body boxes.<br />
|-<br />
| bbox.meta_data<br />
| None<br />
| At time of writing, no function. This is an in progress feature to allow unlimited storage of creator defined data.<br />
|-<br />
| bbox.meta_tag<br />
| 0<br />
| Creator defined integer ignored by engine logic. Note: Subject to removal on completion of meta_data feature.<br />
|-<br />
| bbox.position.x<br />
| 0<br />
| [[Geometry Overview|X position]] of body box, starting from far left of image. Positive integers move right, negative moves left.<br />
|-<br />
| bbox.position.y<br />
| 0<br />
| [[Geometry Overview|Y position]] of body box, starting from top of image. Positive integers move down, negative moves up.<br />
|-<br />
| bbox.size.x<br />
| 0<br />
| [[Geometry Overview|X size]] in pixels, moving right from <code>body.position.x</code>.<br />
|-<br />
| bbox.size.y<br />
| 0<br />
| [[Geometry Overview|Y size]] in pixels, moving down from <code>body.position.y</code><br />
|-<br />
| bbox.size.z.background<br />
| 0<br />
| [[Geometry Overview|Z size]] in pixels, moving further from player’s viewpoint from entity position.<br />
|-<br />
| bbox.size.z.foreground<br />
| 0<br />
| [[Geometry Overview|Z size]] in pixels, moving toward player’s viewpoint from entity position.<br />
|}<br />
<br />
=== Example ===<br />
<br />
==== Single ====<br />
<br />
This example defines a single body box to detect hits.<br />
<br />
<pre>bbox.position.x 66<br />
bbox.position.y 49<br />
bbox.size.x 38<br />
bbox.size.y 98</pre><br />
==== Multiple ====<br />
<br />
This example takes advantage of multiple boxes to place a more accurate hit area area area around Ryu. The second box has an index of 1, and the third an index of 2. Since we didn’t bother to define an index for the first box, it gets a default index of 0. Unless the target is really close, we want the contact area (and thus flash spawns) to prioritize Ryu’s head, then body, so we place the lower indexed boxes in order from head to feet. The body definitions are otherwise identical to single boxes.<br />
<br />
<pre>bbox.position.x 78<br />
bbox.position.y 48<br />
bbox.size.x 25<br />
bbox.size.y 21<br />
<br />
collision.index 1<br />
<br />
bbox.position.x 67<br />
bbox.position.y 57<br />
bbox.size.x 35<br />
bbox.size.y 51<br />
<br />
collision.index 2<br />
<br />
bbox.position.x 62<br />
bbox.position.y 103<br />
bbox.size.x 47<br />
bbox.size.y 46<br />
<br />
frame data/chars/ryu/idle_0.png<br />
<br />
collision.index 0<br />
bbox none<br />
<br />
collision.index 1<br />
bbox none<br />
<br />
frame data/chars/ryu/idle_1.png</pre><br />
== Advanced ==<br />
<br />
=== Hit Placement ===<br />
<br />
Each time a collision occurs, OpenBOR records the location and several other data points into a structure called lasthit. This is then used for items like the native flash effects. Lasthit is available as a system variable and as local vars in didhit and takedamage scripts.<br />
<br />
Hit location is the calculated center point where the respective collision boxes overlap on each [[Geometry Overview|Axis]].<br />
[[File:Collision example 3D 0.webp|none|frame|OpenBOR places a flash effect on the centroid by default, but also exposes the coordinates for creator use.]]<br />
<br />
== Legacy Attack ==<br />
Legacy attack boxes use a single attack command with multiple parameters. Additional parameters are available through separate commands we call “Supplements”. Most legacy attack commands sanitize time inputs into cetiseconds, whereas modern commands accept raw [[Time#Elapsed Time 2|elapsed time]] values.<br />
<br />
'''Note:''' Legacy attack commands are depreciated and will not receive further updates.It is highly recommended any new projects utilize the current attack box commands.<br />
<br />
=== Base commands ===<br />
<br />
==== Attack ====<br />
Default legacy attack box. Other than '''{#}''', you cannot omit an optional parameter and use any other parameters rightward. For example, if you want to include a '''{pausetime}''' value, you must also include '''{power}''', '''{block}''', and '''{noflash}'''.<br />
<br />
<pre>attack{#} {x} {y} {right} {down} {damage} {power} {block} {noflash} {pausetime} {z}</pre><br />
* '''{#}''' – See <code>attack.damage.type</code> (numbers only). '''{#}''' is part of the command name, no spaces. As an example, if you wanted an attack type 2, you would write <code>attack2 {x} {y} ...</code>. Optional. If omitted, defaults to 1.<br />
* '''{x}''' – See <code>attack.position.x</code>.<br />
* '''{y}''' – See <code>attack.position.y</code>.<br />
* '''{right}''' – See <code>attack.size.x</code>.<br />
* '''{down}''' – See <code>attack.size.y</code>.<br />
* '''{damage}''' – See <code>attack.damage.force</code>.<br />
* '''{power}''' – Optional. See <code>attack.reaction.fall.force</code>.<br />
* '''{block}''' – Optional. See <code>attack.block.penetrate</code>.<br />
* '''{noflash}''' – Optional. See <code>attack.effect.hit.flash.disable</code>.<br />
* '''{pausetime}''' – Optional. See <code>attack.reaction.pause.time</code>.<br />
* '''{z}''' – Optional. See <code>attack.size.z.1</code> and <code>attack.size.z.2</code>. Legacy Z affects both directions.<br />
<br />
==== Blast ====<br />
Same as '''Attack''' other than following:<br />
<br />
<pre>blast {x} {y} {right} {down} {damage} {block} {noflash} {pausetime} {z} </pre><br />
* <code>attack.damage.type</code> = Blast. Note blast type does nothing on its own and defaults to type 1 reactions.<br />
* <code>attack.reaction.fall.force</code> = 1.<br />
* <code>attack.reaction.fall.velocity.x</code> = is 2.083.<br />
* <code>attack.damage.mode</code> = 1.<br />
<br />
==== Burn ====<br />
Same as '''Attack''' other than the following:<br />
<br />
<pre>Burn {x} {y} {right} {down} {damage} {knockdown} {block} {noflash} {pausetime} {z}</pre><br />
* <code>attack.damage.type</code> = Burn.<br />
<br />
==== shock ====<br />
Same as '''attack#''' other than the following:<br />
<br />
<pre>shock {x} {y} {right} {down} {damage} {knockdown} {block} {noflash} {pausettime} {z} </pre><br />
* <code>attack.damage.type</code> = Shock.<br />
<br />
==== Freeze ====<br />
Same as '''Attack''' other than the following:<br />
<br />
<pre>freeze {x} {y} {right} {down} {damage} {time} {block} {noflash} {pausetime} {z} </pre><br />
* <code>attack.damage.type</code> = Freeze. Note freeze type does nothing on its own and defaults to type 1 reactions.<br />
* <code>attack.reaction.freeze.mode</code> = 1.<br />
* '''{time}''' – Time in centiseconds to remain frozen.<br />
* <code>attack.map.index</code> = 1.<br />
<br />
==== Steal ====<br />
Same as '''Attack''' other than the following:<br />
<br />
<pre>steal {x} {y} {right} {down} {damage} {knockdown} {block} {noflash} {pausetime} {z}</pre><br />
* <code>attack.damage.type</code> = Steal. Note steal type does nothing on its own and defaults to type 1 reactions.<br />
* <code>attack.damage.steal</code> = 1.<br />
<br />
=== Supplements ===<br />
<br />
==== grabin ====<br />
<pre>grabin {type} {distance}</pre><br />
* '''{type}''' – See <code>attack.reposition.mode</code>.<br />
* '''{distance}''' – See <code>attack.reposition.distance</code>.<br />
<br />
==== Fastattack 1 ====<br />
When enabled, applies a static value of <code>attack.reaction.invincible.time 10</code>.<br />
<br />
==== Forcedirection ====<br />
<pre>forcedirection {dir}</pre><br />
* '''{dir}''' – See <code>attack.reposition.direction</code>.<br />
<br />
==== Damageonlanding ====<br />
<pre>damageonlanding {value} {type} </pre><br />
* '''{value}''' – See <code>attack.damage.land.force</code>.<br />
* '''{type}''' – See <code>attack.damage.land.mode</code>.<br />
<br />
==== Dropv ====<br />
<pre>dropv {height} {speedx} {speedz}</pre><br />
* '''{height}''' – See <code>attack.reaction.fall.velocity.y</code>.<br />
* '''{speedx}''' – See <code>attack.reaction.fall.velocity.x</code>.<br />
* '''{speedz}''' – See <code>attack.reaction.fall.velocity.z</code>.<br />
<br />
==== Nokill ====<br />
<pre>nokill {bool}</pre><br />
* '''{bool}''' – See <code>attack.damage.lethal.disable</code>.<br />
<br />
==== stun {int} ====<br />
* {'''int}''' – See <code>attack.reaction.freeze.mode</code>.<br />
<br />
==== Seal ====<br />
<pre>seal {time} {energy} </pre><br />
* '''{time}''' – Time in centiseconds to stay under seal effect.<br />
* '''{energy}''' – See <code>attack.seal.cost</code>.<br />
<br />
==== Forcemap ====<br />
<pre>forcemap {map} {time}</pre><br />
* '''{map}''' – See <code>attack.map.index</code>.<br />
* '''{time}''' – Time in centiseconds to keep forcemap.<br />
<br />
==== Noreflect ====<br />
<pre>noreflect {bi} </pre><br />
'''{bi}''' – See <code>attack.reaction.pain.disable</code>.<br />
<br />
==== Jugglecost ====<br />
<pre>jugglecost {int} </pre><br />
* This command limits juggling ability of the attackbox.<br />
* Juggling means attacking falling opponents (assuming they are vulnerable while falling). It doesn’t matter if the attackbox knocks down or not cause juggling always knock down opponent.<br />
* This command is used in conjunction with ‘jugglepoints’ (see Header Data above).<br />
* The command works like this:<br />
** If attackbox hits opponent whose ‘jugglepoints’ is higher than or equal with ‘jugglecost’, the attack will connect. At this condition, opponent’s ‘jugglepoints’ will be subtracted by that ‘jugglecost’. This drops ‘jugglepoints’ which limits juggling ability. If attackbox hits opponent whose ‘jugglepoints’ is lower than ‘jugglecost’, the attack will not connect. At this condition, opponent’s ‘jugglepoints’ will remain the same.<br />
<br />
==== OTG ====<br />
<pre>OTG {bi}</pre><br />
'''{bi}''' – See <code>attack.ground.mode</code>.<br />
<br />
==== Guardcost ====<br />
<pre>guardcost {int} </pre><br />
'''{int}''' – See <code>attack.block.cost</code>.<br />
<br />
* Defines how much ‘guardpoints’ will be subtracted from opponent if they block this attack.<br />
<br />
==== DOT ====<br />
<pre>DOT {Index} {Time} {Mode} {Force} {Rate} </pre><br />
* '''{index}''' – See <code>attack.damage.recursive.index</code>.<br />
* '''{time}''' – See <code>attack.damage.recursive.time</code>.<br />
* '''{mode}''' – See <code>attack.damage.recursive.mode</code>.<br />
* '''{force}''' – See <code>attack.damage.recursive.force</code>.<br />
* '''{rate}''' – See <code>attack.damage.recursive.rate</code>.<br />
<br />
==== Staydown ====<br />
<pre>staydown {rise} {riseattack} </pre><br />
'''{rise}''' – See <code>attack.staydown.rise.time</code>.<br />
<br />
'''{riseattack}''' – See <code>attack.staydown.attack.time</code>.<br />
<br />
== Legacy Body ==<br />
<br />
Legacy body box commands are nearly identical to legacy attack box commands in format.<br />
<br />
'''Note:''' As with legacy attack commands,legacy body commands are depreciated and will not receive further updates. It is highly recommended any new projects utilize the current body box commands.<br />
<br />
'''body {x} {y} {width} {height} {depth back} {depth front}'''<br />
<br />
* '''{x}''' – See <code>body.position.x</code>.<br />
* '''{y}''' – See <code>body.position.y</code>.<br />
* '''{width}''' – See <code>body.size.x</code>.<br />
* '''{height}''' – See <code>body.size.y</code>.<br />
* '''{depth back}''' – See <code>body.size.depth.back</code>.<br />
* '''{depth front}''' – See <code>body.size.depth.front</code>. If omitted, '''{depth back}''' sets depth in both directions.<br />
<br />
'''bboxz''' '''{depth back} {depth front}''' – See <code>body.size.depth.back</code> and <code>body.size.depth.front</code><br />
<br />
[[Category:Game Mechanics]]<br />
[[Category:Openbor]]</div>Dcurrenthttps://chronocrash.com/openbor/wiki/index.php?title=Main_Page&diff=1085Main Page2026-08-25T03:40:48Z<p>Dcurrent: /* Why OpenBOR? */</p>
<hr />
<div>== Introduction ==<br />
<br />
=== What is OpenBOR? ===<br />
OpenBOR is a royalty-free, open-source engine for sprite-based games. It combines a complete native game framework - including controls, movement, combat, artificial intelligence, levels, audio, menus, saving, and local multiplayer - with an integrated C-like scripting language that can extend or replace nearly every system.<br />
<br />
OpenBOR specializes in side-scrolling action games such as Double Dragon and Streets of Rage, but its three-dimensional game world, configurable simulation, declarative object system, and scriptable graphics pipeline also support platformers, shooters, role-playing games, puzzle games, and other genres.<br />
<br />
Beginners can build complete games primarily from assets and configuration. Advanced creators can manipulate engine objects, replace native behavior, construct rendering pipelines, and even compile new script programs while a module is running.<br />
<br />
=== Why OpenBOR? ===<br />
What sets OpenBOR apart is how far it extends in both directions. Creators do not need to build their own asset handling, controls, movement, artificial intelligence, collision and combat logic, audio playback, or other foundational systems. Everything is integrated and ready to use. Gather the assets and a fully functional game can be running within hours.<br />
<br />
At the opposite extreme, OpenBOR allows ground up construction or reconstruction by exposing low-level primitives and engine objects through configuration and script. Creators can inspect runtime state, customize selected behavior, replace complete subsystems, or build new ones without modifying engine source or depending on third-party plugins. Native functionality is therefore a starting point, not a boundary.<br />
<br />
* '''Complete native gameplay''' - Controls, movement, gravity, level trees, platforms, combat, blocking, grabbing, throwing, artificial intelligence, cameras, audio, menus, HUDs, and saving work without custom code.<br />
* '''[[Script Overview|Engine-wide scripting]]''' - Object APIs and [[:Category:Script Events|more than 70 event hooks]] expose input, animation, movement, collision, damage, spawning, audio, drawing, and other runtime systems for inspection, modification, or replacement.<br />
* '''[[Time|High-resolution simulation]]''' - The configurable logical clock runs at 200 Hz by default and remains independent of display updates.<br />
* '''[[Geometry Overview|Three-dimensional sprite worlds]]''' - Floating-point X, Y, and Z geometry provides subpixel movement, terrain, altitude, and depth sorting.<br />
* '''[[Collision|Declarative combat collision]]''' - Indexed three-dimensional attack and body boxes carry damage, reaction, motion, status, and presentation behavior.<br />
* '''[[Factions|Composable relationships]]''' - Four independent 52-bit faction masks provide hardware-speed membership, hostility, direct-damage, and indirect-damage rules.<br />
* '''[[Subscreens|Recursive graphics composition]]''' - Script-created subscreens support nested rendering, layer capture, transformations, masks, split screens, and feedback effects.<br />
* '''[[Runtime Script Compilation|Runtime metaprogramming]]''' - Modules can load and combine source files, compile them into independently owned programs, retain persistent state, execute them repeatedly, and replace them during play.<br />
* '''Optimized performance''' - Native systems, high-frequency simulation, and script integration are engineered to maintain steady frame rates and butter-smooth motion with dozens or hundreds of active objects.<br />
<br />
== Getting Started ==<br />
<br />
'''[https://www.chronocrash.com/forum/resources/openbor.1/ Download OpenBOR]''' | '''[https://www.chronocrash.com/forum/resources/categories/samples-and-tutorials.5/?prefix_id=3 Start Building]''' | '''[[:Category:Openbor|Browse the Reference]]''' | '''[https://chronocrash.com Visit the Community]''' | '''[https://github.com/DCurrent/openbor View the Source]'''<br />
<br />
This wiki is the comprehensive technical reference for OpenBOR, but please note it is not intended as a walk-through. For more in-depth instruction, consult the tutorials and guides available through the [https://chronocrash.com/forum ChronoCrash community].<br />
<br />
=== Guides and Resources ===<br />
<br />
* [[OpenBOR Overview]] – General overview of OpenBOR functionality and runtime layout.<br />
* [[:Category:Openbor|OpenBOR Hub]] – Main jumping off point for categories and individual wiki articles.<br />
* [[:Category:OpenBOR Index|OpenBOR Index]] – Simple index of OpenBOR commands, settings, and functions.<br />
* [[Legacy Manual]] – Archival monolithic manual.<br />
* [https://chronocrash.com/ ChronoCrash] – OpenBOR’s home community, including its help forum, downloadable games, and in-depth tutorials.<br />
* [https://github.com/DCurrent/openbor OpenBOR Repository] – Public-facing OpenBOR code base.<br />
<br />
== Development Environment ==<br />
<br />
=== Essential Tools ===<br />
<br />
The following tools are needed to begin building games with OpenBOR. You will need a [https://chronocrash.com/forum ChronoCrash community] account to download some resources.<br />
<br />
* [https://www.chronocrash.com/forum/resources/categories/engine.3/ OpenBOR engine executable] – The latest stable engine release.<br />
* '''[https://www.chronocrash.com/forum/resources/neo-edit-pack.2/ Edit Pack]''' – Tools for packing and unpacking OpenBOR game modules.<br />
* '''Development environment''' – OpenBOR uses a combination of text files and optional script files to configure game functionality. Any text editor may be used. [https://code.visualstudio.com/ Visual Studio Code] is recommended, together with [https://github.com Git] or another version-control system for managing project files.<br />
* '''Graphics software''' – Any graphics-editing application capable of exporting <code>.png</code> images. [https://www.adobe.com Adobe Photoshop] or [https://www.gimp.org/ GIMP] are recommended.<br />
* '''Audio software''' – An audio-editing application capable of exporting <code>.wav</code> files for sound effects and, optionally, <code>.ogg</code> files for music. [https://www.adobe.com/products/audition.html Adobe Audition] or [https://www.audacityteam.org/ Audacity] are recommended.<br />
<br />
=== Optional Tools ===<br />
<br />
These tools are optional but highly recommended.<br />
<br />
* '''[https://www.chronocrash.com/forum/resources/chronocrash-modders-tools.139/ ChronoCrash Modders Tools (CMT)]''' – Visual editing application for building OpenBOR games.<br />
* '''[https://www.chronocrash.com/forum/resources/palapply.15/ PalApply]''' – Applies a palette to one or more images and exports optimized <code>.png</code> files ready for use with OpenBOR.<br />
<br />
== What Open Source Means ==<br />
Because the term has caused confusion and disputes in the past, it is important to clarify what open source means in the context of OpenBOR.<br />
<br />
OpenBOR’s existing codebase is available under a permissive [https://github.com/DCurrent/openbor/blob/master/LICENSE BSD-derived license]. '''Creators may use the engine to make, license, and sell games and other content they rightfully own.''' The OpenBOR license does not claim or control that content.<br />
<br />
Open source does not mean a free-for-all. It provides no implied permission to modify or redistribute another creator’s work without consent. The license also permits binary distribution without requiring source disclosure - it does not compel the team to release existing or future source code, and by extension it does not entitle anyone to the source code of closed-source extensions or obligate the development team to release it. The public repository is provided and maintained as a voluntary act of good faith, not as an obligation imposed by the license.<br />
<br />
The OpenBOR development team may produce proprietary features, such as encrypted pack handling, and license them separately at its discretion.</div>Dcurrenthttps://chronocrash.com/openbor/wiki/index.php?title=File_Operations&diff=1084File Operations2026-08-24T05:44:45Z<p>Dcurrent: /* String */</p>
<hr />
<div>OpenBOR supports file CRUD - create, read, update, and delete - through an API called filestream. Scripts can load external files into memory, read structured text, assemble or revise content, save the result to disk, and remove files that are no longer needed. Common uses include custom configuration, persistent game data, generated model or script files, and data exchanged with external tools.<br />
<br />
Despite the name, an OpenBOR filestream is not a continuously open operating-system file. Instead, OpenBOR filestreams use memory-backed buffers. Opening a file loads its contents into memory, after which reading and editing require no additional disk access or filesystem overhead. Scripts may perform any number of operations at memory speed, then explicitly commit the finished buffer to storage with <code>savefilestream()</code>. <br />
<br />
Each filestream maintains two independent locations:<br />
<br />
* '''Buffer end -''' <code>filestreamappend()</code> always writes here.<br />
* '''Read position -''' Line, argument, byte, and position functions operate here.<br />
<br />
Changing the read position does not change where appended data is written.<blockquote>'''Important:''' Memory buffers and external files have separate lifecycles. <code>closefilestream()</code> releases a buffer without deleting its saved file. <code>deletefilestream()</code> removes an external file without releasing any buffer previously loaded from it.</blockquote><br />
<br />
== Lifecycle ==<br />
Creating, reading, or updating a file normally follows four steps:<br />
<br />
# Create an empty stream with <code>createfilestream()</code>, or load an existing file with <code>openfilestream()</code>.<br />
# Read from the current position or append content to the buffer.<br />
# Call <code>savefilestream()</code> when the buffer should be written to disk.<br />
# Call <code>closefilestream()</code> when the buffer is no longer needed.<br />
<br />
Deletion is independent of this handle lifecycle. Pass a filename directly to <code>deletefilestream()</code>; no stream needs to be open.<br />
{| class="wikitable"<br />
!Operation<br />
!Native support<br />
!Method<br />
|-<br />
|Create<br />
|Yes<br />
|Create an empty buffer, append content, then save it under a filename.<br />
|-<br />
|Read<br />
|Yes<br />
|Open a file, then read its current line, arguments, or byte.<br />
|-<br />
|Update<br />
|Append or rewrite<br />
|Open and append to the loaded buffer, or construct a replacement buffer, then save over the previous file.<br />
|-<br />
|Delete<br />
|Yes<br />
|Pass a filename to <code>deletefilestream()</code> to remove a writable external file.<br />
|}<br />
Saving is explicit. Closing an unsaved stream discards its in-memory changes. Deleting a file does not discard a loaded buffer, so saving that buffer later may recreate the file.<br />
<br />
== Handle and Buffer Model ==<br />
The returned filestream handle is a zero-based index into the engine's filestream collection. Internally, each entry contains:<br />
{| class="wikitable"<br />
!Member<br />
!Purpose<br />
|-<br />
|<code>buf</code><br />
|Allocated memory containing the loaded or constructed data.<br />
|-<br />
|<code>size</code><br />
|Current buffer size and append location.<br />
|-<br />
|<code>pos</code><br />
|Current byte position used by read functions.<br />
|}<br />
Closed entries become available for reuse. Once <code>closefilestream()</code> is called, the old handle is invalid and may later identify a different filestream.<br />
<br />
The engine does not clamp filestream handles or manually assigned positions. Use only handles returned by <code>createfilestream()</code> or successful calls to <code>openfilestream()</code>, and never use a handle after closing it.<br />
<br />
== Walk-through ==<br />
<br />
=== Create and Save ===<br />
The following creates a two-line text file:<syntaxhighlight lang="c" line="1"><br />
void filestream_handle = createfilestream();<br />
<br />
filestreamappend(filestream_handle, "name", 1);<br />
filestreamappend(filestream_handle, "Max");<br />
<br />
filestreamappend(filestream_handle, "score", 0);<br />
filestreamappend(filestream_handle, 125000);<br />
<br />
savefilestream(filestream_handle, "profile.txt");<br />
closefilestream(filestream_handle);<br />
</syntaxhighlight>The default save location is the current module's subdirectory under <code>Saves</code>. Text mode adds a final carriage return and line feed, producing:<pre><br />
name Max<br />
score 125000<br />
</pre>In this example, write type <code>1</code> adds a trailing space after <code>name</code>. Write type <code>0</code> begins a new line before <code>score</code> and then adds a trailing space.<br />
<br />
=== Open and Read ===<br />
Pass a nonzero location value to load from the current module's save directory:<syntaxhighlight lang="c" line="1"><br />
void filestream_handle = openfilestream("profile.txt", 1);<br />
<br />
if (filestream_handle >= 0) {<br />
char player_name = getfilestreamargument(filestream_handle, 1, "string");<br />
<br />
filestreamnextline(filestream_handle);<br />
<br />
int player_score = getfilestreamargument(filestream_handle, 1, "int");<br />
<br />
closefilestream(filestream_handle);<br />
}<br />
</syntaxhighlight>The first argument on each line is index <code>0</code>. The example reads index <code>1</code>, returning <code>"Max"</code> from the first line and <code>125000</code> from the second.<br />
<br />
=== Append and Replace ===<br />
Opening a file loads its existing content into the buffer. Appending new content and saving under the same name rewrites the external file with the expanded buffer:<syntaxhighlight lang="c" line="1"><br />
void filestream_handle = openfilestream("profile.txt", 1);<br />
<br />
if (filestream_handle >= 0) {<br />
/*<br />
* Files written by savefilestream() in text mode already<br />
* end with a line break, so begin the next record directly.<br />
*/<br />
filestreamappend(filestream_handle, "unlocks", 1);<br />
filestreamappend(filestream_handle, 3);<br />
<br />
savefilestream(filestream_handle, "profile.txt");<br />
closefilestream(filestream_handle);<br />
}<br />
</syntaxhighlight><code>savefilestream()</code> opens the destination in write mode and replaces its previous contents. Existing data survives only because <code>openfilestream()</code> first copied that data into the memory buffer.<br />
<br />
Filestreams do not provide insertion, replacement, or removal at an arbitrary read position. To modify existing records, read the source and assemble the desired result in another filestream, then save the replacement over the original filename.<br />
<br />
=== Delete ===<br />
Deletion targets the external file by name rather than a filestream handle:<syntaxhighlight lang="c" line="1"><br />
int deleted = deletefilestream("profile.txt");<br />
<br />
if (!deleted) {<br />
log("Could not delete profile.txt.\n");<br />
}<br />
</syntaxhighlight>The default location is the current module's subdirectory under <code>Saves</code>, matching <code>savefilestream()</code>. Supply the same optional pathname used to save a file when deleting from a custom location:<syntaxhighlight lang="c" line="1"><br />
int deleted = deletefilestream(<br />
"profile.txt",<br />
"data/generated/"<br />
);<br />
</syntaxhighlight>Only the external file is removed. If a filestream already contains data loaded from that file, its memory buffer and handle remain valid until <code>closefilestream()</code> is called.<br />
<br />
== Functions ==<br />
<br />
=== closefilestream() ===<br />
<syntaxhighlight lang="c"><br />
closefilestream(filestream_handle);<br />
</syntaxhighlight>Releases the filestream's allocated buffer. The handle becomes invalid and its collection index may be reused by a later create or open operation.<br />
<br />
This function does not save the buffer and does not delete an external file.<br />
<br />
=== createfilestream() ===<br />
<syntaxhighlight lang="c"><br />
int filestream_handle = createfilestream();<br />
</syntaxhighlight>Allocates an empty memory buffer and returns its handle. The initial read position and content size are both <code>0</code>.<br />
<br />
No external file is created until the buffer is passed to <code>savefilestream()</code>.<br />
<br />
=== deletefilestream() ===<br />
<syntaxhighlight lang="c"><br />
int deleted = deletefilestream(filename[, pathname]);<br />
</syntaxhighlight>Deletes a writable external file and returns <code>1</code> when the operating system confirms deletion. A return value of <code>0</code> means the file could not be deleted, including when the file does not exist, the path is incorrect, or the operating system denies access.<br />
<br />
When <code>pathname</code> is omitted, OpenBOR targets the current module's subdirectory under <code>Saves</code>:<syntaxhighlight lang="c"><br />
int deleted = deletefilestream("profile.txt");<br />
</syntaxhighlight>The optional pathname follows the same rules as <code>savefilestream()</code> and is relative to the engine's working directory:<syntaxhighlight lang="c"><br />
int deleted = deletefilestream( "profile.txt", "data/generated/");<br />
</syntaxhighlight>The pathname is joined directly to the filename. Include the final slash or backslash.<br />
<br />
Deletion operates on external files only and cannot remove content from a packfile. It does not accept a filestream handle, release a memory buffer, or invalidate a handle. Saving a still-open buffer to the same filename after successful deletion creates the file again.<br />
<br />
=== filestreamappend() ===<br />
<syntaxhighlight lang="c"><br />
filestreamappend(filestream_handle, value[, write_type[, value_type]]);<br />
</syntaxhighlight>Converts the supplied value to text and appends it at the end of the buffer. The current read position has no effect on the append location.<br />
{| class="wikitable"<br />
!<code>write_type</code><br />
!Behavior<br />
|-<br />
|Omitted, <code>-1</code>, or any value other than <code>0</code> and <code>1</code><br />
|Appends the value without adding a separator.<br />
|-<br />
|<code>0</code><br />
|Adds <code>\r\n</code> before the value, then adds one trailing space after it.<br />
|-<br />
|<code>1</code><br />
|Appends the value followed by one trailing space.<br />
|}<br />
Write type <code>0</code> starts a new line before the supplied value. Using it for the first value in an empty stream therefore creates an initial blank line.<br />
<br />
Passing <code>"byte"</code> as <code>value_type</code> selects the legacy byte append path:<syntaxhighlight lang="c"><br />
filestreamappend(filestream_handle, byte_value, write_type, "byte");<br />
</syntaxhighlight>See [[File Operations#Binary Data|Binary Data]] before using byte mode.<br />
<br />
=== filestreamnextline() ===<br />
<syntaxhighlight lang="c"><br />
filestreamnextline(filestream_handle);<br />
</syntaxhighlight>Advances the read position from its current location to the next non-line-break byte. The function scans to the end of the current line, then skips all consecutive <code>\r</code> and <code>\n</code> characters.<br />
<br />
Multiple empty lines are skipped as one group. At the end of the buffer, the position does not change.<br />
<br />
=== getfilestreamargument() ===<br />
<br />
<syntaxhighlight lang="c"><br />
mixed result = getfilestreamargument(<br />
filestream_handle,<br />
argument_index,<br />
result_type<br />
[, decode_quotes]<br />
);<br />
</syntaxhighlight><br />
<br />
Reads an argument beginning at the current filestream position without advancing the position. Argument indexes are zero-based.<br />
<br />
The optional <code>decode_quotes</code> parameter controls quote handling. Omit it or pass <code>0</code> for legacy whitespace parsing. Pass any nonzero value for modern quote-aware parsing. See [[File Operations#String|String]] for details and examples.<br />
<br />
{| class="wikitable"<br />
! <code>result_type</code><br />
! Return<br />
|-<br />
| <code>"string"</code><br />
| Argument text.<br />
|-<br />
| <code>"int"</code><br />
| Argument converted to an integer.<br />
|-<br />
| <code>"float"</code><br />
| Argument converted to a decimal value.<br />
|-<br />
| <code>"byte"</code><br />
| Unsigned value of the byte at the current read position. <code>argument_index</code> and <code>decode_quotes</code> are ignored.<br />
|}<br />
<br />
Result type names are case-insensitive.<br />
<br />
==== String ====<br />
String parsing has two modes selected by the optional <code>decode_quotes</code> parameter. Legacy behavior remains the default so existing modules continue to work without modification. Quote-aware behavior is available by passing a nonzero fourth parameter.<br />
<br />
String results may contain up to <code>MAX_SCRIPT_STRING_LENGTH</code>, currently 65,535 characters - about 36 Standard Academic Pages.<br />
<br />
===== Legacy Parsing =====<br />
Omitting <code>decode_quotes</code>, or passing <code>0</code>, uses legacy whitespace parsing:<br />
<br />
<syntaxhighlight lang="c"><br />
char value = getfilestreamargument(<br />
filestream_handle,<br />
argument_index,<br />
"string"<br />
);<br />
</syntaxhighlight><br />
<br />
Spaces and tabs always separate arguments. Quotation marks have no special meaning and remain part of the returned text.<br />
<br />
Given this line:<br />
<br />
<pre><br />
name "Max Thunder"<br />
</pre><br />
<br />
Legacy parsing returns <code>"Max</code> at argument index <code>1</code> and <code>Thunder"</code> at argument index <code>2</code>.<br />
<br />
This behavior supports older scripts that read and reconstruct files one whitespace-delimited token at a time. Use <code>getfilestreamline()</code> instead when the complete line and its original formatting must be returned as one string.<br />
<br />
===== Quote-Aware Parsing =====<br />
Pass a nonzero fourth parameter to enable modern quote-aware parsing:<br />
<br />
<syntaxhighlight lang="c"><br />
char value = getfilestreamargument(<br />
filestream_handle,<br />
argument_index,<br />
"string",<br />
1<br />
);<br />
</syntaxhighlight><br />
<br />
Matching single or double quotes group text into one argument. Opening and closing quote delimiters are discarded from the returned value. Outside quoted spans, spaces and tabs separate arguments, an unquoted line break ends the current record, and <code>#</code> begins a comment.<br />
<br />
Using the previous example, argument index <code>1</code> returns <code>Max Thunder</code> as one string.<br />
<br />
Empty quoted arguments are supported. The maximum string length applies after quote delimiters are removed.<br />
<br />
====== Double Quotes ======<br />
Enclose multiple-word text in double quotes to group it as a single string.<br />
<br />
<pre><br />
Value: "Hello world"<br />
Result: Hello world<br />
</pre><br />
<br />
Double-quoted spans may appear within an argument and are concatenated with adjacent unquoted text:<br />
<br />
<pre><br />
Value: prefix"two words"suffix<br />
Result: prefixtwo wordssuffix<br />
</pre><br />
<br />
====== Single Quotes ======<br />
Single quotes may also group text:<br />
<br />
<pre><br />
Value: 'Multiple words'<br />
Result: Multiple words<br />
</pre><br />
<br />
Single quotes begin grouping only at an argument boundary. This preserves apostrophes in ordinary words:<br />
<br />
<pre><br />
Value: It's<br />
Result: It's<br />
</pre><br />
<br />
====== Mixed Quotes ======<br />
The opposite quote type remains literal inside a quoted span:<br />
<br />
<pre><br />
Value: "Hello, it's a good day."<br />
Result: Hello, it's a good day.<br />
</pre><br />
<br />
<pre><br />
Value: 'She said "hello".'<br />
Result: She said "hello".<br />
</pre><br />
<br />
==== Numeric ====<br />
Missing or nonnumeric arguments converted with <code>"int"</code> or <code>"float"</code> resolve to <code>0</code>. Validate file structure when zero is also a meaningful value.<br />
<br />
Parsing mode also applies before numeric conversion. Legacy parsing retains quote characters, so a quoted number such as <code>"125"</code> converts to <code>0</code>. Quote-aware parsing removes the delimiters first, allowing the same value to convert to <code>125</code>.<br />
<br />
=== getfilestreamline() ===<br />
<syntaxhighlight lang="c"><br />
char line = getfilestreamline(filestream_handle);<br />
</syntaxhighlight>Returns text from the current read position through the next carriage return, line feed, or end of buffer. The line-ending characters are not included.<br />
<br />
This function does not advance the read position. Repeated calls return the same line until <code>filestreamnextline()</code> or <code>setfilestreamposition()</code> changes the position.<br />
<br />
An empty line and the end of the buffer both return an empty string.<br />
<br />
=== getfilestreamposition() ===<br />
<syntaxhighlight lang="c"><br />
int position = getfilestreamposition(filestream_handle);<br />
</syntaxhighlight>Returns the current read position as a byte offset from the beginning of the buffer. The value is not a line number.<br />
<br />
Positions may be stored and supplied later to <code>setfilestreamposition()</code>.<br />
<br />
=== openfilestream() ===<br />
<syntaxhighlight lang="c"><br />
int filestream_handle = openfilestream(filename[, location]);<br />
</syntaxhighlight>Loads an existing file into memory, sets its read position to <code>0</code>, and returns the filestream handle. The complete file is loaded at once.<br />
{| class="wikitable"<br />
!<code>location</code><br />
!Source<br />
|-<br />
|Omitted or <code>0</code><br />
|Module-relative path. OpenBOR checks loose files and the current packfile.<br />
|-<br />
|Any nonzero value<br />
|Current module's subdirectory under <code>Saves</code>.<br />
|}<br />
For a module named <code>Example.pak</code>, the following reads <code>Saves/Example/profile.txt</code>:<syntaxhighlight lang="c"><br />
int filestream_handle = openfilestream("profile.txt", 1);<br />
</syntaxhighlight><br />
The function returns <code>-1</code> when the requested file does not exist or cannot be opened. Always validate the result before using it:<syntaxhighlight lang="c" line="1"><br />
void filestream_handle = openfilestream("data/config.txt");<br />
<br />
if (filestream_handle < 0) {<br />
return;<br />
}<br />
</syntaxhighlight><br />
<br />
=== savefilestream() ===<br />
<syntaxhighlight lang="c"><br />
savefilestream( filestream_handle, filename [, pathname [, save_type]] );<br />
</syntaxhighlight>Writes the current buffer to an external file. The destination is opened in write mode, so an existing file at the same path is replaced.<br />
<br />
When <code>pathname</code> is omitted, OpenBOR writes to the current module's subdirectory under <code>Saves</code>:<syntaxhighlight lang="c"><br />
savefilestream(filestream_handle, "profile.txt");<br />
</syntaxhighlight>An optional custom pathname is relative to the engine's working directory:<syntaxhighlight lang="c"><br />
savefilestream( filestream_handle, "profile.txt", "data/generated/" );<br />
</syntaxhighlight>The custom pathname is joined directly to the filename. Include the final slash or backslash in <code>pathname</code>.<br />
<br />
Default save paths are recommended for portable persistent data. Custom relative paths may resolve differently between platforms and launch environments.<br />
<br />
Text mode writes the buffer and then adds <code>\r\n</code> to the end of the file. Passing <code>"byte"</code> as <code>save_type</code> suppresses that final line break:<syntaxhighlight lang="c"><br />
savefilestream(filestream_handle, "output.dat", "data/generated/", "byte");<br />
</syntaxhighlight>Text mode adds this line break unconditionally. If a loaded buffer already ends with <code>\r\n</code> and is saved again without new content after it, the file gains another empty line.<br />
<br />
Saving does not close the filestream. The same buffer may be appended or saved again before it is released.<br />
<br />
=== setfilestreamposition() ===<br />
<syntaxhighlight lang="c"><br />
setfilestreamposition(filestream_handle, position);<br />
</syntaxhighlight>Sets the read position to a byte offset. Use <code>0</code> to return to the beginning:<syntaxhighlight lang="c"><br />
setfilestreamposition(filestream_handle, 0);<br />
</syntaxhighlight>The engine does not validate or clamp this value. Negative positions and positions beyond the allocated buffer are invalid and may cause unstable behavior.<br />
<br />
Changing the read position does not affect <code>filestreamappend()</code>, which always writes at the buffer end.<br />
<br />
== Iterating Through Lines ==<br />
OpenBOR does not provide a separate end-of-filestream function. Compare the position before and after <code>filestreamnextline()</code> to detect when no further progress is possible:<syntaxhighlight lang="c" line="1"><br />
void filestream_handle = openfilestream("data/records.txt");<br />
<br />
if (filestream_handle >= 0) {<br />
while (1) {<br />
int current_position = getfilestreamposition(filestream_handle);<br />
<br />
char current_line = getfilestreamline(filestream_handle);<br />
<br />
filestreamnextline(filestream_handle);<br />
<br />
int next_position = getfilestreamposition(filestream_handle);<br />
<br />
if (current_line != "") {<br />
log(current_line + "\n");<br />
}<br />
<br />
if (next_position == current_position) {<br />
break;<br />
}<br />
}<br />
<br />
closefilestream(filestream_handle);<br />
}<br />
</syntaxhighlight>This pattern also tolerates empty lines. <code>filestreamnextline()</code> skips their line-ending characters and continues to the next populated line.<br />
<br />
== Binary Data ==<br />
Byte mode lets scripts work with individual numeric byte values instead of parsed text. This is useful for compact records, custom encodings, byte-level inspection, and data containing non-printing values that are awkward to represent as ordinary strings. Reads return the byte at the current position, while append operations can add byte values directly without converting them to text.<br />
<br />
Byte mode is not currently a complete binary-file interface. Saving determines the output length by scanning for a null terminator, so a byte value of <code>0</code> ends the writable content. Values from <code>1</code> through <code>255</code> can be manipulated and preserved, but files containing embedded null bytes cannot be saved reliably. Use byte mode for controlled byte-oriented formats, and text mode or another native API when arbitrary binary data must be preserved.<br />
<br />
== Practical Guidance ==<br />
<br />
* Check every <code>openfilestream()</code> result for <code>-1</code>.<br />
* Keep handles private to the code that owns their lifecycle when practical.<br />
* Maximum file path length is 511 characters. Be aware that some operating systems impose stricter limits. Windows 11, for example, limits file paths to 260 characters by default. For portability, try to keep file paths reasonable in length.<br />
* Save before closing when changes must persist.<br />
* Close every filestream when it is no longer needed.<br />
* Never use a closed handle or invent a handle index.<br />
* Check the return value from <code>deletefilestream()</code> before assuming a file was removed.<br />
* Close a buffer separately when deleting the file from which it was loaded.<br />
* Use <code>getfilestreamposition()</code> to preserve known-safe positions instead of guessing byte offsets.<br />
* Prefer one logical record per line and whitespace-separated fields when using <code>getfilestreamargument()</code>.<br />
* Use <code>getfilestreamline()</code> when field content may contain spaces.<br />
* Avoid loading unnecessarily large files. Opening a filestream allocates enough memory for the complete file.<br />
* Remember that packfile content is not modified in place. Save changed data to the module's save directory or another writable external path.<br />
<br />
The engine releases any remaining filestream buffers during shutdown, but does not save them automatically or delete their external files. Explicit cleanup keeps ownership clear and allows closed handle slots to be reused during play.<br />
<br />
== See Also ==<br />
<br />
* [[Script Overview]]<br />
* [[:Category:Script Functions|Script Functions]]<br />
* [[Arrays]]<br />
* [[Strings]]<br />
* [[Variables Overview]]<br />
<br />
[[Category:Openbor]]<br />
[[Category:Script]]</div>Dcurrenthttps://chronocrash.com/openbor/wiki/index.php?title=File_Operations&diff=1083File Operations2026-08-24T05:42:22Z<p>Dcurrent: /* Numeric */</p>
<hr />
<div>OpenBOR supports file CRUD - create, read, update, and delete - through an API called filestream. Scripts can load external files into memory, read structured text, assemble or revise content, save the result to disk, and remove files that are no longer needed. Common uses include custom configuration, persistent game data, generated model or script files, and data exchanged with external tools.<br />
<br />
Despite the name, an OpenBOR filestream is not a continuously open operating-system file. Instead, OpenBOR filestreams use memory-backed buffers. Opening a file loads its contents into memory, after which reading and editing require no additional disk access or filesystem overhead. Scripts may perform any number of operations at memory speed, then explicitly commit the finished buffer to storage with <code>savefilestream()</code>. <br />
<br />
Each filestream maintains two independent locations:<br />
<br />
* '''Buffer end -''' <code>filestreamappend()</code> always writes here.<br />
* '''Read position -''' Line, argument, byte, and position functions operate here.<br />
<br />
Changing the read position does not change where appended data is written.<blockquote>'''Important:''' Memory buffers and external files have separate lifecycles. <code>closefilestream()</code> releases a buffer without deleting its saved file. <code>deletefilestream()</code> removes an external file without releasing any buffer previously loaded from it.</blockquote><br />
<br />
== Lifecycle ==<br />
Creating, reading, or updating a file normally follows four steps:<br />
<br />
# Create an empty stream with <code>createfilestream()</code>, or load an existing file with <code>openfilestream()</code>.<br />
# Read from the current position or append content to the buffer.<br />
# Call <code>savefilestream()</code> when the buffer should be written to disk.<br />
# Call <code>closefilestream()</code> when the buffer is no longer needed.<br />
<br />
Deletion is independent of this handle lifecycle. Pass a filename directly to <code>deletefilestream()</code>; no stream needs to be open.<br />
{| class="wikitable"<br />
!Operation<br />
!Native support<br />
!Method<br />
|-<br />
|Create<br />
|Yes<br />
|Create an empty buffer, append content, then save it under a filename.<br />
|-<br />
|Read<br />
|Yes<br />
|Open a file, then read its current line, arguments, or byte.<br />
|-<br />
|Update<br />
|Append or rewrite<br />
|Open and append to the loaded buffer, or construct a replacement buffer, then save over the previous file.<br />
|-<br />
|Delete<br />
|Yes<br />
|Pass a filename to <code>deletefilestream()</code> to remove a writable external file.<br />
|}<br />
Saving is explicit. Closing an unsaved stream discards its in-memory changes. Deleting a file does not discard a loaded buffer, so saving that buffer later may recreate the file.<br />
<br />
== Handle and Buffer Model ==<br />
The returned filestream handle is a zero-based index into the engine's filestream collection. Internally, each entry contains:<br />
{| class="wikitable"<br />
!Member<br />
!Purpose<br />
|-<br />
|<code>buf</code><br />
|Allocated memory containing the loaded or constructed data.<br />
|-<br />
|<code>size</code><br />
|Current buffer size and append location.<br />
|-<br />
|<code>pos</code><br />
|Current byte position used by read functions.<br />
|}<br />
Closed entries become available for reuse. Once <code>closefilestream()</code> is called, the old handle is invalid and may later identify a different filestream.<br />
<br />
The engine does not clamp filestream handles or manually assigned positions. Use only handles returned by <code>createfilestream()</code> or successful calls to <code>openfilestream()</code>, and never use a handle after closing it.<br />
<br />
== Walk-through ==<br />
<br />
=== Create and Save ===<br />
The following creates a two-line text file:<syntaxhighlight lang="c" line="1"><br />
void filestream_handle = createfilestream();<br />
<br />
filestreamappend(filestream_handle, "name", 1);<br />
filestreamappend(filestream_handle, "Max");<br />
<br />
filestreamappend(filestream_handle, "score", 0);<br />
filestreamappend(filestream_handle, 125000);<br />
<br />
savefilestream(filestream_handle, "profile.txt");<br />
closefilestream(filestream_handle);<br />
</syntaxhighlight>The default save location is the current module's subdirectory under <code>Saves</code>. Text mode adds a final carriage return and line feed, producing:<pre><br />
name Max<br />
score 125000<br />
</pre>In this example, write type <code>1</code> adds a trailing space after <code>name</code>. Write type <code>0</code> begins a new line before <code>score</code> and then adds a trailing space.<br />
<br />
=== Open and Read ===<br />
Pass a nonzero location value to load from the current module's save directory:<syntaxhighlight lang="c" line="1"><br />
void filestream_handle = openfilestream("profile.txt", 1);<br />
<br />
if (filestream_handle >= 0) {<br />
char player_name = getfilestreamargument(filestream_handle, 1, "string");<br />
<br />
filestreamnextline(filestream_handle);<br />
<br />
int player_score = getfilestreamargument(filestream_handle, 1, "int");<br />
<br />
closefilestream(filestream_handle);<br />
}<br />
</syntaxhighlight>The first argument on each line is index <code>0</code>. The example reads index <code>1</code>, returning <code>"Max"</code> from the first line and <code>125000</code> from the second.<br />
<br />
=== Append and Replace ===<br />
Opening a file loads its existing content into the buffer. Appending new content and saving under the same name rewrites the external file with the expanded buffer:<syntaxhighlight lang="c" line="1"><br />
void filestream_handle = openfilestream("profile.txt", 1);<br />
<br />
if (filestream_handle >= 0) {<br />
/*<br />
* Files written by savefilestream() in text mode already<br />
* end with a line break, so begin the next record directly.<br />
*/<br />
filestreamappend(filestream_handle, "unlocks", 1);<br />
filestreamappend(filestream_handle, 3);<br />
<br />
savefilestream(filestream_handle, "profile.txt");<br />
closefilestream(filestream_handle);<br />
}<br />
</syntaxhighlight><code>savefilestream()</code> opens the destination in write mode and replaces its previous contents. Existing data survives only because <code>openfilestream()</code> first copied that data into the memory buffer.<br />
<br />
Filestreams do not provide insertion, replacement, or removal at an arbitrary read position. To modify existing records, read the source and assemble the desired result in another filestream, then save the replacement over the original filename.<br />
<br />
=== Delete ===<br />
Deletion targets the external file by name rather than a filestream handle:<syntaxhighlight lang="c" line="1"><br />
int deleted = deletefilestream("profile.txt");<br />
<br />
if (!deleted) {<br />
log("Could not delete profile.txt.\n");<br />
}<br />
</syntaxhighlight>The default location is the current module's subdirectory under <code>Saves</code>, matching <code>savefilestream()</code>. Supply the same optional pathname used to save a file when deleting from a custom location:<syntaxhighlight lang="c" line="1"><br />
int deleted = deletefilestream(<br />
"profile.txt",<br />
"data/generated/"<br />
);<br />
</syntaxhighlight>Only the external file is removed. If a filestream already contains data loaded from that file, its memory buffer and handle remain valid until <code>closefilestream()</code> is called.<br />
<br />
== Functions ==<br />
<br />
=== closefilestream() ===<br />
<syntaxhighlight lang="c"><br />
closefilestream(filestream_handle);<br />
</syntaxhighlight>Releases the filestream's allocated buffer. The handle becomes invalid and its collection index may be reused by a later create or open operation.<br />
<br />
This function does not save the buffer and does not delete an external file.<br />
<br />
=== createfilestream() ===<br />
<syntaxhighlight lang="c"><br />
int filestream_handle = createfilestream();<br />
</syntaxhighlight>Allocates an empty memory buffer and returns its handle. The initial read position and content size are both <code>0</code>.<br />
<br />
No external file is created until the buffer is passed to <code>savefilestream()</code>.<br />
<br />
=== deletefilestream() ===<br />
<syntaxhighlight lang="c"><br />
int deleted = deletefilestream(filename[, pathname]);<br />
</syntaxhighlight>Deletes a writable external file and returns <code>1</code> when the operating system confirms deletion. A return value of <code>0</code> means the file could not be deleted, including when the file does not exist, the path is incorrect, or the operating system denies access.<br />
<br />
When <code>pathname</code> is omitted, OpenBOR targets the current module's subdirectory under <code>Saves</code>:<syntaxhighlight lang="c"><br />
int deleted = deletefilestream("profile.txt");<br />
</syntaxhighlight>The optional pathname follows the same rules as <code>savefilestream()</code> and is relative to the engine's working directory:<syntaxhighlight lang="c"><br />
int deleted = deletefilestream( "profile.txt", "data/generated/");<br />
</syntaxhighlight>The pathname is joined directly to the filename. Include the final slash or backslash.<br />
<br />
Deletion operates on external files only and cannot remove content from a packfile. It does not accept a filestream handle, release a memory buffer, or invalidate a handle. Saving a still-open buffer to the same filename after successful deletion creates the file again.<br />
<br />
=== filestreamappend() ===<br />
<syntaxhighlight lang="c"><br />
filestreamappend(filestream_handle, value[, write_type[, value_type]]);<br />
</syntaxhighlight>Converts the supplied value to text and appends it at the end of the buffer. The current read position has no effect on the append location.<br />
{| class="wikitable"<br />
!<code>write_type</code><br />
!Behavior<br />
|-<br />
|Omitted, <code>-1</code>, or any value other than <code>0</code> and <code>1</code><br />
|Appends the value without adding a separator.<br />
|-<br />
|<code>0</code><br />
|Adds <code>\r\n</code> before the value, then adds one trailing space after it.<br />
|-<br />
|<code>1</code><br />
|Appends the value followed by one trailing space.<br />
|}<br />
Write type <code>0</code> starts a new line before the supplied value. Using it for the first value in an empty stream therefore creates an initial blank line.<br />
<br />
Passing <code>"byte"</code> as <code>value_type</code> selects the legacy byte append path:<syntaxhighlight lang="c"><br />
filestreamappend(filestream_handle, byte_value, write_type, "byte");<br />
</syntaxhighlight>See [[File Operations#Binary Data|Binary Data]] before using byte mode.<br />
<br />
=== filestreamnextline() ===<br />
<syntaxhighlight lang="c"><br />
filestreamnextline(filestream_handle);<br />
</syntaxhighlight>Advances the read position from its current location to the next non-line-break byte. The function scans to the end of the current line, then skips all consecutive <code>\r</code> and <code>\n</code> characters.<br />
<br />
Multiple empty lines are skipped as one group. At the end of the buffer, the position does not change.<br />
<br />
=== getfilestreamargument() ===<br />
<br />
<syntaxhighlight lang="c"><br />
mixed result = getfilestreamargument(<br />
filestream_handle,<br />
argument_index,<br />
result_type<br />
[, decode_quotes]<br />
);<br />
</syntaxhighlight><br />
<br />
Reads an argument beginning at the current filestream position without advancing the position. Argument indexes are zero-based.<br />
<br />
The optional <code>decode_quotes</code> parameter controls quote handling. Omit it or pass <code>0</code> for legacy whitespace parsing. Pass any nonzero value for modern quote-aware parsing. See [[File Operations#String|String]] for details and examples.<br />
<br />
{| class="wikitable"<br />
! <code>result_type</code><br />
! Return<br />
|-<br />
| <code>"string"</code><br />
| Argument text.<br />
|-<br />
| <code>"int"</code><br />
| Argument converted to an integer.<br />
|-<br />
| <code>"float"</code><br />
| Argument converted to a decimal value.<br />
|-<br />
| <code>"byte"</code><br />
| Unsigned value of the byte at the current read position. <code>argument_index</code> and <code>decode_quotes</code> are ignored.<br />
|}<br />
<br />
Result type names are case-insensitive.<br />
<br />
=== String ===<br />
<br />
String parsing has two modes selected by the optional <code>decode_quotes</code> parameter. Legacy behavior remains the default so existing modules continue to work without modification. Quote-aware behavior is available by passing a nonzero fourth parameter.<br />
<br />
String results may contain up to <code>MAX_SCRIPT_STRING_LENGTH</code>, currently 65,535 characters - about 36 Standard Academic Pages.<br />
<br />
==== Legacy Parsing ====<br />
<br />
Omitting <code>decode_quotes</code>, or passing <code>0</code>, uses legacy whitespace parsing:<br />
<br />
<syntaxhighlight lang="c"><br />
char value = getfilestreamargument(<br />
filestream_handle,<br />
argument_index,<br />
"string"<br />
);<br />
</syntaxhighlight><br />
<br />
Spaces and tabs always separate arguments. Quotation marks have no special meaning and remain part of the returned text.<br />
<br />
Given this line:<br />
<br />
<pre><br />
name "Max Thunder"<br />
</pre><br />
<br />
Legacy parsing returns <code>"Max</code> at argument index <code>1</code> and <code>Thunder"</code> at argument index <code>2</code>.<br />
<br />
This behavior supports older scripts that read and reconstruct files one whitespace-delimited token at a time. Use <code>getfilestreamline()</code> instead when the complete line and its original formatting must be returned as one string.<br />
<br />
==== Quote-Aware Parsing ====<br />
<br />
Pass a nonzero fourth parameter to enable modern quote-aware parsing:<br />
<br />
<syntaxhighlight lang="c"><br />
char value = getfilestreamargument(<br />
filestream_handle,<br />
argument_index,<br />
"string",<br />
1<br />
);<br />
</syntaxhighlight><br />
<br />
Matching single or double quotes group text into one argument. Opening and closing quote delimiters are discarded from the returned value. Outside quoted spans, spaces and tabs separate arguments, an unquoted line break ends the current record, and <code>#</code> begins a comment.<br />
<br />
Using the previous example, argument index <code>1</code> returns <code>Max Thunder</code> as one string.<br />
<br />
Empty quoted arguments are supported. The maximum string length applies after quote delimiters are removed.<br />
<br />
===== Double Quotes =====<br />
<br />
Enclose multiple-word text in double quotes to group it as a single string.<br />
<br />
<pre><br />
Value: "Hello world"<br />
Result: Hello world<br />
</pre><br />
<br />
Double-quoted spans may appear within an argument and are concatenated with adjacent unquoted text:<br />
<br />
<pre><br />
Value: prefix"two words"suffix<br />
Result: prefixtwo wordssuffix<br />
</pre><br />
<br />
===== Single Quotes =====<br />
<br />
Single quotes may also group text:<br />
<br />
<pre><br />
Value: 'Multiple words'<br />
Result: Multiple words<br />
</pre><br />
<br />
Single quotes begin grouping only at an argument boundary. This preserves apostrophes in ordinary words:<br />
<br />
<pre><br />
Value: It's<br />
Result: It's<br />
</pre><br />
<br />
===== Mixed Quotes =====<br />
<br />
The opposite quote type remains literal inside a quoted span:<br />
<br />
<pre><br />
Value: "Hello, it's a good day."<br />
Result: Hello, it's a good day.<br />
</pre><br />
<br />
<pre><br />
Value: 'She said "hello".'<br />
Result: She said "hello".<br />
</pre><br />
<br />
=== Numeric ===<br />
<br />
Missing or nonnumeric arguments converted with <code>"int"</code> or <code>"float"</code> resolve to <code>0</code>. Validate file structure when zero is also a meaningful value.<br />
<br />
Parsing mode also applies before numeric conversion. Legacy parsing retains quote characters, so a quoted number such as <code>"125"</code> converts to <code>0</code>. Quote-aware parsing removes the delimiters first, allowing the same value to convert to <code>125</code>.<br />
<br />
=== getfilestreamline() ===<br />
<syntaxhighlight lang="c"><br />
char line = getfilestreamline(filestream_handle);<br />
</syntaxhighlight>Returns text from the current read position through the next carriage return, line feed, or end of buffer. The line-ending characters are not included.<br />
<br />
This function does not advance the read position. Repeated calls return the same line until <code>filestreamnextline()</code> or <code>setfilestreamposition()</code> changes the position.<br />
<br />
An empty line and the end of the buffer both return an empty string.<br />
<br />
=== getfilestreamposition() ===<br />
<syntaxhighlight lang="c"><br />
int position = getfilestreamposition(filestream_handle);<br />
</syntaxhighlight>Returns the current read position as a byte offset from the beginning of the buffer. The value is not a line number.<br />
<br />
Positions may be stored and supplied later to <code>setfilestreamposition()</code>.<br />
<br />
=== openfilestream() ===<br />
<syntaxhighlight lang="c"><br />
int filestream_handle = openfilestream(filename[, location]);<br />
</syntaxhighlight>Loads an existing file into memory, sets its read position to <code>0</code>, and returns the filestream handle. The complete file is loaded at once.<br />
{| class="wikitable"<br />
!<code>location</code><br />
!Source<br />
|-<br />
|Omitted or <code>0</code><br />
|Module-relative path. OpenBOR checks loose files and the current packfile.<br />
|-<br />
|Any nonzero value<br />
|Current module's subdirectory under <code>Saves</code>.<br />
|}<br />
For a module named <code>Example.pak</code>, the following reads <code>Saves/Example/profile.txt</code>:<syntaxhighlight lang="c"><br />
int filestream_handle = openfilestream("profile.txt", 1);<br />
</syntaxhighlight><br />
The function returns <code>-1</code> when the requested file does not exist or cannot be opened. Always validate the result before using it:<syntaxhighlight lang="c" line="1"><br />
void filestream_handle = openfilestream("data/config.txt");<br />
<br />
if (filestream_handle < 0) {<br />
return;<br />
}<br />
</syntaxhighlight><br />
<br />
=== savefilestream() ===<br />
<syntaxhighlight lang="c"><br />
savefilestream( filestream_handle, filename [, pathname [, save_type]] );<br />
</syntaxhighlight>Writes the current buffer to an external file. The destination is opened in write mode, so an existing file at the same path is replaced.<br />
<br />
When <code>pathname</code> is omitted, OpenBOR writes to the current module's subdirectory under <code>Saves</code>:<syntaxhighlight lang="c"><br />
savefilestream(filestream_handle, "profile.txt");<br />
</syntaxhighlight>An optional custom pathname is relative to the engine's working directory:<syntaxhighlight lang="c"><br />
savefilestream( filestream_handle, "profile.txt", "data/generated/" );<br />
</syntaxhighlight>The custom pathname is joined directly to the filename. Include the final slash or backslash in <code>pathname</code>.<br />
<br />
Default save paths are recommended for portable persistent data. Custom relative paths may resolve differently between platforms and launch environments.<br />
<br />
Text mode writes the buffer and then adds <code>\r\n</code> to the end of the file. Passing <code>"byte"</code> as <code>save_type</code> suppresses that final line break:<syntaxhighlight lang="c"><br />
savefilestream(filestream_handle, "output.dat", "data/generated/", "byte");<br />
</syntaxhighlight>Text mode adds this line break unconditionally. If a loaded buffer already ends with <code>\r\n</code> and is saved again without new content after it, the file gains another empty line.<br />
<br />
Saving does not close the filestream. The same buffer may be appended or saved again before it is released.<br />
<br />
=== setfilestreamposition() ===<br />
<syntaxhighlight lang="c"><br />
setfilestreamposition(filestream_handle, position);<br />
</syntaxhighlight>Sets the read position to a byte offset. Use <code>0</code> to return to the beginning:<syntaxhighlight lang="c"><br />
setfilestreamposition(filestream_handle, 0);<br />
</syntaxhighlight>The engine does not validate or clamp this value. Negative positions and positions beyond the allocated buffer are invalid and may cause unstable behavior.<br />
<br />
Changing the read position does not affect <code>filestreamappend()</code>, which always writes at the buffer end.<br />
<br />
== Iterating Through Lines ==<br />
OpenBOR does not provide a separate end-of-filestream function. Compare the position before and after <code>filestreamnextline()</code> to detect when no further progress is possible:<syntaxhighlight lang="c" line="1"><br />
void filestream_handle = openfilestream("data/records.txt");<br />
<br />
if (filestream_handle >= 0) {<br />
while (1) {<br />
int current_position = getfilestreamposition(filestream_handle);<br />
<br />
char current_line = getfilestreamline(filestream_handle);<br />
<br />
filestreamnextline(filestream_handle);<br />
<br />
int next_position = getfilestreamposition(filestream_handle);<br />
<br />
if (current_line != "") {<br />
log(current_line + "\n");<br />
}<br />
<br />
if (next_position == current_position) {<br />
break;<br />
}<br />
}<br />
<br />
closefilestream(filestream_handle);<br />
}<br />
</syntaxhighlight>This pattern also tolerates empty lines. <code>filestreamnextline()</code> skips their line-ending characters and continues to the next populated line.<br />
<br />
== Binary Data ==<br />
Byte mode lets scripts work with individual numeric byte values instead of parsed text. This is useful for compact records, custom encodings, byte-level inspection, and data containing non-printing values that are awkward to represent as ordinary strings. Reads return the byte at the current position, while append operations can add byte values directly without converting them to text.<br />
<br />
Byte mode is not currently a complete binary-file interface. Saving determines the output length by scanning for a null terminator, so a byte value of <code>0</code> ends the writable content. Values from <code>1</code> through <code>255</code> can be manipulated and preserved, but files containing embedded null bytes cannot be saved reliably. Use byte mode for controlled byte-oriented formats, and text mode or another native API when arbitrary binary data must be preserved.<br />
<br />
== Practical Guidance ==<br />
<br />
* Check every <code>openfilestream()</code> result for <code>-1</code>.<br />
* Keep handles private to the code that owns their lifecycle when practical.<br />
* Maximum file path length is 511 characters. Be aware that some operating systems impose stricter limits. Windows 11, for example, limits file paths to 260 characters by default. For portability, try to keep file paths reasonable in length.<br />
* Save before closing when changes must persist.<br />
* Close every filestream when it is no longer needed.<br />
* Never use a closed handle or invent a handle index.<br />
* Check the return value from <code>deletefilestream()</code> before assuming a file was removed.<br />
* Close a buffer separately when deleting the file from which it was loaded.<br />
* Use <code>getfilestreamposition()</code> to preserve known-safe positions instead of guessing byte offsets.<br />
* Prefer one logical record per line and whitespace-separated fields when using <code>getfilestreamargument()</code>.<br />
* Use <code>getfilestreamline()</code> when field content may contain spaces.<br />
* Avoid loading unnecessarily large files. Opening a filestream allocates enough memory for the complete file.<br />
* Remember that packfile content is not modified in place. Save changed data to the module's save directory or another writable external path.<br />
<br />
The engine releases any remaining filestream buffers during shutdown, but does not save them automatically or delete their external files. Explicit cleanup keeps ownership clear and allows closed handle slots to be reused during play.<br />
<br />
== See Also ==<br />
<br />
* [[Script Overview]]<br />
* [[:Category:Script Functions|Script Functions]]<br />
* [[Arrays]]<br />
* [[Strings]]<br />
* [[Variables Overview]]<br />
<br />
[[Category:Openbor]]<br />
[[Category:Script]]</div>Dcurrenthttps://chronocrash.com/openbor/wiki/index.php?title=File_Operations&diff=1082File Operations2026-08-24T05:41:08Z<p>Dcurrent: /* String */</p>
<hr />
<div>OpenBOR supports file CRUD - create, read, update, and delete - through an API called filestream. Scripts can load external files into memory, read structured text, assemble or revise content, save the result to disk, and remove files that are no longer needed. Common uses include custom configuration, persistent game data, generated model or script files, and data exchanged with external tools.<br />
<br />
Despite the name, an OpenBOR filestream is not a continuously open operating-system file. Instead, OpenBOR filestreams use memory-backed buffers. Opening a file loads its contents into memory, after which reading and editing require no additional disk access or filesystem overhead. Scripts may perform any number of operations at memory speed, then explicitly commit the finished buffer to storage with <code>savefilestream()</code>. <br />
<br />
Each filestream maintains two independent locations:<br />
<br />
* '''Buffer end -''' <code>filestreamappend()</code> always writes here.<br />
* '''Read position -''' Line, argument, byte, and position functions operate here.<br />
<br />
Changing the read position does not change where appended data is written.<blockquote>'''Important:''' Memory buffers and external files have separate lifecycles. <code>closefilestream()</code> releases a buffer without deleting its saved file. <code>deletefilestream()</code> removes an external file without releasing any buffer previously loaded from it.</blockquote><br />
<br />
== Lifecycle ==<br />
Creating, reading, or updating a file normally follows four steps:<br />
<br />
# Create an empty stream with <code>createfilestream()</code>, or load an existing file with <code>openfilestream()</code>.<br />
# Read from the current position or append content to the buffer.<br />
# Call <code>savefilestream()</code> when the buffer should be written to disk.<br />
# Call <code>closefilestream()</code> when the buffer is no longer needed.<br />
<br />
Deletion is independent of this handle lifecycle. Pass a filename directly to <code>deletefilestream()</code>; no stream needs to be open.<br />
{| class="wikitable"<br />
!Operation<br />
!Native support<br />
!Method<br />
|-<br />
|Create<br />
|Yes<br />
|Create an empty buffer, append content, then save it under a filename.<br />
|-<br />
|Read<br />
|Yes<br />
|Open a file, then read its current line, arguments, or byte.<br />
|-<br />
|Update<br />
|Append or rewrite<br />
|Open and append to the loaded buffer, or construct a replacement buffer, then save over the previous file.<br />
|-<br />
|Delete<br />
|Yes<br />
|Pass a filename to <code>deletefilestream()</code> to remove a writable external file.<br />
|}<br />
Saving is explicit. Closing an unsaved stream discards its in-memory changes. Deleting a file does not discard a loaded buffer, so saving that buffer later may recreate the file.<br />
<br />
== Handle and Buffer Model ==<br />
The returned filestream handle is a zero-based index into the engine's filestream collection. Internally, each entry contains:<br />
{| class="wikitable"<br />
!Member<br />
!Purpose<br />
|-<br />
|<code>buf</code><br />
|Allocated memory containing the loaded or constructed data.<br />
|-<br />
|<code>size</code><br />
|Current buffer size and append location.<br />
|-<br />
|<code>pos</code><br />
|Current byte position used by read functions.<br />
|}<br />
Closed entries become available for reuse. Once <code>closefilestream()</code> is called, the old handle is invalid and may later identify a different filestream.<br />
<br />
The engine does not clamp filestream handles or manually assigned positions. Use only handles returned by <code>createfilestream()</code> or successful calls to <code>openfilestream()</code>, and never use a handle after closing it.<br />
<br />
== Walk-through ==<br />
<br />
=== Create and Save ===<br />
The following creates a two-line text file:<syntaxhighlight lang="c" line="1"><br />
void filestream_handle = createfilestream();<br />
<br />
filestreamappend(filestream_handle, "name", 1);<br />
filestreamappend(filestream_handle, "Max");<br />
<br />
filestreamappend(filestream_handle, "score", 0);<br />
filestreamappend(filestream_handle, 125000);<br />
<br />
savefilestream(filestream_handle, "profile.txt");<br />
closefilestream(filestream_handle);<br />
</syntaxhighlight>The default save location is the current module's subdirectory under <code>Saves</code>. Text mode adds a final carriage return and line feed, producing:<pre><br />
name Max<br />
score 125000<br />
</pre>In this example, write type <code>1</code> adds a trailing space after <code>name</code>. Write type <code>0</code> begins a new line before <code>score</code> and then adds a trailing space.<br />
<br />
=== Open and Read ===<br />
Pass a nonzero location value to load from the current module's save directory:<syntaxhighlight lang="c" line="1"><br />
void filestream_handle = openfilestream("profile.txt", 1);<br />
<br />
if (filestream_handle >= 0) {<br />
char player_name = getfilestreamargument(filestream_handle, 1, "string");<br />
<br />
filestreamnextline(filestream_handle);<br />
<br />
int player_score = getfilestreamargument(filestream_handle, 1, "int");<br />
<br />
closefilestream(filestream_handle);<br />
}<br />
</syntaxhighlight>The first argument on each line is index <code>0</code>. The example reads index <code>1</code>, returning <code>"Max"</code> from the first line and <code>125000</code> from the second.<br />
<br />
=== Append and Replace ===<br />
Opening a file loads its existing content into the buffer. Appending new content and saving under the same name rewrites the external file with the expanded buffer:<syntaxhighlight lang="c" line="1"><br />
void filestream_handle = openfilestream("profile.txt", 1);<br />
<br />
if (filestream_handle >= 0) {<br />
/*<br />
* Files written by savefilestream() in text mode already<br />
* end with a line break, so begin the next record directly.<br />
*/<br />
filestreamappend(filestream_handle, "unlocks", 1);<br />
filestreamappend(filestream_handle, 3);<br />
<br />
savefilestream(filestream_handle, "profile.txt");<br />
closefilestream(filestream_handle);<br />
}<br />
</syntaxhighlight><code>savefilestream()</code> opens the destination in write mode and replaces its previous contents. Existing data survives only because <code>openfilestream()</code> first copied that data into the memory buffer.<br />
<br />
Filestreams do not provide insertion, replacement, or removal at an arbitrary read position. To modify existing records, read the source and assemble the desired result in another filestream, then save the replacement over the original filename.<br />
<br />
=== Delete ===<br />
Deletion targets the external file by name rather than a filestream handle:<syntaxhighlight lang="c" line="1"><br />
int deleted = deletefilestream("profile.txt");<br />
<br />
if (!deleted) {<br />
log("Could not delete profile.txt.\n");<br />
}<br />
</syntaxhighlight>The default location is the current module's subdirectory under <code>Saves</code>, matching <code>savefilestream()</code>. Supply the same optional pathname used to save a file when deleting from a custom location:<syntaxhighlight lang="c" line="1"><br />
int deleted = deletefilestream(<br />
"profile.txt",<br />
"data/generated/"<br />
);<br />
</syntaxhighlight>Only the external file is removed. If a filestream already contains data loaded from that file, its memory buffer and handle remain valid until <code>closefilestream()</code> is called.<br />
<br />
== Functions ==<br />
<br />
=== closefilestream() ===<br />
<syntaxhighlight lang="c"><br />
closefilestream(filestream_handle);<br />
</syntaxhighlight>Releases the filestream's allocated buffer. The handle becomes invalid and its collection index may be reused by a later create or open operation.<br />
<br />
This function does not save the buffer and does not delete an external file.<br />
<br />
=== createfilestream() ===<br />
<syntaxhighlight lang="c"><br />
int filestream_handle = createfilestream();<br />
</syntaxhighlight>Allocates an empty memory buffer and returns its handle. The initial read position and content size are both <code>0</code>.<br />
<br />
No external file is created until the buffer is passed to <code>savefilestream()</code>.<br />
<br />
=== deletefilestream() ===<br />
<syntaxhighlight lang="c"><br />
int deleted = deletefilestream(filename[, pathname]);<br />
</syntaxhighlight>Deletes a writable external file and returns <code>1</code> when the operating system confirms deletion. A return value of <code>0</code> means the file could not be deleted, including when the file does not exist, the path is incorrect, or the operating system denies access.<br />
<br />
When <code>pathname</code> is omitted, OpenBOR targets the current module's subdirectory under <code>Saves</code>:<syntaxhighlight lang="c"><br />
int deleted = deletefilestream("profile.txt");<br />
</syntaxhighlight>The optional pathname follows the same rules as <code>savefilestream()</code> and is relative to the engine's working directory:<syntaxhighlight lang="c"><br />
int deleted = deletefilestream( "profile.txt", "data/generated/");<br />
</syntaxhighlight>The pathname is joined directly to the filename. Include the final slash or backslash.<br />
<br />
Deletion operates on external files only and cannot remove content from a packfile. It does not accept a filestream handle, release a memory buffer, or invalidate a handle. Saving a still-open buffer to the same filename after successful deletion creates the file again.<br />
<br />
=== filestreamappend() ===<br />
<syntaxhighlight lang="c"><br />
filestreamappend(filestream_handle, value[, write_type[, value_type]]);<br />
</syntaxhighlight>Converts the supplied value to text and appends it at the end of the buffer. The current read position has no effect on the append location.<br />
{| class="wikitable"<br />
!<code>write_type</code><br />
!Behavior<br />
|-<br />
|Omitted, <code>-1</code>, or any value other than <code>0</code> and <code>1</code><br />
|Appends the value without adding a separator.<br />
|-<br />
|<code>0</code><br />
|Adds <code>\r\n</code> before the value, then adds one trailing space after it.<br />
|-<br />
|<code>1</code><br />
|Appends the value followed by one trailing space.<br />
|}<br />
Write type <code>0</code> starts a new line before the supplied value. Using it for the first value in an empty stream therefore creates an initial blank line.<br />
<br />
Passing <code>"byte"</code> as <code>value_type</code> selects the legacy byte append path:<syntaxhighlight lang="c"><br />
filestreamappend(filestream_handle, byte_value, write_type, "byte");<br />
</syntaxhighlight>See [[File Operations#Binary Data|Binary Data]] before using byte mode.<br />
<br />
=== filestreamnextline() ===<br />
<syntaxhighlight lang="c"><br />
filestreamnextline(filestream_handle);<br />
</syntaxhighlight>Advances the read position from its current location to the next non-line-break byte. The function scans to the end of the current line, then skips all consecutive <code>\r</code> and <code>\n</code> characters.<br />
<br />
Multiple empty lines are skipped as one group. At the end of the buffer, the position does not change.<br />
<br />
=== getfilestreamargument() ===<br />
<br />
<syntaxhighlight lang="c"><br />
mixed result = getfilestreamargument(<br />
filestream_handle,<br />
argument_index,<br />
result_type<br />
[, decode_quotes]<br />
);<br />
</syntaxhighlight><br />
<br />
Reads an argument beginning at the current filestream position without advancing the position. Argument indexes are zero-based.<br />
<br />
The optional <code>decode_quotes</code> parameter controls quote handling. Omit it or pass <code>0</code> for legacy whitespace parsing. Pass any nonzero value for modern quote-aware parsing. See [[File Operations#String|String]] for details and examples.<br />
<br />
{| class="wikitable"<br />
! <code>result_type</code><br />
! Return<br />
|-<br />
| <code>"string"</code><br />
| Argument text.<br />
|-<br />
| <code>"int"</code><br />
| Argument converted to an integer.<br />
|-<br />
| <code>"float"</code><br />
| Argument converted to a decimal value.<br />
|-<br />
| <code>"byte"</code><br />
| Unsigned value of the byte at the current read position. <code>argument_index</code> and <code>decode_quotes</code> are ignored.<br />
|}<br />
<br />
Result type names are case-insensitive.<br />
<br />
=== String ===<br />
<br />
String parsing has two modes selected by the optional <code>decode_quotes</code> parameter. Legacy behavior remains the default so existing modules continue to work without modification. Quote-aware behavior is available by passing a nonzero fourth parameter.<br />
<br />
String results may contain up to <code>MAX_SCRIPT_STRING_LENGTH</code>, currently 65,535 characters - about 36 Standard Academic Pages.<br />
<br />
==== Legacy Parsing ====<br />
<br />
Omitting <code>decode_quotes</code>, or passing <code>0</code>, uses legacy whitespace parsing:<br />
<br />
<syntaxhighlight lang="c"><br />
char value = getfilestreamargument(<br />
filestream_handle,<br />
argument_index,<br />
"string"<br />
);<br />
</syntaxhighlight><br />
<br />
Spaces and tabs always separate arguments. Quotation marks have no special meaning and remain part of the returned text.<br />
<br />
Given this line:<br />
<br />
<pre><br />
name "Max Thunder"<br />
</pre><br />
<br />
Legacy parsing returns <code>"Max</code> at argument index <code>1</code> and <code>Thunder"</code> at argument index <code>2</code>.<br />
<br />
This behavior supports older scripts that read and reconstruct files one whitespace-delimited token at a time. Use <code>getfilestreamline()</code> instead when the complete line and its original formatting must be returned as one string.<br />
<br />
==== Quote-Aware Parsing ====<br />
<br />
Pass a nonzero fourth parameter to enable modern quote-aware parsing:<br />
<br />
<syntaxhighlight lang="c"><br />
char value = getfilestreamargument(<br />
filestream_handle,<br />
argument_index,<br />
"string",<br />
1<br />
);<br />
</syntaxhighlight><br />
<br />
Matching single or double quotes group text into one argument. Opening and closing quote delimiters are discarded from the returned value. Outside quoted spans, spaces and tabs separate arguments, an unquoted line break ends the current record, and <code>#</code> begins a comment.<br />
<br />
Using the previous example, argument index <code>1</code> returns <code>Max Thunder</code> as one string.<br />
<br />
Empty quoted arguments are supported. The maximum string length applies after quote delimiters are removed.<br />
<br />
===== Double Quotes =====<br />
<br />
Enclose multiple-word text in double quotes to group it as a single string.<br />
<br />
<pre><br />
Value: "Hello world"<br />
Result: Hello world<br />
</pre><br />
<br />
Double-quoted spans may appear within an argument and are concatenated with adjacent unquoted text:<br />
<br />
<pre><br />
Value: prefix"two words"suffix<br />
Result: prefixtwo wordssuffix<br />
</pre><br />
<br />
===== Single Quotes =====<br />
<br />
Single quotes may also group text:<br />
<br />
<pre><br />
Value: 'Multiple words'<br />
Result: Multiple words<br />
</pre><br />
<br />
Single quotes begin grouping only at an argument boundary. This preserves apostrophes in ordinary words:<br />
<br />
<pre><br />
Value: It's<br />
Result: It's<br />
</pre><br />
<br />
===== Mixed Quotes =====<br />
<br />
The opposite quote type remains literal inside a quoted span:<br />
<br />
<pre><br />
Value: "Hello, it's a good day."<br />
Result: Hello, it's a good day.<br />
</pre><br />
<br />
<pre><br />
Value: 'She said "hello".'<br />
Result: She said "hello".<br />
</pre><br />
<br />
=== Numeric ===<br />
<br />
Missing or nonnumeric arguments converted with <code>"int"</code> or <code>"float"</code> resolve to <code>0</code>. Validate file structure when zero is also a meaningful value.<br />
<br />
Parsing mode also applies before numeric conversion. Legacy parsing retains quote characters, so a quoted number such as <code>"125"</code> converts to <code>0</code>. Quote-aware parsing removes the delimiters first, allowing the same value to convert to <code>125</code>.<br />
<br />
=== Numeric ===<br />
Missing or nonnumeric arguments converted with <code>"int"</code> or <code>"float"</code> resolve to <code>0</code>. Validate file structure when zero is also a meaningful value.<br />
<br />
=== getfilestreamline() ===<br />
<syntaxhighlight lang="c"><br />
char line = getfilestreamline(filestream_handle);<br />
</syntaxhighlight>Returns text from the current read position through the next carriage return, line feed, or end of buffer. The line-ending characters are not included.<br />
<br />
This function does not advance the read position. Repeated calls return the same line until <code>filestreamnextline()</code> or <code>setfilestreamposition()</code> changes the position.<br />
<br />
An empty line and the end of the buffer both return an empty string.<br />
<br />
=== getfilestreamposition() ===<br />
<syntaxhighlight lang="c"><br />
int position = getfilestreamposition(filestream_handle);<br />
</syntaxhighlight>Returns the current read position as a byte offset from the beginning of the buffer. The value is not a line number.<br />
<br />
Positions may be stored and supplied later to <code>setfilestreamposition()</code>.<br />
<br />
=== openfilestream() ===<br />
<syntaxhighlight lang="c"><br />
int filestream_handle = openfilestream(filename[, location]);<br />
</syntaxhighlight>Loads an existing file into memory, sets its read position to <code>0</code>, and returns the filestream handle. The complete file is loaded at once.<br />
{| class="wikitable"<br />
!<code>location</code><br />
!Source<br />
|-<br />
|Omitted or <code>0</code><br />
|Module-relative path. OpenBOR checks loose files and the current packfile.<br />
|-<br />
|Any nonzero value<br />
|Current module's subdirectory under <code>Saves</code>.<br />
|}<br />
For a module named <code>Example.pak</code>, the following reads <code>Saves/Example/profile.txt</code>:<syntaxhighlight lang="c"><br />
int filestream_handle = openfilestream("profile.txt", 1);<br />
</syntaxhighlight><br />
The function returns <code>-1</code> when the requested file does not exist or cannot be opened. Always validate the result before using it:<syntaxhighlight lang="c" line="1"><br />
void filestream_handle = openfilestream("data/config.txt");<br />
<br />
if (filestream_handle < 0) {<br />
return;<br />
}<br />
</syntaxhighlight><br />
<br />
=== savefilestream() ===<br />
<syntaxhighlight lang="c"><br />
savefilestream( filestream_handle, filename [, pathname [, save_type]] );<br />
</syntaxhighlight>Writes the current buffer to an external file. The destination is opened in write mode, so an existing file at the same path is replaced.<br />
<br />
When <code>pathname</code> is omitted, OpenBOR writes to the current module's subdirectory under <code>Saves</code>:<syntaxhighlight lang="c"><br />
savefilestream(filestream_handle, "profile.txt");<br />
</syntaxhighlight>An optional custom pathname is relative to the engine's working directory:<syntaxhighlight lang="c"><br />
savefilestream( filestream_handle, "profile.txt", "data/generated/" );<br />
</syntaxhighlight>The custom pathname is joined directly to the filename. Include the final slash or backslash in <code>pathname</code>.<br />
<br />
Default save paths are recommended for portable persistent data. Custom relative paths may resolve differently between platforms and launch environments.<br />
<br />
Text mode writes the buffer and then adds <code>\r\n</code> to the end of the file. Passing <code>"byte"</code> as <code>save_type</code> suppresses that final line break:<syntaxhighlight lang="c"><br />
savefilestream(filestream_handle, "output.dat", "data/generated/", "byte");<br />
</syntaxhighlight>Text mode adds this line break unconditionally. If a loaded buffer already ends with <code>\r\n</code> and is saved again without new content after it, the file gains another empty line.<br />
<br />
Saving does not close the filestream. The same buffer may be appended or saved again before it is released.<br />
<br />
=== setfilestreamposition() ===<br />
<syntaxhighlight lang="c"><br />
setfilestreamposition(filestream_handle, position);<br />
</syntaxhighlight>Sets the read position to a byte offset. Use <code>0</code> to return to the beginning:<syntaxhighlight lang="c"><br />
setfilestreamposition(filestream_handle, 0);<br />
</syntaxhighlight>The engine does not validate or clamp this value. Negative positions and positions beyond the allocated buffer are invalid and may cause unstable behavior.<br />
<br />
Changing the read position does not affect <code>filestreamappend()</code>, which always writes at the buffer end.<br />
<br />
== Iterating Through Lines ==<br />
OpenBOR does not provide a separate end-of-filestream function. Compare the position before and after <code>filestreamnextline()</code> to detect when no further progress is possible:<syntaxhighlight lang="c" line="1"><br />
void filestream_handle = openfilestream("data/records.txt");<br />
<br />
if (filestream_handle >= 0) {<br />
while (1) {<br />
int current_position = getfilestreamposition(filestream_handle);<br />
<br />
char current_line = getfilestreamline(filestream_handle);<br />
<br />
filestreamnextline(filestream_handle);<br />
<br />
int next_position = getfilestreamposition(filestream_handle);<br />
<br />
if (current_line != "") {<br />
log(current_line + "\n");<br />
}<br />
<br />
if (next_position == current_position) {<br />
break;<br />
}<br />
}<br />
<br />
closefilestream(filestream_handle);<br />
}<br />
</syntaxhighlight>This pattern also tolerates empty lines. <code>filestreamnextline()</code> skips their line-ending characters and continues to the next populated line.<br />
<br />
== Binary Data ==<br />
Byte mode lets scripts work with individual numeric byte values instead of parsed text. This is useful for compact records, custom encodings, byte-level inspection, and data containing non-printing values that are awkward to represent as ordinary strings. Reads return the byte at the current position, while append operations can add byte values directly without converting them to text.<br />
<br />
Byte mode is not currently a complete binary-file interface. Saving determines the output length by scanning for a null terminator, so a byte value of <code>0</code> ends the writable content. Values from <code>1</code> through <code>255</code> can be manipulated and preserved, but files containing embedded null bytes cannot be saved reliably. Use byte mode for controlled byte-oriented formats, and text mode or another native API when arbitrary binary data must be preserved.<br />
<br />
== Practical Guidance ==<br />
<br />
* Check every <code>openfilestream()</code> result for <code>-1</code>.<br />
* Keep handles private to the code that owns their lifecycle when practical.<br />
* Maximum file path length is 511 characters. Be aware that some operating systems impose stricter limits. Windows 11, for example, limits file paths to 260 characters by default. For portability, try to keep file paths reasonable in length.<br />
* Save before closing when changes must persist.<br />
* Close every filestream when it is no longer needed.<br />
* Never use a closed handle or invent a handle index.<br />
* Check the return value from <code>deletefilestream()</code> before assuming a file was removed.<br />
* Close a buffer separately when deleting the file from which it was loaded.<br />
* Use <code>getfilestreamposition()</code> to preserve known-safe positions instead of guessing byte offsets.<br />
* Prefer one logical record per line and whitespace-separated fields when using <code>getfilestreamargument()</code>.<br />
* Use <code>getfilestreamline()</code> when field content may contain spaces.<br />
* Avoid loading unnecessarily large files. Opening a filestream allocates enough memory for the complete file.<br />
* Remember that packfile content is not modified in place. Save changed data to the module's save directory or another writable external path.<br />
<br />
The engine releases any remaining filestream buffers during shutdown, but does not save them automatically or delete their external files. Explicit cleanup keeps ownership clear and allows closed handle slots to be reused during play.<br />
<br />
== See Also ==<br />
<br />
* [[Script Overview]]<br />
* [[:Category:Script Functions|Script Functions]]<br />
* [[Arrays]]<br />
* [[Strings]]<br />
* [[Variables Overview]]<br />
<br />
[[Category:Openbor]]<br />
[[Category:Script]]</div>Dcurrenthttps://chronocrash.com/openbor/wiki/index.php?title=File_Operations&diff=1081File Operations2026-08-24T05:40:17Z<p>Dcurrent: /* getfilestreamargument() */</p>
<hr />
<div>OpenBOR supports file CRUD - create, read, update, and delete - through an API called filestream. Scripts can load external files into memory, read structured text, assemble or revise content, save the result to disk, and remove files that are no longer needed. Common uses include custom configuration, persistent game data, generated model or script files, and data exchanged with external tools.<br />
<br />
Despite the name, an OpenBOR filestream is not a continuously open operating-system file. Instead, OpenBOR filestreams use memory-backed buffers. Opening a file loads its contents into memory, after which reading and editing require no additional disk access or filesystem overhead. Scripts may perform any number of operations at memory speed, then explicitly commit the finished buffer to storage with <code>savefilestream()</code>. <br />
<br />
Each filestream maintains two independent locations:<br />
<br />
* '''Buffer end -''' <code>filestreamappend()</code> always writes here.<br />
* '''Read position -''' Line, argument, byte, and position functions operate here.<br />
<br />
Changing the read position does not change where appended data is written.<blockquote>'''Important:''' Memory buffers and external files have separate lifecycles. <code>closefilestream()</code> releases a buffer without deleting its saved file. <code>deletefilestream()</code> removes an external file without releasing any buffer previously loaded from it.</blockquote><br />
<br />
== Lifecycle ==<br />
Creating, reading, or updating a file normally follows four steps:<br />
<br />
# Create an empty stream with <code>createfilestream()</code>, or load an existing file with <code>openfilestream()</code>.<br />
# Read from the current position or append content to the buffer.<br />
# Call <code>savefilestream()</code> when the buffer should be written to disk.<br />
# Call <code>closefilestream()</code> when the buffer is no longer needed.<br />
<br />
Deletion is independent of this handle lifecycle. Pass a filename directly to <code>deletefilestream()</code>; no stream needs to be open.<br />
{| class="wikitable"<br />
!Operation<br />
!Native support<br />
!Method<br />
|-<br />
|Create<br />
|Yes<br />
|Create an empty buffer, append content, then save it under a filename.<br />
|-<br />
|Read<br />
|Yes<br />
|Open a file, then read its current line, arguments, or byte.<br />
|-<br />
|Update<br />
|Append or rewrite<br />
|Open and append to the loaded buffer, or construct a replacement buffer, then save over the previous file.<br />
|-<br />
|Delete<br />
|Yes<br />
|Pass a filename to <code>deletefilestream()</code> to remove a writable external file.<br />
|}<br />
Saving is explicit. Closing an unsaved stream discards its in-memory changes. Deleting a file does not discard a loaded buffer, so saving that buffer later may recreate the file.<br />
<br />
== Handle and Buffer Model ==<br />
The returned filestream handle is a zero-based index into the engine's filestream collection. Internally, each entry contains:<br />
{| class="wikitable"<br />
!Member<br />
!Purpose<br />
|-<br />
|<code>buf</code><br />
|Allocated memory containing the loaded or constructed data.<br />
|-<br />
|<code>size</code><br />
|Current buffer size and append location.<br />
|-<br />
|<code>pos</code><br />
|Current byte position used by read functions.<br />
|}<br />
Closed entries become available for reuse. Once <code>closefilestream()</code> is called, the old handle is invalid and may later identify a different filestream.<br />
<br />
The engine does not clamp filestream handles or manually assigned positions. Use only handles returned by <code>createfilestream()</code> or successful calls to <code>openfilestream()</code>, and never use a handle after closing it.<br />
<br />
== Walk-through ==<br />
<br />
=== Create and Save ===<br />
The following creates a two-line text file:<syntaxhighlight lang="c" line="1"><br />
void filestream_handle = createfilestream();<br />
<br />
filestreamappend(filestream_handle, "name", 1);<br />
filestreamappend(filestream_handle, "Max");<br />
<br />
filestreamappend(filestream_handle, "score", 0);<br />
filestreamappend(filestream_handle, 125000);<br />
<br />
savefilestream(filestream_handle, "profile.txt");<br />
closefilestream(filestream_handle);<br />
</syntaxhighlight>The default save location is the current module's subdirectory under <code>Saves</code>. Text mode adds a final carriage return and line feed, producing:<pre><br />
name Max<br />
score 125000<br />
</pre>In this example, write type <code>1</code> adds a trailing space after <code>name</code>. Write type <code>0</code> begins a new line before <code>score</code> and then adds a trailing space.<br />
<br />
=== Open and Read ===<br />
Pass a nonzero location value to load from the current module's save directory:<syntaxhighlight lang="c" line="1"><br />
void filestream_handle = openfilestream("profile.txt", 1);<br />
<br />
if (filestream_handle >= 0) {<br />
char player_name = getfilestreamargument(filestream_handle, 1, "string");<br />
<br />
filestreamnextline(filestream_handle);<br />
<br />
int player_score = getfilestreamargument(filestream_handle, 1, "int");<br />
<br />
closefilestream(filestream_handle);<br />
}<br />
</syntaxhighlight>The first argument on each line is index <code>0</code>. The example reads index <code>1</code>, returning <code>"Max"</code> from the first line and <code>125000</code> from the second.<br />
<br />
=== Append and Replace ===<br />
Opening a file loads its existing content into the buffer. Appending new content and saving under the same name rewrites the external file with the expanded buffer:<syntaxhighlight lang="c" line="1"><br />
void filestream_handle = openfilestream("profile.txt", 1);<br />
<br />
if (filestream_handle >= 0) {<br />
/*<br />
* Files written by savefilestream() in text mode already<br />
* end with a line break, so begin the next record directly.<br />
*/<br />
filestreamappend(filestream_handle, "unlocks", 1);<br />
filestreamappend(filestream_handle, 3);<br />
<br />
savefilestream(filestream_handle, "profile.txt");<br />
closefilestream(filestream_handle);<br />
}<br />
</syntaxhighlight><code>savefilestream()</code> opens the destination in write mode and replaces its previous contents. Existing data survives only because <code>openfilestream()</code> first copied that data into the memory buffer.<br />
<br />
Filestreams do not provide insertion, replacement, or removal at an arbitrary read position. To modify existing records, read the source and assemble the desired result in another filestream, then save the replacement over the original filename.<br />
<br />
=== Delete ===<br />
Deletion targets the external file by name rather than a filestream handle:<syntaxhighlight lang="c" line="1"><br />
int deleted = deletefilestream("profile.txt");<br />
<br />
if (!deleted) {<br />
log("Could not delete profile.txt.\n");<br />
}<br />
</syntaxhighlight>The default location is the current module's subdirectory under <code>Saves</code>, matching <code>savefilestream()</code>. Supply the same optional pathname used to save a file when deleting from a custom location:<syntaxhighlight lang="c" line="1"><br />
int deleted = deletefilestream(<br />
"profile.txt",<br />
"data/generated/"<br />
);<br />
</syntaxhighlight>Only the external file is removed. If a filestream already contains data loaded from that file, its memory buffer and handle remain valid until <code>closefilestream()</code> is called.<br />
<br />
== Functions ==<br />
<br />
=== closefilestream() ===<br />
<syntaxhighlight lang="c"><br />
closefilestream(filestream_handle);<br />
</syntaxhighlight>Releases the filestream's allocated buffer. The handle becomes invalid and its collection index may be reused by a later create or open operation.<br />
<br />
This function does not save the buffer and does not delete an external file.<br />
<br />
=== createfilestream() ===<br />
<syntaxhighlight lang="c"><br />
int filestream_handle = createfilestream();<br />
</syntaxhighlight>Allocates an empty memory buffer and returns its handle. The initial read position and content size are both <code>0</code>.<br />
<br />
No external file is created until the buffer is passed to <code>savefilestream()</code>.<br />
<br />
=== deletefilestream() ===<br />
<syntaxhighlight lang="c"><br />
int deleted = deletefilestream(filename[, pathname]);<br />
</syntaxhighlight>Deletes a writable external file and returns <code>1</code> when the operating system confirms deletion. A return value of <code>0</code> means the file could not be deleted, including when the file does not exist, the path is incorrect, or the operating system denies access.<br />
<br />
When <code>pathname</code> is omitted, OpenBOR targets the current module's subdirectory under <code>Saves</code>:<syntaxhighlight lang="c"><br />
int deleted = deletefilestream("profile.txt");<br />
</syntaxhighlight>The optional pathname follows the same rules as <code>savefilestream()</code> and is relative to the engine's working directory:<syntaxhighlight lang="c"><br />
int deleted = deletefilestream( "profile.txt", "data/generated/");<br />
</syntaxhighlight>The pathname is joined directly to the filename. Include the final slash or backslash.<br />
<br />
Deletion operates on external files only and cannot remove content from a packfile. It does not accept a filestream handle, release a memory buffer, or invalidate a handle. Saving a still-open buffer to the same filename after successful deletion creates the file again.<br />
<br />
=== filestreamappend() ===<br />
<syntaxhighlight lang="c"><br />
filestreamappend(filestream_handle, value[, write_type[, value_type]]);<br />
</syntaxhighlight>Converts the supplied value to text and appends it at the end of the buffer. The current read position has no effect on the append location.<br />
{| class="wikitable"<br />
!<code>write_type</code><br />
!Behavior<br />
|-<br />
|Omitted, <code>-1</code>, or any value other than <code>0</code> and <code>1</code><br />
|Appends the value without adding a separator.<br />
|-<br />
|<code>0</code><br />
|Adds <code>\r\n</code> before the value, then adds one trailing space after it.<br />
|-<br />
|<code>1</code><br />
|Appends the value followed by one trailing space.<br />
|}<br />
Write type <code>0</code> starts a new line before the supplied value. Using it for the first value in an empty stream therefore creates an initial blank line.<br />
<br />
Passing <code>"byte"</code> as <code>value_type</code> selects the legacy byte append path:<syntaxhighlight lang="c"><br />
filestreamappend(filestream_handle, byte_value, write_type, "byte");<br />
</syntaxhighlight>See [[File Operations#Binary Data|Binary Data]] before using byte mode.<br />
<br />
=== filestreamnextline() ===<br />
<syntaxhighlight lang="c"><br />
filestreamnextline(filestream_handle);<br />
</syntaxhighlight>Advances the read position from its current location to the next non-line-break byte. The function scans to the end of the current line, then skips all consecutive <code>\r</code> and <code>\n</code> characters.<br />
<br />
Multiple empty lines are skipped as one group. At the end of the buffer, the position does not change.<br />
<br />
=== getfilestreamargument() ===<br />
<br />
<syntaxhighlight lang="c"><br />
mixed result = getfilestreamargument(<br />
filestream_handle,<br />
argument_index,<br />
result_type<br />
[, decode_quotes]<br />
);<br />
</syntaxhighlight><br />
<br />
Reads an argument beginning at the current filestream position without advancing the position. Argument indexes are zero-based.<br />
<br />
The optional <code>decode_quotes</code> parameter controls quote handling. Omit it or pass <code>0</code> for legacy whitespace parsing. Pass any nonzero value for modern quote-aware parsing. See [[File Operations#String|String]] for details and examples.<br />
<br />
{| class="wikitable"<br />
! <code>result_type</code><br />
! Return<br />
|-<br />
| <code>"string"</code><br />
| Argument text.<br />
|-<br />
| <code>"int"</code><br />
| Argument converted to an integer.<br />
|-<br />
| <code>"float"</code><br />
| Argument converted to a decimal value.<br />
|-<br />
| <code>"byte"</code><br />
| Unsigned value of the byte at the current read position. <code>argument_index</code> and <code>decode_quotes</code> are ignored.<br />
|}<br />
<br />
Result type names are case-insensitive.<br />
<br />
=== String ===<br />
<br />
String parsing has two modes selected by the optional <code>decode_quotes</code> parameter. Legacy behavior remains the default so existing modules continue to work without modification. Quote-aware behavior is available by passing a nonzero fourth parameter.<br />
<br />
String results may contain up to <code>MAX_SCRIPT_STRING_LENGTH</code>, currently 65,535 characters - about 36 Standard Academic Pages.<br />
<br />
==== Legacy Parsing ====<br />
<br />
Omitting <code>decode_quotes</code>, or passing <code>0</code>, uses legacy whitespace parsing:<br />
<br />
<syntaxhighlight lang="c"><br />
char value = getfilestreamargument(<br />
filestream_handle,<br />
argument_index,<br />
"string"<br />
);<br />
</syntaxhighlight><br />
<br />
Spaces and tabs always separate arguments. Quotation marks have no special meaning and remain part of the returned text.<br />
<br />
Given this line:<br />
<br />
<pre><br />
name "Max Thunder"<br />
</pre><br />
<br />
Legacy parsing returns <code>"Max</code> at argument index <code>1</code> and <code>Thunder"</code> at argument index <code>2</code>.<br />
<br />
This behavior supports older scripts that read and reconstruct files one whitespace-delimited token at a time. Use <code>getfilestreamline()</code> instead when the complete line and its original formatting must be returned as one string.<br />
<br />
==== Quote-Aware Parsing ====<br />
<br />
Pass a nonzero fourth parameter to enable modern quote-aware parsing:<br />
<br />
<syntaxhighlight lang="c"><br />
char value = getfilestreamargument(<br />
filestream_handle,<br />
argument_index,<br />
"string",<br />
1<br />
);<br />
</syntaxhighlight><br />
<br />
Matching single or double quotes group text into one argument. Opening and closing quote delimiters are discarded from the returned value. Outside quoted spans, spaces and tabs separate arguments, an unquoted line break ends the current record, and <code>#</code> begins a comment.<br />
<br />
Using the previous example, argument index <code>1</code> returns <code>Max Thunder</code> as one string.<br />
<br />
Empty quoted arguments are supported. The maximum string length applies after quote delimiters are removed.<br />
<br />
===== Double Quotes =====<br />
<br />
Enclose multiple-word text in double quotes to group it as a single string.<br />
<br />
<pre><br />
Value: "Hello world"<br />
Result: Hello world<br />
</pre><br />
<br />
Double-quoted spans may appear within an argument and are concatenated with adjacent unquoted text:<br />
<br />
<pre><br />
Value: prefix"two words"suffix<br />
Result: prefixtwo wordssuffix<br />
</pre><br />
<br />
===== Single Quotes =====<br />
<br />
Single quotes may also group text:<br />
<br />
<pre><br />
Value: 'Multiple words'<br />
Result: Multiple words<br />
</pre><br />
<br />
Single quotes begin grouping only at an argument boundary. This preserves apostrophes in ordinary words:<br />
<br />
<pre><br />
Value: It's<br />
Result: It's<br />
</pre><br />
<br />
===== Mixed Quotes =====<br />
<br />
The opposite quote type remains literal inside a quoted span:<br />
<br />
<pre><br />
Value: "Hello, it's a good day."<br />
Result: Hello, it's a good day.<br />
</pre><br />
<br />
<pre><br />
Value: 'She said "hello".'<br />
Result: She said "hello".<br />
</pre><br />
<br />
=== Numeric ===<br />
<br />
Missing or nonnumeric arguments converted with <code>"int"</code> or <code>"float"</code> resolve to <code>0</code>. Validate file structure when zero is also a meaningful value.<br />
<br />
Parsing mode also applies before numeric conversion. Legacy parsing retains quote characters, so a quoted number such as <code>"125"</code> converts to <code>0</code>. Quote-aware parsing removes the delimiters first, allowing the same value to convert to <code>125</code>.<br />
<br />
=== String ===<br />
Matching single or double quotes group text into one argument. Opening and closing quote delimiters are discarded from the returned value. String results may contain up to <code>MAX_SCRIPT_STRING_LENGTH</code>, currently 65,535 characters - about 36 Standard Academic Pages. The limit applies after quote delimiters are removed.<br />
<br />
==== Double Quotes ====<br />
Enclose multiple word tokens in quotes to group as a single string.<syntaxhighlight lang="text"><br />
Value: "Hello world"<br />
<br />
Result: Hello world<br />
</syntaxhighlight>Double-quoted spans may appear within an argument and are concatenated with adjacent unquoted text:<syntaxhighlight lang="text"><br />
Value: prefix"two words"suffix<br />
<br />
Result: prefixtwo wordssuffix<br />
</syntaxhighlight><br />
<br />
==== Single Quotes ====<br />
You may also enclose tokens with single quotes.<syntaxhighlight lang="text"><br />
Value: 'Its'<br />
<br />
Result: Its<br />
</syntaxhighlight>Single quotes begin grouping only at an argument boundary. This preserves apostrophes in ordinary words:<syntaxhighlight lang="text"><br />
Value: It's<br />
<br />
Result: It's<br />
</syntaxhighlight><br />
<br />
==== Mixed Quotes ====<br />
You may mix quote types to preserve quotations within the string. The opposite quote type remains literal inside a quoted span:<syntaxhighlight lang="text"><br />
Value: "Hello, it's a good day."<br />
<br />
Result: Hello, it's a good day.<br />
</syntaxhighlight><syntaxhighlight><br />
Value: 'She said "hello".'<br />
<br />
Result: She said "hello".<br />
</syntaxhighlight><br />
<br />
=== Numeric ===<br />
Missing or nonnumeric arguments converted with <code>"int"</code> or <code>"float"</code> resolve to <code>0</code>. Validate file structure when zero is also a meaningful value.<br />
<br />
=== getfilestreamline() ===<br />
<syntaxhighlight lang="c"><br />
char line = getfilestreamline(filestream_handle);<br />
</syntaxhighlight>Returns text from the current read position through the next carriage return, line feed, or end of buffer. The line-ending characters are not included.<br />
<br />
This function does not advance the read position. Repeated calls return the same line until <code>filestreamnextline()</code> or <code>setfilestreamposition()</code> changes the position.<br />
<br />
An empty line and the end of the buffer both return an empty string.<br />
<br />
=== getfilestreamposition() ===<br />
<syntaxhighlight lang="c"><br />
int position = getfilestreamposition(filestream_handle);<br />
</syntaxhighlight>Returns the current read position as a byte offset from the beginning of the buffer. The value is not a line number.<br />
<br />
Positions may be stored and supplied later to <code>setfilestreamposition()</code>.<br />
<br />
=== openfilestream() ===<br />
<syntaxhighlight lang="c"><br />
int filestream_handle = openfilestream(filename[, location]);<br />
</syntaxhighlight>Loads an existing file into memory, sets its read position to <code>0</code>, and returns the filestream handle. The complete file is loaded at once.<br />
{| class="wikitable"<br />
!<code>location</code><br />
!Source<br />
|-<br />
|Omitted or <code>0</code><br />
|Module-relative path. OpenBOR checks loose files and the current packfile.<br />
|-<br />
|Any nonzero value<br />
|Current module's subdirectory under <code>Saves</code>.<br />
|}<br />
For a module named <code>Example.pak</code>, the following reads <code>Saves/Example/profile.txt</code>:<syntaxhighlight lang="c"><br />
int filestream_handle = openfilestream("profile.txt", 1);<br />
</syntaxhighlight><br />
The function returns <code>-1</code> when the requested file does not exist or cannot be opened. Always validate the result before using it:<syntaxhighlight lang="c" line="1"><br />
void filestream_handle = openfilestream("data/config.txt");<br />
<br />
if (filestream_handle < 0) {<br />
return;<br />
}<br />
</syntaxhighlight><br />
<br />
=== savefilestream() ===<br />
<syntaxhighlight lang="c"><br />
savefilestream( filestream_handle, filename [, pathname [, save_type]] );<br />
</syntaxhighlight>Writes the current buffer to an external file. The destination is opened in write mode, so an existing file at the same path is replaced.<br />
<br />
When <code>pathname</code> is omitted, OpenBOR writes to the current module's subdirectory under <code>Saves</code>:<syntaxhighlight lang="c"><br />
savefilestream(filestream_handle, "profile.txt");<br />
</syntaxhighlight>An optional custom pathname is relative to the engine's working directory:<syntaxhighlight lang="c"><br />
savefilestream( filestream_handle, "profile.txt", "data/generated/" );<br />
</syntaxhighlight>The custom pathname is joined directly to the filename. Include the final slash or backslash in <code>pathname</code>.<br />
<br />
Default save paths are recommended for portable persistent data. Custom relative paths may resolve differently between platforms and launch environments.<br />
<br />
Text mode writes the buffer and then adds <code>\r\n</code> to the end of the file. Passing <code>"byte"</code> as <code>save_type</code> suppresses that final line break:<syntaxhighlight lang="c"><br />
savefilestream(filestream_handle, "output.dat", "data/generated/", "byte");<br />
</syntaxhighlight>Text mode adds this line break unconditionally. If a loaded buffer already ends with <code>\r\n</code> and is saved again without new content after it, the file gains another empty line.<br />
<br />
Saving does not close the filestream. The same buffer may be appended or saved again before it is released.<br />
<br />
=== setfilestreamposition() ===<br />
<syntaxhighlight lang="c"><br />
setfilestreamposition(filestream_handle, position);<br />
</syntaxhighlight>Sets the read position to a byte offset. Use <code>0</code> to return to the beginning:<syntaxhighlight lang="c"><br />
setfilestreamposition(filestream_handle, 0);<br />
</syntaxhighlight>The engine does not validate or clamp this value. Negative positions and positions beyond the allocated buffer are invalid and may cause unstable behavior.<br />
<br />
Changing the read position does not affect <code>filestreamappend()</code>, which always writes at the buffer end.<br />
<br />
== Iterating Through Lines ==<br />
OpenBOR does not provide a separate end-of-filestream function. Compare the position before and after <code>filestreamnextline()</code> to detect when no further progress is possible:<syntaxhighlight lang="c" line="1"><br />
void filestream_handle = openfilestream("data/records.txt");<br />
<br />
if (filestream_handle >= 0) {<br />
while (1) {<br />
int current_position = getfilestreamposition(filestream_handle);<br />
<br />
char current_line = getfilestreamline(filestream_handle);<br />
<br />
filestreamnextline(filestream_handle);<br />
<br />
int next_position = getfilestreamposition(filestream_handle);<br />
<br />
if (current_line != "") {<br />
log(current_line + "\n");<br />
}<br />
<br />
if (next_position == current_position) {<br />
break;<br />
}<br />
}<br />
<br />
closefilestream(filestream_handle);<br />
}<br />
</syntaxhighlight>This pattern also tolerates empty lines. <code>filestreamnextline()</code> skips their line-ending characters and continues to the next populated line.<br />
<br />
== Binary Data ==<br />
Byte mode lets scripts work with individual numeric byte values instead of parsed text. This is useful for compact records, custom encodings, byte-level inspection, and data containing non-printing values that are awkward to represent as ordinary strings. Reads return the byte at the current position, while append operations can add byte values directly without converting them to text.<br />
<br />
Byte mode is not currently a complete binary-file interface. Saving determines the output length by scanning for a null terminator, so a byte value of <code>0</code> ends the writable content. Values from <code>1</code> through <code>255</code> can be manipulated and preserved, but files containing embedded null bytes cannot be saved reliably. Use byte mode for controlled byte-oriented formats, and text mode or another native API when arbitrary binary data must be preserved.<br />
<br />
== Practical Guidance ==<br />
<br />
* Check every <code>openfilestream()</code> result for <code>-1</code>.<br />
* Keep handles private to the code that owns their lifecycle when practical.<br />
* Maximum file path length is 511 characters. Be aware that some operating systems impose stricter limits. Windows 11, for example, limits file paths to 260 characters by default. For portability, try to keep file paths reasonable in length.<br />
* Save before closing when changes must persist.<br />
* Close every filestream when it is no longer needed.<br />
* Never use a closed handle or invent a handle index.<br />
* Check the return value from <code>deletefilestream()</code> before assuming a file was removed.<br />
* Close a buffer separately when deleting the file from which it was loaded.<br />
* Use <code>getfilestreamposition()</code> to preserve known-safe positions instead of guessing byte offsets.<br />
* Prefer one logical record per line and whitespace-separated fields when using <code>getfilestreamargument()</code>.<br />
* Use <code>getfilestreamline()</code> when field content may contain spaces.<br />
* Avoid loading unnecessarily large files. Opening a filestream allocates enough memory for the complete file.<br />
* Remember that packfile content is not modified in place. Save changed data to the module's save directory or another writable external path.<br />
<br />
The engine releases any remaining filestream buffers during shutdown, but does not save them automatically or delete their external files. Explicit cleanup keeps ownership clear and allows closed handle slots to be reused during play.<br />
<br />
== See Also ==<br />
<br />
* [[Script Overview]]<br />
* [[:Category:Script Functions|Script Functions]]<br />
* [[Arrays]]<br />
* [[Strings]]<br />
* [[Variables Overview]]<br />
<br />
[[Category:Openbor]]<br />
[[Category:Script]]</div>Dcurrenthttps://chronocrash.com/openbor/wiki/index.php?title=File_Operations&diff=1080File Operations2026-08-24T05:30:58Z<p>Dcurrent: /* getfilestreamargument() */</p>
<hr />
<div>OpenBOR supports file CRUD - create, read, update, and delete - through an API called filestream. Scripts can load external files into memory, read structured text, assemble or revise content, save the result to disk, and remove files that are no longer needed. Common uses include custom configuration, persistent game data, generated model or script files, and data exchanged with external tools.<br />
<br />
Despite the name, an OpenBOR filestream is not a continuously open operating-system file. Instead, OpenBOR filestreams use memory-backed buffers. Opening a file loads its contents into memory, after which reading and editing require no additional disk access or filesystem overhead. Scripts may perform any number of operations at memory speed, then explicitly commit the finished buffer to storage with <code>savefilestream()</code>. <br />
<br />
Each filestream maintains two independent locations:<br />
<br />
* '''Buffer end -''' <code>filestreamappend()</code> always writes here.<br />
* '''Read position -''' Line, argument, byte, and position functions operate here.<br />
<br />
Changing the read position does not change where appended data is written.<blockquote>'''Important:''' Memory buffers and external files have separate lifecycles. <code>closefilestream()</code> releases a buffer without deleting its saved file. <code>deletefilestream()</code> removes an external file without releasing any buffer previously loaded from it.</blockquote><br />
<br />
== Lifecycle ==<br />
Creating, reading, or updating a file normally follows four steps:<br />
<br />
# Create an empty stream with <code>createfilestream()</code>, or load an existing file with <code>openfilestream()</code>.<br />
# Read from the current position or append content to the buffer.<br />
# Call <code>savefilestream()</code> when the buffer should be written to disk.<br />
# Call <code>closefilestream()</code> when the buffer is no longer needed.<br />
<br />
Deletion is independent of this handle lifecycle. Pass a filename directly to <code>deletefilestream()</code>; no stream needs to be open.<br />
{| class="wikitable"<br />
!Operation<br />
!Native support<br />
!Method<br />
|-<br />
|Create<br />
|Yes<br />
|Create an empty buffer, append content, then save it under a filename.<br />
|-<br />
|Read<br />
|Yes<br />
|Open a file, then read its current line, arguments, or byte.<br />
|-<br />
|Update<br />
|Append or rewrite<br />
|Open and append to the loaded buffer, or construct a replacement buffer, then save over the previous file.<br />
|-<br />
|Delete<br />
|Yes<br />
|Pass a filename to <code>deletefilestream()</code> to remove a writable external file.<br />
|}<br />
Saving is explicit. Closing an unsaved stream discards its in-memory changes. Deleting a file does not discard a loaded buffer, so saving that buffer later may recreate the file.<br />
<br />
== Handle and Buffer Model ==<br />
The returned filestream handle is a zero-based index into the engine's filestream collection. Internally, each entry contains:<br />
{| class="wikitable"<br />
!Member<br />
!Purpose<br />
|-<br />
|<code>buf</code><br />
|Allocated memory containing the loaded or constructed data.<br />
|-<br />
|<code>size</code><br />
|Current buffer size and append location.<br />
|-<br />
|<code>pos</code><br />
|Current byte position used by read functions.<br />
|}<br />
Closed entries become available for reuse. Once <code>closefilestream()</code> is called, the old handle is invalid and may later identify a different filestream.<br />
<br />
The engine does not clamp filestream handles or manually assigned positions. Use only handles returned by <code>createfilestream()</code> or successful calls to <code>openfilestream()</code>, and never use a handle after closing it.<br />
<br />
== Walk-through ==<br />
<br />
=== Create and Save ===<br />
The following creates a two-line text file:<syntaxhighlight lang="c" line="1"><br />
void filestream_handle = createfilestream();<br />
<br />
filestreamappend(filestream_handle, "name", 1);<br />
filestreamappend(filestream_handle, "Max");<br />
<br />
filestreamappend(filestream_handle, "score", 0);<br />
filestreamappend(filestream_handle, 125000);<br />
<br />
savefilestream(filestream_handle, "profile.txt");<br />
closefilestream(filestream_handle);<br />
</syntaxhighlight>The default save location is the current module's subdirectory under <code>Saves</code>. Text mode adds a final carriage return and line feed, producing:<pre><br />
name Max<br />
score 125000<br />
</pre>In this example, write type <code>1</code> adds a trailing space after <code>name</code>. Write type <code>0</code> begins a new line before <code>score</code> and then adds a trailing space.<br />
<br />
=== Open and Read ===<br />
Pass a nonzero location value to load from the current module's save directory:<syntaxhighlight lang="c" line="1"><br />
void filestream_handle = openfilestream("profile.txt", 1);<br />
<br />
if (filestream_handle >= 0) {<br />
char player_name = getfilestreamargument(filestream_handle, 1, "string");<br />
<br />
filestreamnextline(filestream_handle);<br />
<br />
int player_score = getfilestreamargument(filestream_handle, 1, "int");<br />
<br />
closefilestream(filestream_handle);<br />
}<br />
</syntaxhighlight>The first argument on each line is index <code>0</code>. The example reads index <code>1</code>, returning <code>"Max"</code> from the first line and <code>125000</code> from the second.<br />
<br />
=== Append and Replace ===<br />
Opening a file loads its existing content into the buffer. Appending new content and saving under the same name rewrites the external file with the expanded buffer:<syntaxhighlight lang="c" line="1"><br />
void filestream_handle = openfilestream("profile.txt", 1);<br />
<br />
if (filestream_handle >= 0) {<br />
/*<br />
* Files written by savefilestream() in text mode already<br />
* end with a line break, so begin the next record directly.<br />
*/<br />
filestreamappend(filestream_handle, "unlocks", 1);<br />
filestreamappend(filestream_handle, 3);<br />
<br />
savefilestream(filestream_handle, "profile.txt");<br />
closefilestream(filestream_handle);<br />
}<br />
</syntaxhighlight><code>savefilestream()</code> opens the destination in write mode and replaces its previous contents. Existing data survives only because <code>openfilestream()</code> first copied that data into the memory buffer.<br />
<br />
Filestreams do not provide insertion, replacement, or removal at an arbitrary read position. To modify existing records, read the source and assemble the desired result in another filestream, then save the replacement over the original filename.<br />
<br />
=== Delete ===<br />
Deletion targets the external file by name rather than a filestream handle:<syntaxhighlight lang="c" line="1"><br />
int deleted = deletefilestream("profile.txt");<br />
<br />
if (!deleted) {<br />
log("Could not delete profile.txt.\n");<br />
}<br />
</syntaxhighlight>The default location is the current module's subdirectory under <code>Saves</code>, matching <code>savefilestream()</code>. Supply the same optional pathname used to save a file when deleting from a custom location:<syntaxhighlight lang="c" line="1"><br />
int deleted = deletefilestream(<br />
"profile.txt",<br />
"data/generated/"<br />
);<br />
</syntaxhighlight>Only the external file is removed. If a filestream already contains data loaded from that file, its memory buffer and handle remain valid until <code>closefilestream()</code> is called.<br />
<br />
== Functions ==<br />
<br />
=== closefilestream() ===<br />
<syntaxhighlight lang="c"><br />
closefilestream(filestream_handle);<br />
</syntaxhighlight>Releases the filestream's allocated buffer. The handle becomes invalid and its collection index may be reused by a later create or open operation.<br />
<br />
This function does not save the buffer and does not delete an external file.<br />
<br />
=== createfilestream() ===<br />
<syntaxhighlight lang="c"><br />
int filestream_handle = createfilestream();<br />
</syntaxhighlight>Allocates an empty memory buffer and returns its handle. The initial read position and content size are both <code>0</code>.<br />
<br />
No external file is created until the buffer is passed to <code>savefilestream()</code>.<br />
<br />
=== deletefilestream() ===<br />
<syntaxhighlight lang="c"><br />
int deleted = deletefilestream(filename[, pathname]);<br />
</syntaxhighlight>Deletes a writable external file and returns <code>1</code> when the operating system confirms deletion. A return value of <code>0</code> means the file could not be deleted, including when the file does not exist, the path is incorrect, or the operating system denies access.<br />
<br />
When <code>pathname</code> is omitted, OpenBOR targets the current module's subdirectory under <code>Saves</code>:<syntaxhighlight lang="c"><br />
int deleted = deletefilestream("profile.txt");<br />
</syntaxhighlight>The optional pathname follows the same rules as <code>savefilestream()</code> and is relative to the engine's working directory:<syntaxhighlight lang="c"><br />
int deleted = deletefilestream( "profile.txt", "data/generated/");<br />
</syntaxhighlight>The pathname is joined directly to the filename. Include the final slash or backslash.<br />
<br />
Deletion operates on external files only and cannot remove content from a packfile. It does not accept a filestream handle, release a memory buffer, or invalidate a handle. Saving a still-open buffer to the same filename after successful deletion creates the file again.<br />
<br />
=== filestreamappend() ===<br />
<syntaxhighlight lang="c"><br />
filestreamappend(filestream_handle, value[, write_type[, value_type]]);<br />
</syntaxhighlight>Converts the supplied value to text and appends it at the end of the buffer. The current read position has no effect on the append location.<br />
{| class="wikitable"<br />
!<code>write_type</code><br />
!Behavior<br />
|-<br />
|Omitted, <code>-1</code>, or any value other than <code>0</code> and <code>1</code><br />
|Appends the value without adding a separator.<br />
|-<br />
|<code>0</code><br />
|Adds <code>\r\n</code> before the value, then adds one trailing space after it.<br />
|-<br />
|<code>1</code><br />
|Appends the value followed by one trailing space.<br />
|}<br />
Write type <code>0</code> starts a new line before the supplied value. Using it for the first value in an empty stream therefore creates an initial blank line.<br />
<br />
Passing <code>"byte"</code> as <code>value_type</code> selects the legacy byte append path:<syntaxhighlight lang="c"><br />
filestreamappend(filestream_handle, byte_value, write_type, "byte");<br />
</syntaxhighlight>See [[File Operations#Binary Data|Binary Data]] before using byte mode.<br />
<br />
=== filestreamnextline() ===<br />
<syntaxhighlight lang="c"><br />
filestreamnextline(filestream_handle);<br />
</syntaxhighlight>Advances the read position from its current location to the next non-line-break byte. The function scans to the end of the current line, then skips all consecutive <code>\r</code> and <code>\n</code> characters.<br />
<br />
Multiple empty lines are skipped as one group. At the end of the buffer, the position does not change.<br />
<br />
=== getfilestreamargument() ===<br />
<br />
<syntaxhighlight lang="c" line="1"><br />
mixed result = getfilestreamargument(<br />
filestream_handle,<br />
argument_index,<br />
result_type<br />
[, decode_quotes]<br />
);<br />
</syntaxhighlight><br />
<br />
Reads an argument beginning at the current filestream position without advancing the position. Argument indexes are zero-based.<br />
<br />
The optional <code>decode_quotes</code> parameter selects how arguments and quotation marks are interpreted. It preserves compatibility with modules written for the historical filestream parser while providing modern quote-aware parsing when requested.<br />
<br />
{| class="wikitable"<br />
! <code>decode_quotes</code><br />
! Parsing behavior<br />
|-<br />
| Omitted or <code>0</code><br />
| Legacy whitespace parsing. Spaces and tabs always separate arguments. Quotation marks are treated as ordinary characters and remain in the returned value.<br />
|-<br />
| Any nonzero value<br />
| Modern quote-aware parsing. Matching quotes group text into one argument, and the surrounding quote delimiters are removed from the returned value.<br />
|}<br />
<br />
Existing three-parameter calls retain the historical behavior:<br />
<br />
<syntaxhighlight lang="c" line="1"><br />
char value = getfilestreamargument(<br />
filestream_handle,<br />
argument_index,<br />
"string"<br />
);<br />
</syntaxhighlight><br />
<br />
Pass a nonzero fourth parameter to request quote-aware parsing:<br />
<br />
<syntaxhighlight lang="c" line="1"><br />
char value = getfilestreamargument(<br />
filestream_handle,<br />
argument_index,<br />
"string",<br />
1<br />
);<br />
</syntaxhighlight><br />
<br />
{| class="wikitable"<br />
! <code>result_type</code><br />
! Return<br />
|-<br />
| <code>"string"</code><br />
| Argument text.<br />
|-<br />
| <code>"int"</code><br />
| Argument converted to an integer.<br />
|-<br />
| <code>"float"</code><br />
| Argument converted to a decimal value.<br />
|-<br />
| <code>"byte"</code><br />
| Unsigned value of the byte at the current read position. <code>argument_index</code> and <code>decode_quotes</code> are ignored.<br />
|}<br />
<br />
Result type names are case-insensitive.<br />
<br />
==== Legacy Parsing ====<br />
<br />
Legacy parsing is the default for compatibility with existing modules. Spaces and tabs always separate arguments, even when they appear between quotation marks. Quote characters remain part of the returned text.<br />
<br />
Given this line:<br />
<br />
<pre><br />
msgid "How To Play"<br />
</pre><br />
<br />
The following calls return:<br />
<br />
{| class="wikitable"<br />
! Call<br />
! Result<br />
|-<br />
| <code>getfilestreamargument(file, 0, "string")</code><br />
| <code>msgid</code><br />
|-<br />
| <code>getfilestreamargument(file, 1, "string")</code><br />
| <code>"How</code><br />
|-<br />
| <code>getfilestreamargument(file, 2, "string")</code><br />
| <code>To</code><br />
|-<br />
| <code>getfilestreamargument(file, 3, "string")</code><br />
| <code>Play"</code><br />
|}<br />
<br />
This behavior allows older scripts that read, process, and reconstruct text files one whitespace-delimited token at a time to continue working without modification.<br />
<br />
==== Quote-Aware Parsing ====<br />
<br />
Pass a nonzero fourth parameter to enable modern quote-aware parsing:<br />
<br />
<syntaxhighlight lang="c"><br />
char value = getfilestreamargument(file, 1, "string", 1);<br />
</syntaxhighlight><br />
<br />
Using the same source line:<br />
<br />
<pre><br />
msgid "How To Play"<br />
</pre><br />
<br />
The call returns:<br />
<br />
<pre><br />
How To Play<br />
</pre><br />
<br />
The complete quoted phrase occupies argument index <code>1</code>, and the surrounding quotation marks are removed.<br />
<br />
Outside quoted spans, spaces and tabs separate arguments, an unquoted line break ends the current record, and <code>#</code> begins a comment.<br />
<br />
===== Double Quotes =====<br />
<br />
Double quotes may group text containing whitespace:<br />
<br />
<pre><br />
name "Max Thunder"<br />
</pre><br />
<br />
<syntaxhighlight lang="c"><br />
char name = getfilestreamargument(file, 1, "string", 1);<br />
</syntaxhighlight><br />
<br />
Result:<br />
<br />
<pre><br />
Max Thunder<br />
</pre><br />
<br />
Double-quoted spans may appear within an argument and are concatenated with adjacent unquoted text:<br />
<br />
<pre><br />
prefix"two words"suffix<br />
</pre><br />
<br />
Result:<br />
<br />
<pre><br />
prefixtwo wordssuffix<br />
</pre><br />
<br />
===== Single Quotes =====<br />
<br />
Single quotes may also group text:<br />
<br />
<pre><br />
'Multiple words'<br />
</pre><br />
<br />
Result:<br />
<br />
<pre><br />
Multiple words<br />
</pre><br />
<br />
Single quotes begin grouping only at an argument boundary. This preserves apostrophes in ordinary words:<br />
<br />
<pre><br />
It's<br />
</pre><br />
<br />
Result:<br />
<br />
<pre><br />
It's<br />
</pre><br />
<br />
===== Mixed Quotes =====<br />
<br />
The opposite quote type remains literal inside a quoted span:<br />
<br />
<pre><br />
"Hello, it's a good day."<br />
</pre><br />
<br />
Result:<br />
<br />
<pre><br />
Hello, it's a good day.<br />
</pre><br />
<br />
<pre><br />
'She said "hello".'<br />
</pre><br />
<br />
Result:<br />
<br />
<pre><br />
She said "hello".<br />
</pre><br />
<br />
==== Numeric Results ====<br />
<br />
Missing or nonnumeric arguments converted with <code>"int"</code> or <code>"float"</code> resolve to <code>0</code>. Validate the file structure when zero is also a meaningful value.<br />
<br />
Quote handling occurs before numeric conversion when modern parsing is enabled. For example:<br />
<br />
<pre><br />
value "125"<br />
</pre><br />
<br />
<syntaxhighlight lang="c"><br />
int legacy_value = getfilestreamargument(file, 1, "int");<br />
int decoded_value = getfilestreamargument(file, 1, "int", 1);<br />
</syntaxhighlight><br />
<br />
The legacy result is <code>0</code> because the returned token begins with a quotation mark. The quote-aware result is <code>125</code> because the delimiters are removed before conversion.<br />
<br />
String results may contain up to <code>MAX_SCRIPT_STRING_LENGTH</code>, currently 65,535 characters. The limit applies to the value returned to the script.<br />
* Omit <code>decode_quotes</code> when compatibility with historical whitespace-token behavior is required.<br />
* Pass <code>1</code> as the fourth <code>getfilestreamargument()</code> parameter when quoted fields should be treated as complete arguments.<br />
* Use <code>getfilestreamline()</code> when the exact line, including quotation marks and spacing, must be preserved.<br />
<br />
=== String ===<br />
Matching single or double quotes group text into one argument. Opening and closing quote delimiters are discarded from the returned value. String results may contain up to <code>MAX_SCRIPT_STRING_LENGTH</code>, currently 65,535 characters - about 36 Standard Academic Pages. The limit applies after quote delimiters are removed.<br />
<br />
==== Double Quotes ====<br />
Enclose multiple word tokens in quotes to group as a single string.<syntaxhighlight lang="text"><br />
Value: "Hello world"<br />
<br />
Result: Hello world<br />
</syntaxhighlight>Double-quoted spans may appear within an argument and are concatenated with adjacent unquoted text:<syntaxhighlight lang="text"><br />
Value: prefix"two words"suffix<br />
<br />
Result: prefixtwo wordssuffix<br />
</syntaxhighlight><br />
<br />
==== Single Quotes ====<br />
You may also enclose tokens with single quotes.<syntaxhighlight lang="text"><br />
Value: 'Its'<br />
<br />
Result: Its<br />
</syntaxhighlight>Single quotes begin grouping only at an argument boundary. This preserves apostrophes in ordinary words:<syntaxhighlight lang="text"><br />
Value: It's<br />
<br />
Result: It's<br />
</syntaxhighlight><br />
<br />
==== Mixed Quotes ====<br />
You may mix quote types to preserve quotations within the string. The opposite quote type remains literal inside a quoted span:<syntaxhighlight lang="text"><br />
Value: "Hello, it's a good day."<br />
<br />
Result: Hello, it's a good day.<br />
</syntaxhighlight><syntaxhighlight><br />
Value: 'She said "hello".'<br />
<br />
Result: She said "hello".<br />
</syntaxhighlight><br />
<br />
=== Numeric ===<br />
Missing or nonnumeric arguments converted with <code>"int"</code> or <code>"float"</code> resolve to <code>0</code>. Validate file structure when zero is also a meaningful value.<br />
<br />
=== getfilestreamline() ===<br />
<syntaxhighlight lang="c"><br />
char line = getfilestreamline(filestream_handle);<br />
</syntaxhighlight>Returns text from the current read position through the next carriage return, line feed, or end of buffer. The line-ending characters are not included.<br />
<br />
This function does not advance the read position. Repeated calls return the same line until <code>filestreamnextline()</code> or <code>setfilestreamposition()</code> changes the position.<br />
<br />
An empty line and the end of the buffer both return an empty string.<br />
<br />
=== getfilestreamposition() ===<br />
<syntaxhighlight lang="c"><br />
int position = getfilestreamposition(filestream_handle);<br />
</syntaxhighlight>Returns the current read position as a byte offset from the beginning of the buffer. The value is not a line number.<br />
<br />
Positions may be stored and supplied later to <code>setfilestreamposition()</code>.<br />
<br />
=== openfilestream() ===<br />
<syntaxhighlight lang="c"><br />
int filestream_handle = openfilestream(filename[, location]);<br />
</syntaxhighlight>Loads an existing file into memory, sets its read position to <code>0</code>, and returns the filestream handle. The complete file is loaded at once.<br />
{| class="wikitable"<br />
!<code>location</code><br />
!Source<br />
|-<br />
|Omitted or <code>0</code><br />
|Module-relative path. OpenBOR checks loose files and the current packfile.<br />
|-<br />
|Any nonzero value<br />
|Current module's subdirectory under <code>Saves</code>.<br />
|}<br />
For a module named <code>Example.pak</code>, the following reads <code>Saves/Example/profile.txt</code>:<syntaxhighlight lang="c"><br />
int filestream_handle = openfilestream("profile.txt", 1);<br />
</syntaxhighlight><br />
The function returns <code>-1</code> when the requested file does not exist or cannot be opened. Always validate the result before using it:<syntaxhighlight lang="c" line="1"><br />
void filestream_handle = openfilestream("data/config.txt");<br />
<br />
if (filestream_handle < 0) {<br />
return;<br />
}<br />
</syntaxhighlight><br />
<br />
=== savefilestream() ===<br />
<syntaxhighlight lang="c"><br />
savefilestream( filestream_handle, filename [, pathname [, save_type]] );<br />
</syntaxhighlight>Writes the current buffer to an external file. The destination is opened in write mode, so an existing file at the same path is replaced.<br />
<br />
When <code>pathname</code> is omitted, OpenBOR writes to the current module's subdirectory under <code>Saves</code>:<syntaxhighlight lang="c"><br />
savefilestream(filestream_handle, "profile.txt");<br />
</syntaxhighlight>An optional custom pathname is relative to the engine's working directory:<syntaxhighlight lang="c"><br />
savefilestream( filestream_handle, "profile.txt", "data/generated/" );<br />
</syntaxhighlight>The custom pathname is joined directly to the filename. Include the final slash or backslash in <code>pathname</code>.<br />
<br />
Default save paths are recommended for portable persistent data. Custom relative paths may resolve differently between platforms and launch environments.<br />
<br />
Text mode writes the buffer and then adds <code>\r\n</code> to the end of the file. Passing <code>"byte"</code> as <code>save_type</code> suppresses that final line break:<syntaxhighlight lang="c"><br />
savefilestream(filestream_handle, "output.dat", "data/generated/", "byte");<br />
</syntaxhighlight>Text mode adds this line break unconditionally. If a loaded buffer already ends with <code>\r\n</code> and is saved again without new content after it, the file gains another empty line.<br />
<br />
Saving does not close the filestream. The same buffer may be appended or saved again before it is released.<br />
<br />
=== setfilestreamposition() ===<br />
<syntaxhighlight lang="c"><br />
setfilestreamposition(filestream_handle, position);<br />
</syntaxhighlight>Sets the read position to a byte offset. Use <code>0</code> to return to the beginning:<syntaxhighlight lang="c"><br />
setfilestreamposition(filestream_handle, 0);<br />
</syntaxhighlight>The engine does not validate or clamp this value. Negative positions and positions beyond the allocated buffer are invalid and may cause unstable behavior.<br />
<br />
Changing the read position does not affect <code>filestreamappend()</code>, which always writes at the buffer end.<br />
<br />
== Iterating Through Lines ==<br />
OpenBOR does not provide a separate end-of-filestream function. Compare the position before and after <code>filestreamnextline()</code> to detect when no further progress is possible:<syntaxhighlight lang="c" line="1"><br />
void filestream_handle = openfilestream("data/records.txt");<br />
<br />
if (filestream_handle >= 0) {<br />
while (1) {<br />
int current_position = getfilestreamposition(filestream_handle);<br />
<br />
char current_line = getfilestreamline(filestream_handle);<br />
<br />
filestreamnextline(filestream_handle);<br />
<br />
int next_position = getfilestreamposition(filestream_handle);<br />
<br />
if (current_line != "") {<br />
log(current_line + "\n");<br />
}<br />
<br />
if (next_position == current_position) {<br />
break;<br />
}<br />
}<br />
<br />
closefilestream(filestream_handle);<br />
}<br />
</syntaxhighlight>This pattern also tolerates empty lines. <code>filestreamnextline()</code> skips their line-ending characters and continues to the next populated line.<br />
<br />
== Binary Data ==<br />
Byte mode lets scripts work with individual numeric byte values instead of parsed text. This is useful for compact records, custom encodings, byte-level inspection, and data containing non-printing values that are awkward to represent as ordinary strings. Reads return the byte at the current position, while append operations can add byte values directly without converting them to text.<br />
<br />
Byte mode is not currently a complete binary-file interface. Saving determines the output length by scanning for a null terminator, so a byte value of <code>0</code> ends the writable content. Values from <code>1</code> through <code>255</code> can be manipulated and preserved, but files containing embedded null bytes cannot be saved reliably. Use byte mode for controlled byte-oriented formats, and text mode or another native API when arbitrary binary data must be preserved.<br />
<br />
== Practical Guidance ==<br />
<br />
* Check every <code>openfilestream()</code> result for <code>-1</code>.<br />
* Keep handles private to the code that owns their lifecycle when practical.<br />
* Maximum file path length is 511 characters. Be aware that some operating systems impose stricter limits. Windows 11, for example, limits file paths to 260 characters by default. For portability, try to keep file paths reasonable in length.<br />
* Save before closing when changes must persist.<br />
* Close every filestream when it is no longer needed.<br />
* Never use a closed handle or invent a handle index.<br />
* Check the return value from <code>deletefilestream()</code> before assuming a file was removed.<br />
* Close a buffer separately when deleting the file from which it was loaded.<br />
* Use <code>getfilestreamposition()</code> to preserve known-safe positions instead of guessing byte offsets.<br />
* Prefer one logical record per line and whitespace-separated fields when using <code>getfilestreamargument()</code>.<br />
* Use <code>getfilestreamline()</code> when field content may contain spaces.<br />
* Avoid loading unnecessarily large files. Opening a filestream allocates enough memory for the complete file.<br />
* Remember that packfile content is not modified in place. Save changed data to the module's save directory or another writable external path.<br />
<br />
The engine releases any remaining filestream buffers during shutdown, but does not save them automatically or delete their external files. Explicit cleanup keeps ownership clear and allows closed handle slots to be reused during play.<br />
<br />
== See Also ==<br />
<br />
* [[Script Overview]]<br />
* [[:Category:Script Functions|Script Functions]]<br />
* [[Arrays]]<br />
* [[Strings]]<br />
* [[Variables Overview]]<br />
<br />
[[Category:Openbor]]<br />
[[Category:Script]]</div>Dcurrenthttps://chronocrash.com/openbor/wiki/index.php?title=File_Operations&diff=1079File Operations2026-08-24T05:08:16Z<p>Dcurrent: /* getfilestreamargument() */</p>
<hr />
<div>OpenBOR supports file CRUD - create, read, update, and delete - through an API called filestream. Scripts can load external files into memory, read structured text, assemble or revise content, save the result to disk, and remove files that are no longer needed. Common uses include custom configuration, persistent game data, generated model or script files, and data exchanged with external tools.<br />
<br />
Despite the name, an OpenBOR filestream is not a continuously open operating-system file. Instead, OpenBOR filestreams use memory-backed buffers. Opening a file loads its contents into memory, after which reading and editing require no additional disk access or filesystem overhead. Scripts may perform any number of operations at memory speed, then explicitly commit the finished buffer to storage with <code>savefilestream()</code>. <br />
<br />
Each filestream maintains two independent locations:<br />
<br />
* '''Buffer end -''' <code>filestreamappend()</code> always writes here.<br />
* '''Read position -''' Line, argument, byte, and position functions operate here.<br />
<br />
Changing the read position does not change where appended data is written.<blockquote>'''Important:''' Memory buffers and external files have separate lifecycles. <code>closefilestream()</code> releases a buffer without deleting its saved file. <code>deletefilestream()</code> removes an external file without releasing any buffer previously loaded from it.</blockquote><br />
<br />
== Lifecycle ==<br />
Creating, reading, or updating a file normally follows four steps:<br />
<br />
# Create an empty stream with <code>createfilestream()</code>, or load an existing file with <code>openfilestream()</code>.<br />
# Read from the current position or append content to the buffer.<br />
# Call <code>savefilestream()</code> when the buffer should be written to disk.<br />
# Call <code>closefilestream()</code> when the buffer is no longer needed.<br />
<br />
Deletion is independent of this handle lifecycle. Pass a filename directly to <code>deletefilestream()</code>; no stream needs to be open.<br />
{| class="wikitable"<br />
!Operation<br />
!Native support<br />
!Method<br />
|-<br />
|Create<br />
|Yes<br />
|Create an empty buffer, append content, then save it under a filename.<br />
|-<br />
|Read<br />
|Yes<br />
|Open a file, then read its current line, arguments, or byte.<br />
|-<br />
|Update<br />
|Append or rewrite<br />
|Open and append to the loaded buffer, or construct a replacement buffer, then save over the previous file.<br />
|-<br />
|Delete<br />
|Yes<br />
|Pass a filename to <code>deletefilestream()</code> to remove a writable external file.<br />
|}<br />
Saving is explicit. Closing an unsaved stream discards its in-memory changes. Deleting a file does not discard a loaded buffer, so saving that buffer later may recreate the file.<br />
<br />
== Handle and Buffer Model ==<br />
The returned filestream handle is a zero-based index into the engine's filestream collection. Internally, each entry contains:<br />
{| class="wikitable"<br />
!Member<br />
!Purpose<br />
|-<br />
|<code>buf</code><br />
|Allocated memory containing the loaded or constructed data.<br />
|-<br />
|<code>size</code><br />
|Current buffer size and append location.<br />
|-<br />
|<code>pos</code><br />
|Current byte position used by read functions.<br />
|}<br />
Closed entries become available for reuse. Once <code>closefilestream()</code> is called, the old handle is invalid and may later identify a different filestream.<br />
<br />
The engine does not clamp filestream handles or manually assigned positions. Use only handles returned by <code>createfilestream()</code> or successful calls to <code>openfilestream()</code>, and never use a handle after closing it.<br />
<br />
== Walk-through ==<br />
<br />
=== Create and Save ===<br />
The following creates a two-line text file:<syntaxhighlight lang="c" line="1"><br />
void filestream_handle = createfilestream();<br />
<br />
filestreamappend(filestream_handle, "name", 1);<br />
filestreamappend(filestream_handle, "Max");<br />
<br />
filestreamappend(filestream_handle, "score", 0);<br />
filestreamappend(filestream_handle, 125000);<br />
<br />
savefilestream(filestream_handle, "profile.txt");<br />
closefilestream(filestream_handle);<br />
</syntaxhighlight>The default save location is the current module's subdirectory under <code>Saves</code>. Text mode adds a final carriage return and line feed, producing:<pre><br />
name Max<br />
score 125000<br />
</pre>In this example, write type <code>1</code> adds a trailing space after <code>name</code>. Write type <code>0</code> begins a new line before <code>score</code> and then adds a trailing space.<br />
<br />
=== Open and Read ===<br />
Pass a nonzero location value to load from the current module's save directory:<syntaxhighlight lang="c" line="1"><br />
void filestream_handle = openfilestream("profile.txt", 1);<br />
<br />
if (filestream_handle >= 0) {<br />
char player_name = getfilestreamargument(filestream_handle, 1, "string");<br />
<br />
filestreamnextline(filestream_handle);<br />
<br />
int player_score = getfilestreamargument(filestream_handle, 1, "int");<br />
<br />
closefilestream(filestream_handle);<br />
}<br />
</syntaxhighlight>The first argument on each line is index <code>0</code>. The example reads index <code>1</code>, returning <code>"Max"</code> from the first line and <code>125000</code> from the second.<br />
<br />
=== Append and Replace ===<br />
Opening a file loads its existing content into the buffer. Appending new content and saving under the same name rewrites the external file with the expanded buffer:<syntaxhighlight lang="c" line="1"><br />
void filestream_handle = openfilestream("profile.txt", 1);<br />
<br />
if (filestream_handle >= 0) {<br />
/*<br />
* Files written by savefilestream() in text mode already<br />
* end with a line break, so begin the next record directly.<br />
*/<br />
filestreamappend(filestream_handle, "unlocks", 1);<br />
filestreamappend(filestream_handle, 3);<br />
<br />
savefilestream(filestream_handle, "profile.txt");<br />
closefilestream(filestream_handle);<br />
}<br />
</syntaxhighlight><code>savefilestream()</code> opens the destination in write mode and replaces its previous contents. Existing data survives only because <code>openfilestream()</code> first copied that data into the memory buffer.<br />
<br />
Filestreams do not provide insertion, replacement, or removal at an arbitrary read position. To modify existing records, read the source and assemble the desired result in another filestream, then save the replacement over the original filename.<br />
<br />
=== Delete ===<br />
Deletion targets the external file by name rather than a filestream handle:<syntaxhighlight lang="c" line="1"><br />
int deleted = deletefilestream("profile.txt");<br />
<br />
if (!deleted) {<br />
log("Could not delete profile.txt.\n");<br />
}<br />
</syntaxhighlight>The default location is the current module's subdirectory under <code>Saves</code>, matching <code>savefilestream()</code>. Supply the same optional pathname used to save a file when deleting from a custom location:<syntaxhighlight lang="c" line="1"><br />
int deleted = deletefilestream(<br />
"profile.txt",<br />
"data/generated/"<br />
);<br />
</syntaxhighlight>Only the external file is removed. If a filestream already contains data loaded from that file, its memory buffer and handle remain valid until <code>closefilestream()</code> is called.<br />
<br />
== Functions ==<br />
<br />
=== closefilestream() ===<br />
<syntaxhighlight lang="c"><br />
closefilestream(filestream_handle);<br />
</syntaxhighlight>Releases the filestream's allocated buffer. The handle becomes invalid and its collection index may be reused by a later create or open operation.<br />
<br />
This function does not save the buffer and does not delete an external file.<br />
<br />
=== createfilestream() ===<br />
<syntaxhighlight lang="c"><br />
int filestream_handle = createfilestream();<br />
</syntaxhighlight>Allocates an empty memory buffer and returns its handle. The initial read position and content size are both <code>0</code>.<br />
<br />
No external file is created until the buffer is passed to <code>savefilestream()</code>.<br />
<br />
=== deletefilestream() ===<br />
<syntaxhighlight lang="c"><br />
int deleted = deletefilestream(filename[, pathname]);<br />
</syntaxhighlight>Deletes a writable external file and returns <code>1</code> when the operating system confirms deletion. A return value of <code>0</code> means the file could not be deleted, including when the file does not exist, the path is incorrect, or the operating system denies access.<br />
<br />
When <code>pathname</code> is omitted, OpenBOR targets the current module's subdirectory under <code>Saves</code>:<syntaxhighlight lang="c"><br />
int deleted = deletefilestream("profile.txt");<br />
</syntaxhighlight>The optional pathname follows the same rules as <code>savefilestream()</code> and is relative to the engine's working directory:<syntaxhighlight lang="c"><br />
int deleted = deletefilestream( "profile.txt", "data/generated/");<br />
</syntaxhighlight>The pathname is joined directly to the filename. Include the final slash or backslash.<br />
<br />
Deletion operates on external files only and cannot remove content from a packfile. It does not accept a filestream handle, release a memory buffer, or invalidate a handle. Saving a still-open buffer to the same filename after successful deletion creates the file again.<br />
<br />
=== filestreamappend() ===<br />
<syntaxhighlight lang="c"><br />
filestreamappend(filestream_handle, value[, write_type[, value_type]]);<br />
</syntaxhighlight>Converts the supplied value to text and appends it at the end of the buffer. The current read position has no effect on the append location.<br />
{| class="wikitable"<br />
!<code>write_type</code><br />
!Behavior<br />
|-<br />
|Omitted, <code>-1</code>, or any value other than <code>0</code> and <code>1</code><br />
|Appends the value without adding a separator.<br />
|-<br />
|<code>0</code><br />
|Adds <code>\r\n</code> before the value, then adds one trailing space after it.<br />
|-<br />
|<code>1</code><br />
|Appends the value followed by one trailing space.<br />
|}<br />
Write type <code>0</code> starts a new line before the supplied value. Using it for the first value in an empty stream therefore creates an initial blank line.<br />
<br />
Passing <code>"byte"</code> as <code>value_type</code> selects the legacy byte append path:<syntaxhighlight lang="c"><br />
filestreamappend(filestream_handle, byte_value, write_type, "byte");<br />
</syntaxhighlight>See [[File Operations#Binary Data|Binary Data]] before using byte mode.<br />
<br />
=== filestreamnextline() ===<br />
<syntaxhighlight lang="c"><br />
filestreamnextline(filestream_handle);<br />
</syntaxhighlight>Advances the read position from its current location to the next non-line-break byte. The function scans to the end of the current line, then skips all consecutive <code>\r</code> and <code>\n</code> characters.<br />
<br />
Multiple empty lines are skipped as one group. At the end of the buffer, the position does not change.<br />
<br />
=== getfilestreamargument() ===<br />
<br />
<syntaxhighlight lang="c"><br />
mixed result = getfilestreamargument(<br />
filestream_handle,<br />
argument_index,<br />
result_type<br />
[, decode_quotes]<br />
);<br />
</syntaxhighlight><br />
<br />
Reads an argument beginning at the current filestream position without advancing the position. Argument indexes are zero-based.<br />
<br />
The optional <code>decode_quotes</code> parameter selects how arguments and quotation marks are interpreted. It preserves compatibility with modules written for the historical filestream parser while providing modern quote-aware parsing when requested.<br />
<br />
{| class="wikitable"<br />
! <code>decode_quotes</code><br />
! Parsing behavior<br />
|-<br />
| Omitted or <code>0</code><br />
| Legacy whitespace parsing. Spaces and tabs always separate arguments. Quotation marks are treated as ordinary characters and remain in the returned value.<br />
|-<br />
| Any nonzero value<br />
| Modern quote-aware parsing. Matching quotes group text into one argument, and the surrounding quote delimiters are removed from the returned value.<br />
|}<br />
<br />
Existing three-parameter calls retain the historical behavior:<br />
<br />
<syntaxhighlight lang="c"><br />
char value = getfilestreamargument(<br />
filestream_handle,<br />
argument_index,<br />
"string"<br />
);<br />
</syntaxhighlight><br />
<br />
Pass a nonzero fourth parameter to request quote-aware parsing:<br />
<br />
<syntaxhighlight lang="c"><br />
char value = getfilestreamargument(<br />
filestream_handle,<br />
argument_index,<br />
"string",<br />
1<br />
);<br />
</syntaxhighlight><br />
<br />
{| class="wikitable"<br />
! <code>result_type</code><br />
! Return<br />
|-<br />
| <code>"string"</code><br />
| Argument text.<br />
|-<br />
| <code>"int"</code><br />
| Argument converted to an integer.<br />
|-<br />
| <code>"float"</code><br />
| Argument converted to a decimal value.<br />
|-<br />
| <code>"byte"</code><br />
| Unsigned value of the byte at the current read position. <code>argument_index</code> and <code>decode_quotes</code> are ignored.<br />
|}<br />
<br />
Result type names are case-insensitive.<br />
<br />
==== Legacy Parsing ====<br />
<br />
Legacy parsing is the default for compatibility with existing modules. Spaces and tabs always separate arguments, even when they appear between quotation marks. Quote characters remain part of the returned text.<br />
<br />
Given this line:<br />
<br />
<pre><br />
msgid "How To Play"<br />
</pre><br />
<br />
The following calls return:<br />
<br />
{| class="wikitable"<br />
! Call<br />
! Result<br />
|-<br />
| <code>getfilestreamargument(file, 0, "string")</code><br />
| <code>msgid</code><br />
|-<br />
| <code>getfilestreamargument(file, 1, "string")</code><br />
| <code>"How</code><br />
|-<br />
| <code>getfilestreamargument(file, 2, "string")</code><br />
| <code>To</code><br />
|-<br />
| <code>getfilestreamargument(file, 3, "string")</code><br />
| <code>Play"</code><br />
|}<br />
<br />
This behavior allows older scripts that read, process, and reconstruct text files one whitespace-delimited token at a time to continue working without modification.<br />
<br />
==== Quote-Aware Parsing ====<br />
<br />
Pass a nonzero fourth parameter to enable modern quote-aware parsing:<br />
<br />
<syntaxhighlight lang="c"><br />
char value = getfilestreamargument(file, 1, "string", 1);<br />
</syntaxhighlight><br />
<br />
Using the same source line:<br />
<br />
<pre><br />
msgid "How To Play"<br />
</pre><br />
<br />
The call returns:<br />
<br />
<pre><br />
How To Play<br />
</pre><br />
<br />
The complete quoted phrase occupies argument index <code>1</code>, and the surrounding quotation marks are removed.<br />
<br />
Outside quoted spans, spaces and tabs separate arguments, an unquoted line break ends the current record, and <code>#</code> begins a comment.<br />
<br />
===== Double Quotes =====<br />
<br />
Double quotes may group text containing whitespace:<br />
<br />
<pre><br />
name "Max Thunder"<br />
</pre><br />
<br />
<syntaxhighlight lang="c"><br />
char name = getfilestreamargument(file, 1, "string", 1);<br />
</syntaxhighlight><br />
<br />
Result:<br />
<br />
<pre><br />
Max Thunder<br />
</pre><br />
<br />
Double-quoted spans may appear within an argument and are concatenated with adjacent unquoted text:<br />
<br />
<pre><br />
prefix"two words"suffix<br />
</pre><br />
<br />
Result:<br />
<br />
<pre><br />
prefixtwo wordssuffix<br />
</pre><br />
<br />
===== Single Quotes =====<br />
<br />
Single quotes may also group text:<br />
<br />
<pre><br />
'Multiple words'<br />
</pre><br />
<br />
Result:<br />
<br />
<pre><br />
Multiple words<br />
</pre><br />
<br />
Single quotes begin grouping only at an argument boundary. This preserves apostrophes in ordinary words:<br />
<br />
<pre><br />
It's<br />
</pre><br />
<br />
Result:<br />
<br />
<pre><br />
It's<br />
</pre><br />
<br />
===== Mixed Quotes =====<br />
<br />
The opposite quote type remains literal inside a quoted span:<br />
<br />
<pre><br />
"Hello, it's a good day."<br />
</pre><br />
<br />
Result:<br />
<br />
<pre><br />
Hello, it's a good day.<br />
</pre><br />
<br />
<pre><br />
'She said "hello".'<br />
</pre><br />
<br />
Result:<br />
<br />
<pre><br />
She said "hello".<br />
</pre><br />
<br />
==== Numeric Results ====<br />
<br />
Missing or nonnumeric arguments converted with <code>"int"</code> or <code>"float"</code> resolve to <code>0</code>. Validate the file structure when zero is also a meaningful value.<br />
<br />
Quote handling occurs before numeric conversion when modern parsing is enabled. For example:<br />
<br />
<pre><br />
value "125"<br />
</pre><br />
<br />
<syntaxhighlight lang="c"><br />
int legacy_value = getfilestreamargument(file, 1, "int");<br />
int decoded_value = getfilestreamargument(file, 1, "int", 1);<br />
</syntaxhighlight><br />
<br />
The legacy result is <code>0</code> because the returned token begins with a quotation mark. The quote-aware result is <code>125</code> because the delimiters are removed before conversion.<br />
<br />
String results may contain up to <code>MAX_SCRIPT_STRING_LENGTH</code>, currently 65,535 characters. The limit applies to the value returned to the script.<br />
<br />
<!-- Replace the existing getfilestreamargument() guidance bullets under Practical Guidance with the following. --><br />
<br />
* Omit <code>decode_quotes</code> when compatibility with historical whitespace-token behavior is required.<br />
* Pass <code>1</code> as the fourth <code>getfilestreamargument()</code> parameter when quoted fields should be treated as complete arguments.<br />
* Use <code>getfilestreamline()</code> when the exact line, including quotation marks and spacing, must be preserved.<br />
<br />
=== String ===<br />
Matching single or double quotes group text into one argument. Opening and closing quote delimiters are discarded from the returned value. String results may contain up to <code>MAX_SCRIPT_STRING_LENGTH</code>, currently 65,535 characters - about 36 Standard Academic Pages. The limit applies after quote delimiters are removed.<br />
<br />
==== Double Quotes ====<br />
Enclose multiple word tokens in quotes to group as a single string.<syntaxhighlight lang="text"><br />
Value: "Hello world"<br />
<br />
Result: Hello world<br />
</syntaxhighlight>Double-quoted spans may appear within an argument and are concatenated with adjacent unquoted text:<syntaxhighlight lang="text"><br />
Value: prefix"two words"suffix<br />
<br />
Result: prefixtwo wordssuffix<br />
</syntaxhighlight><br />
<br />
==== Single Quotes ====<br />
You may also enclose tokens with single quotes.<syntaxhighlight lang="text"><br />
Value: 'Its'<br />
<br />
Result: Its<br />
</syntaxhighlight>Single quotes begin grouping only at an argument boundary. This preserves apostrophes in ordinary words:<syntaxhighlight lang="text"><br />
Value: It's<br />
<br />
Result: It's<br />
</syntaxhighlight><br />
<br />
==== Mixed Quotes ====<br />
You may mix quote types to preserve quotations within the string. The opposite quote type remains literal inside a quoted span:<syntaxhighlight lang="text"><br />
Value: "Hello, it's a good day."<br />
<br />
Result: Hello, it's a good day.<br />
</syntaxhighlight><syntaxhighlight><br />
Value: 'She said "hello".'<br />
<br />
Result: She said "hello".<br />
</syntaxhighlight><br />
<br />
=== Numeric ===<br />
Missing or nonnumeric arguments converted with <code>"int"</code> or <code>"float"</code> resolve to <code>0</code>. Validate file structure when zero is also a meaningful value.<br />
<br />
=== getfilestreamline() ===<br />
<syntaxhighlight lang="c"><br />
char line = getfilestreamline(filestream_handle);<br />
</syntaxhighlight>Returns text from the current read position through the next carriage return, line feed, or end of buffer. The line-ending characters are not included.<br />
<br />
This function does not advance the read position. Repeated calls return the same line until <code>filestreamnextline()</code> or <code>setfilestreamposition()</code> changes the position.<br />
<br />
An empty line and the end of the buffer both return an empty string.<br />
<br />
=== getfilestreamposition() ===<br />
<syntaxhighlight lang="c"><br />
int position = getfilestreamposition(filestream_handle);<br />
</syntaxhighlight>Returns the current read position as a byte offset from the beginning of the buffer. The value is not a line number.<br />
<br />
Positions may be stored and supplied later to <code>setfilestreamposition()</code>.<br />
<br />
=== openfilestream() ===<br />
<syntaxhighlight lang="c"><br />
int filestream_handle = openfilestream(filename[, location]);<br />
</syntaxhighlight>Loads an existing file into memory, sets its read position to <code>0</code>, and returns the filestream handle. The complete file is loaded at once.<br />
{| class="wikitable"<br />
!<code>location</code><br />
!Source<br />
|-<br />
|Omitted or <code>0</code><br />
|Module-relative path. OpenBOR checks loose files and the current packfile.<br />
|-<br />
|Any nonzero value<br />
|Current module's subdirectory under <code>Saves</code>.<br />
|}<br />
For a module named <code>Example.pak</code>, the following reads <code>Saves/Example/profile.txt</code>:<syntaxhighlight lang="c"><br />
int filestream_handle = openfilestream("profile.txt", 1);<br />
</syntaxhighlight><br />
The function returns <code>-1</code> when the requested file does not exist or cannot be opened. Always validate the result before using it:<syntaxhighlight lang="c" line="1"><br />
void filestream_handle = openfilestream("data/config.txt");<br />
<br />
if (filestream_handle < 0) {<br />
return;<br />
}<br />
</syntaxhighlight><br />
<br />
=== savefilestream() ===<br />
<syntaxhighlight lang="c"><br />
savefilestream( filestream_handle, filename [, pathname [, save_type]] );<br />
</syntaxhighlight>Writes the current buffer to an external file. The destination is opened in write mode, so an existing file at the same path is replaced.<br />
<br />
When <code>pathname</code> is omitted, OpenBOR writes to the current module's subdirectory under <code>Saves</code>:<syntaxhighlight lang="c"><br />
savefilestream(filestream_handle, "profile.txt");<br />
</syntaxhighlight>An optional custom pathname is relative to the engine's working directory:<syntaxhighlight lang="c"><br />
savefilestream( filestream_handle, "profile.txt", "data/generated/" );<br />
</syntaxhighlight>The custom pathname is joined directly to the filename. Include the final slash or backslash in <code>pathname</code>.<br />
<br />
Default save paths are recommended for portable persistent data. Custom relative paths may resolve differently between platforms and launch environments.<br />
<br />
Text mode writes the buffer and then adds <code>\r\n</code> to the end of the file. Passing <code>"byte"</code> as <code>save_type</code> suppresses that final line break:<syntaxhighlight lang="c"><br />
savefilestream(filestream_handle, "output.dat", "data/generated/", "byte");<br />
</syntaxhighlight>Text mode adds this line break unconditionally. If a loaded buffer already ends with <code>\r\n</code> and is saved again without new content after it, the file gains another empty line.<br />
<br />
Saving does not close the filestream. The same buffer may be appended or saved again before it is released.<br />
<br />
=== setfilestreamposition() ===<br />
<syntaxhighlight lang="c"><br />
setfilestreamposition(filestream_handle, position);<br />
</syntaxhighlight>Sets the read position to a byte offset. Use <code>0</code> to return to the beginning:<syntaxhighlight lang="c"><br />
setfilestreamposition(filestream_handle, 0);<br />
</syntaxhighlight>The engine does not validate or clamp this value. Negative positions and positions beyond the allocated buffer are invalid and may cause unstable behavior.<br />
<br />
Changing the read position does not affect <code>filestreamappend()</code>, which always writes at the buffer end.<br />
<br />
== Iterating Through Lines ==<br />
OpenBOR does not provide a separate end-of-filestream function. Compare the position before and after <code>filestreamnextline()</code> to detect when no further progress is possible:<syntaxhighlight lang="c" line="1"><br />
void filestream_handle = openfilestream("data/records.txt");<br />
<br />
if (filestream_handle >= 0) {<br />
while (1) {<br />
int current_position = getfilestreamposition(filestream_handle);<br />
<br />
char current_line = getfilestreamline(filestream_handle);<br />
<br />
filestreamnextline(filestream_handle);<br />
<br />
int next_position = getfilestreamposition(filestream_handle);<br />
<br />
if (current_line != "") {<br />
log(current_line + "\n");<br />
}<br />
<br />
if (next_position == current_position) {<br />
break;<br />
}<br />
}<br />
<br />
closefilestream(filestream_handle);<br />
}<br />
</syntaxhighlight>This pattern also tolerates empty lines. <code>filestreamnextline()</code> skips their line-ending characters and continues to the next populated line.<br />
<br />
== Binary Data ==<br />
Byte mode lets scripts work with individual numeric byte values instead of parsed text. This is useful for compact records, custom encodings, byte-level inspection, and data containing non-printing values that are awkward to represent as ordinary strings. Reads return the byte at the current position, while append operations can add byte values directly without converting them to text.<br />
<br />
Byte mode is not currently a complete binary-file interface. Saving determines the output length by scanning for a null terminator, so a byte value of <code>0</code> ends the writable content. Values from <code>1</code> through <code>255</code> can be manipulated and preserved, but files containing embedded null bytes cannot be saved reliably. Use byte mode for controlled byte-oriented formats, and text mode or another native API when arbitrary binary data must be preserved.<br />
<br />
== Practical Guidance ==<br />
<br />
* Check every <code>openfilestream()</code> result for <code>-1</code>.<br />
* Keep handles private to the code that owns their lifecycle when practical.<br />
* Maximum file path length is 511 characters. Be aware that some operating systems impose stricter limits. Windows 11, for example, limits file paths to 260 characters by default. For portability, try to keep file paths reasonable in length.<br />
* Save before closing when changes must persist.<br />
* Close every filestream when it is no longer needed.<br />
* Never use a closed handle or invent a handle index.<br />
* Check the return value from <code>deletefilestream()</code> before assuming a file was removed.<br />
* Close a buffer separately when deleting the file from which it was loaded.<br />
* Use <code>getfilestreamposition()</code> to preserve known-safe positions instead of guessing byte offsets.<br />
* Prefer one logical record per line and whitespace-separated fields when using <code>getfilestreamargument()</code>.<br />
* Use <code>getfilestreamline()</code> when field content may contain spaces.<br />
* Avoid loading unnecessarily large files. Opening a filestream allocates enough memory for the complete file.<br />
* Remember that packfile content is not modified in place. Save changed data to the module's save directory or another writable external path.<br />
<br />
The engine releases any remaining filestream buffers during shutdown, but does not save them automatically or delete their external files. Explicit cleanup keeps ownership clear and allows closed handle slots to be reused during play.<br />
<br />
== See Also ==<br />
<br />
* [[Script Overview]]<br />
* [[:Category:Script Functions|Script Functions]]<br />
* [[Arrays]]<br />
* [[Strings]]<br />
* [[Variables Overview]]<br />
<br />
[[Category:Openbor]]<br />
[[Category:Script]]</div>Dcurrenthttps://chronocrash.com/openbor/wiki/index.php?title=Script_Overview&diff=1078Script Overview2026-08-23T19:11:55Z<p>Dcurrent: /* Script Entry Points */</p>
<hr />
<div>== Introduction ==<br />
OpenBOR includes a C-based scripting engine that allows creators to build customized or all new functionality into their games. Scripts may execute in response to a wide range of engine events, including animation-frame updates, engine cycles, timer ticks, collisions, damage, key input, and many others. Creators can implement scripts through native define-file paths, user-defined libraries, or code inserted directly into level files and model sheets.<br />
<br />
Alongside its native function library, the OpenBOR scripting engine supports the <code>#include</code> directive. An optional, memory-efficient <code>#import</code> directive is also available when only function references are needed. These directives allow creators to build reusable custom libraries, then call their functions from any appropriate script event.<br />
<br />
Scripts can also perform create, read, update, and delete operations on external data files at runtime. This includes working with content such as model sheets, configuration data, and even other script files.<br />
<br />
In practical terms, OpenBOR places virtually no limit on the game mechanics creators can implement. If you can imagine it and write the logic, you can build it.<br />
<br />
== Basics ==<br />
<br />
=== Syntax ===<br />
OpenBOR Script uses syntax similar to C, with several notable differences:<br />
<br />
'''Weak typing:''' OpenBOR Script is weakly typed. Variables are stored as variants, and the engine changes their types as needed. Type prefixes indicate the intended data type, but do not enforce it by default. Functions declared as void may still return values. Strong typing may optionally be enforced with type guards. See Variables and Type Guards for details.<br />
<br />
'''Preprocessor directives:''' Standard C preprocessor directives such as <code>#include</code>, <code>#define</code>, and <code>#ifdef</code> are available. OpenBOR Script also provides an additional custom memory saving <code>#import</code> directive implementation.<br />
<br />
'''String concatenation:''' The <code>+</code> operator may be used to combine strings:<syntaxhighlight lang="c" line="1"><br />
void string_a = "Hello "<br />
void string_b = "world!"<br />
<br />
void string_c = string_a + string_b;<br />
log(string_c); //"Hello world!"<br />
</syntaxhighlight>'''Assignment:''' During assignment, both the value and type of the right-hand variant are copied to the left-hand variant. No automatic type validation is performed, so creators should take care when assigning values between variables.<br />
<br />
=== Operators ===<br />
<br />
{| class="wikitable"<br />
! Category<br />
! Operators<br />
|-<br />
| Arithmetic<br />
| <code>+</code>, <code>-</code>, <code>*</code>, <code>/</code>, <code>%</code><br />
|-<br />
| Increment and decrement<br />
| <code>++</code>, <code>--</code><br />
|-<br />
| Assignment<br />
| <code>=</code>, <code>+=</code>, <code>-=</code>, <code>*=</code>, <code>/=</code>, <code>%=</code><br />
|-<br />
| Comparison<br />
| <code>==</code>, <code>!=</code>, <code>></code>, <code><</code>, <code>>=</code>, <code><=</code><br />
|-<br />
| Logical<br />
| <code>!</code>, <code>&&</code>, <code><code><nowiki>||</nowiki></code><br />
|-<br />
| Bitwise<br />
| <code>&</code>, <code>|<code>&</code>, <code><nowiki>|</nowiki></code>, <code>^</code>, <code>~</code>, <code><<</code>, <code>>></code><br />
|-<br />
| Bitwise assignment<br />
| <code>&=</code>, <code>|<code>&=</code>, <code><nowiki>|=</nowiki></code>, <code>^=</code>, <code><<=</code>, <code>>>=</code><br />
|-<br />
| Conditional<br />
| <code>?:</code><br />
|-<br />
| Grouping and access<br />
| <code>()</code>, <code>.</code><br />
|}<br />
<br />
=== Control Flow ===<br />
<br />
* do<br />
* while<br />
* for<br />
* break<br />
* if<br />
* else<br />
* continue<br />
* switch<br />
* case<br />
* return<br />
=== Preprocessor Directives ===<br />
<br />
* #define<br />
* #ifdef<br />
* #ifndef<br />
* #endif<br />
* #include<br />
* #import<br />
<br />
<code>#import</code> is an OpenBOR-specific directive. Unlike <code>#include</code>, which copies the contents of a file into the current script, <code>#import</code> imports references to the file's functions without copying its contents. This can significantly reduce memory usage when sharing reusable function libraries across multiple scripts. <br />
<br />
=== Native Functions ===<br />
In addition to the operators described above, OpenBOR provides a suite of [[:Category:Script Functions|native functions]] that give scripts direct control over engine primitives and systems. These functions allow creators to inspect, modify, replace, or extend engine behavior while also assisting with game logic, graphics generation, mathematical calculations, data handling, and other common scripting tasks.<br />
<br />
== Script Entry Points ==<br />
Every OpenBOR script except for [[Animationscript|animation]] contains one required entry-point function, <code>main()</code>, and may also define two optional lifecycle functions, <code>oncreate()</code> and <code>ondestroy()</code>. <br />
<br />
=== main() ===<br />
The engine executes <code>main()</code> whenever the script’s associated event fires. Before execution, the engine automatically populates a collection of local variables containing information relevant to that event. Available variables depend on the script type and triggering event. For example, a collision script may receive references to the participating entities, while an input script may receive information about the player and activated controls.<syntaxhighlight lang="c" line="1">void main() {<br />
// Do stuff here.<br />
}</syntaxhighlight><br />
=== oncreate() ===<br />
The engine executes <code>oncreate()</code> when the script instance is created. This function may be used to initialize variables, allocate resources, or perform other setup required before the script begins responding to events.<syntaxhighlight lang="c" line="1">void oncreate() {<br />
// Do stuff here.<br />
}</syntaxhighlight><br />
=== ondestroy() ===<br />
The engine executes <code>ondestroy()</code> when the script instance is destroyed. This function may be used to release resources, save state, or perform other cleanup associated with the script instance.<br />
<br />
<syntaxhighlight lang="c" line="1"><br />
void ondestroy() {<br />
// Do stuff here.<br />
}<br />
</syntaxhighlight><br />
[[Category:Openbor]]<br />
[[Category:Script]]</div>Dcurrenthttps://chronocrash.com/openbor/wiki/index.php?title=Main_Page&diff=1077Main Page2026-08-22T04:02:12Z<p>Dcurrent: /* Why OpenBOR? */</p>
<hr />
<div>== Introduction ==<br />
<br />
=== What is OpenBOR? ===<br />
OpenBOR is a royalty-free, open-source engine for sprite-based games. It combines a complete native game framework - including controls, movement, combat, artificial intelligence, levels, audio, menus, saving, and local multiplayer - with an integrated C-like scripting language that can extend or replace nearly every system.<br />
<br />
OpenBOR specializes in side-scrolling action games such as Double Dragon and Streets of Rage, but its three-dimensional game world, configurable simulation, declarative object system, and scriptable graphics pipeline also support platformers, shooters, role-playing games, puzzle games, and other genres.<br />
<br />
Beginners can build complete games primarily from assets and configuration. Advanced creators can manipulate engine objects, replace native behavior, construct rendering pipelines, and even compile new script programs while a module is running.<br />
<br />
=== Why OpenBOR? ===<br />
What sets OpenBOR apart is how far it extends in both directions. Creators do not need to build their own asset handling, controls, movement, artificial intelligence, collision and combat logic, audio playback, or other foundational systems. Everything is integrated and ready to use. Gather the assets and a fully functional game can be running within hours.<br />
<br />
At the opposite extreme, OpenBOR exposes low-level primitives and engine objects through configuration and script. Creators can inspect runtime state, customize selected behavior, replace complete subsystems, or build new ones without modifying engine source or depending on third-party plugins. Native functionality is therefore a starting point, not a boundary.<br />
<br />
* '''Complete native gameplay''' - Controls, movement, gravity, level trees, platforms, combat, blocking, grabbing, throwing, artificial intelligence, cameras, audio, menus, HUDs, and saving work without custom code.<br />
* '''[[Script Overview|Engine-wide scripting]]''' - Object APIs and [[:Category:Script Events|more than 70 event hooks]] expose input, animation, movement, collision, damage, spawning, audio, drawing, and other runtime systems for inspection, modification, or replacement.<br />
* '''[[Time|High-resolution simulation]]''' - The configurable logical clock runs at 200 Hz by default and remains independent of display updates.<br />
* '''[[Geometry Overview|Three-dimensional sprite worlds]]''' - Floating-point X, Y, and Z geometry provides subpixel movement, terrain, altitude, and depth sorting.<br />
* '''[[Collision|Declarative combat collision]]''' - Indexed three-dimensional attack and body boxes carry damage, reaction, motion, status, and presentation behavior.<br />
* '''[[Factions|Composable relationships]]''' - Four independent 52-bit faction masks provide hardware-speed membership, hostility, direct-damage, and indirect-damage rules.<br />
* '''[[Subscreens|Recursive graphics composition]]''' - Script-created subscreens support nested rendering, layer capture, transformations, masks, split screens, and feedback effects.<br />
* '''[[Runtime Script Compilation|Runtime metaprogramming]]''' - Modules can load and combine source files, compile them into independently owned programs, retain persistent state, execute them repeatedly, and replace them during play.<br />
* '''Optimized performance''' - Native systems, high-frequency simulation, and script integration are engineered to maintain steady frame rates and butter-smooth motion with dozens or hundreds of active objects.<br />
<br />
== Getting Started ==<br />
<br />
'''[https://www.chronocrash.com/forum/resources/openbor.1/ Download OpenBOR]''' | '''[https://www.chronocrash.com/forum/resources/categories/samples-and-tutorials.5/?prefix_id=3 Start Building]''' | '''[[:Category:Openbor|Browse the Reference]]''' | '''[https://chronocrash.com Visit the Community]''' | '''[https://github.com/DCurrent/openbor View the Source]'''<br />
<br />
This wiki is the comprehensive technical reference for OpenBOR, but please note it is not intended as a walk-through. For more in-depth instruction, consult the tutorials and guides available through the [https://chronocrash.com/forum ChronoCrash community].<br />
<br />
=== Guides and Resources ===<br />
<br />
* [[OpenBOR Overview]] – General overview of OpenBOR functionality and runtime layout.<br />
* [[:Category:Openbor|OpenBOR Hub]] – Main jumping off point for categories and individual wiki articles.<br />
* [[:Category:OpenBOR Index|OpenBOR Index]] – Simple index of OpenBOR commands, settings, and functions.<br />
* [[Legacy Manual]] – Archival monolithic manual.<br />
* [https://chronocrash.com/ ChronoCrash] – OpenBOR’s home community, including its help forum, downloadable games, and in-depth tutorials.<br />
* [https://github.com/DCurrent/openbor OpenBOR Repository] – Public-facing OpenBOR code base.<br />
<br />
== Development Environment ==<br />
<br />
=== Essential Tools ===<br />
<br />
The following tools are needed to begin building games with OpenBOR. You will need a [https://chronocrash.com/forum ChronoCrash community] account to download some resources.<br />
<br />
* [https://www.chronocrash.com/forum/resources/categories/engine.3/ OpenBOR engine executable] – The latest stable engine release.<br />
* '''[https://www.chronocrash.com/forum/resources/neo-edit-pack.2/ Edit Pack]''' – Tools for packing and unpacking OpenBOR game modules.<br />
* '''Development environment''' – OpenBOR uses a combination of text files and optional script files to configure game functionality. Any text editor may be used. [https://code.visualstudio.com/ Visual Studio Code] is recommended, together with [https://github.com Git] or another version-control system for managing project files.<br />
* '''Graphics software''' – Any graphics-editing application capable of exporting <code>.png</code> images. [https://www.adobe.com Adobe Photoshop] or [https://www.gimp.org/ GIMP] are recommended.<br />
* '''Audio software''' – An audio-editing application capable of exporting <code>.wav</code> files for sound effects and, optionally, <code>.ogg</code> files for music. [https://www.adobe.com/products/audition.html Adobe Audition] or [https://www.audacityteam.org/ Audacity] are recommended.<br />
<br />
=== Optional Tools ===<br />
<br />
These tools are optional but highly recommended.<br />
<br />
* '''[https://www.chronocrash.com/forum/resources/chronocrash-modders-tools.139/ ChronoCrash Modders Tools (CMT)]''' – Visual editing application for building OpenBOR games.<br />
* '''[https://www.chronocrash.com/forum/resources/palapply.15/ PalApply]''' – Applies a palette to one or more images and exports optimized <code>.png</code> files ready for use with OpenBOR.<br />
<br />
== What Open Source Means ==<br />
Because the term has caused confusion and disputes in the past, it is important to clarify what open source means in the context of OpenBOR.<br />
<br />
OpenBOR’s existing codebase is available under a permissive [https://github.com/DCurrent/openbor/blob/master/LICENSE BSD-derived license]. '''Creators may use the engine to make, license, and sell games and other content they rightfully own.''' The OpenBOR license does not claim or control that content.<br />
<br />
Open source does not mean a free-for-all. It provides no implied permission to modify or redistribute another creator’s work without consent. The license also permits binary distribution without requiring source disclosure - it does not compel the team to release existing or future source code, and by extension it does not entitle anyone to the source code of closed-source extensions or obligate the development team to release it. The public repository is provided and maintained as a voluntary act of good faith, not as an obligation imposed by the license.<br />
<br />
The OpenBOR development team may produce proprietary features, such as encrypted pack handling, and license them separately at its discretion.</div>Dcurrenthttps://chronocrash.com/openbor/wiki/index.php?title=Main_Page&diff=1076Main Page2026-08-22T04:01:06Z<p>Dcurrent: /* Why OpenBOR? */</p>
<hr />
<div>== Introduction ==<br />
<br />
=== What is OpenBOR? ===<br />
OpenBOR is a royalty-free, open-source engine for sprite-based games. It combines a complete native game framework - including controls, movement, combat, artificial intelligence, levels, audio, menus, saving, and local multiplayer - with an integrated C-like scripting language that can extend or replace nearly every system.<br />
<br />
OpenBOR specializes in side-scrolling action games such as Double Dragon and Streets of Rage, but its three-dimensional game world, configurable simulation, declarative object system, and scriptable graphics pipeline also support platformers, shooters, role-playing games, puzzle games, and other genres.<br />
<br />
Beginners can build complete games primarily from assets and configuration. Advanced creators can manipulate engine objects, replace native behavior, construct rendering pipelines, and even compile new script programs while a module is running.<br />
<br />
=== Why OpenBOR? ===<br />
What sets OpenBOR apart is how far it extends in both directions. Creators do not need to build their own asset handling, controls, movement, artificial intelligence, collision and combat logic, audio playback, or other foundational systems. Everything is integrated and ready to use. Gather the assets and a fully functional game can be running within hours.<br />
<br />
At the opposite extreme, OpenBOR exposes low-level primitives and engine objects through configuration and script. Creators can inspect runtime state, customize selected behavior, replace complete subsystems, or build new ones without modifying engine source or depending on third-party plugins. Native functionality is therefore a starting point, not a boundary.<br />
<br />
* '''Complete native gameplay''' - Controls, movement, gravity, level trees, platforms, combat, blocking, grabbing, throwing, artificial intelligence, cameras, audio, menus, HUDs, and saving work without custom code.<br />
* '''[[Script Overview|Engine-wide scripting]]''' - Object APIs and over [[:Category:Script Events|70 event hooks]] expose input, animation, movement, collision, damage, spawning, audio, drawing, and other runtime systems for inspection, modification, or replacement.<br />
* '''[[Time|High-resolution simulation]]''' - The configurable logical clock runs at 200 Hz by default and remains independent of display updates.<br />
* '''[[Geometry Overview|Three-dimensional sprite worlds]]''' - Floating-point X, Y, and Z geometry provides subpixel movement, terrain, altitude, and depth sorting.<br />
* '''[[Collision|Declarative combat collision]]''' - Indexed three-dimensional attack and body boxes carry damage, reaction, motion, status, and presentation behavior.<br />
* '''[[Factions|Composable relationships]]''' - Four independent 52-bit faction masks provide hardware-speed membership, hostility, direct-damage, and indirect-damage rules.<br />
* '''[[Subscreens|Recursive graphics composition]]''' - Script-created subscreens support nested rendering, layer capture, transformations, masks, split screens, and feedback effects.<br />
* '''[[Runtime Script Compilation|Runtime metaprogramming]]''' - Modules can load and combine source files, compile them into independently owned programs, retain persistent state, execute them repeatedly, and replace them during play.<br />
* '''Optimized performance -''' Native systems, high-frequency simulation, and script integration are engineered to maintain steady frame rates and butter-smooth motion with dozens or hundreds of active objects.<br />
<br />
== Getting Started ==<br />
<br />
'''[https://www.chronocrash.com/forum/resources/openbor.1/ Download OpenBOR]''' | '''[https://www.chronocrash.com/forum/resources/categories/samples-and-tutorials.5/?prefix_id=3 Start Building]''' | '''[[:Category:Openbor|Browse the Reference]]''' | '''[https://chronocrash.com Visit the Community]''' | '''[https://github.com/DCurrent/openbor View the Source]'''<br />
<br />
This wiki is the comprehensive technical reference for OpenBOR, but please note it is not intended as a walk-through. For more in-depth instruction, consult the tutorials and guides available through the [https://chronocrash.com/forum ChronoCrash community].<br />
<br />
=== Guides and Resources ===<br />
<br />
* [[OpenBOR Overview]] – General overview of OpenBOR functionality and runtime layout.<br />
* [[:Category:Openbor|OpenBOR Hub]] – Main jumping off point for categories and individual wiki articles.<br />
* [[:Category:OpenBOR Index|OpenBOR Index]] – Simple index of OpenBOR commands, settings, and functions.<br />
* [[Legacy Manual]] – Archival monolithic manual.<br />
* [https://chronocrash.com/ ChronoCrash] – OpenBOR’s home community, including its help forum, downloadable games, and in-depth tutorials.<br />
* [https://github.com/DCurrent/openbor OpenBOR Repository] – Public-facing OpenBOR code base.<br />
<br />
== Development Environment ==<br />
<br />
=== Essential Tools ===<br />
<br />
The following tools are needed to begin building games with OpenBOR. You will need a [https://chronocrash.com/forum ChronoCrash community] account to download some resources.<br />
<br />
* [https://www.chronocrash.com/forum/resources/categories/engine.3/ OpenBOR engine executable] – The latest stable engine release.<br />
* '''[https://www.chronocrash.com/forum/resources/neo-edit-pack.2/ Edit Pack]''' – Tools for packing and unpacking OpenBOR game modules.<br />
* '''Development environment''' – OpenBOR uses a combination of text files and optional script files to configure game functionality. Any text editor may be used. [https://code.visualstudio.com/ Visual Studio Code] is recommended, together with [https://github.com Git] or another version-control system for managing project files.<br />
* '''Graphics software''' – Any graphics-editing application capable of exporting <code>.png</code> images. [https://www.adobe.com Adobe Photoshop] or [https://www.gimp.org/ GIMP] are recommended.<br />
* '''Audio software''' – An audio-editing application capable of exporting <code>.wav</code> files for sound effects and, optionally, <code>.ogg</code> files for music. [https://www.adobe.com/products/audition.html Adobe Audition] or [https://www.audacityteam.org/ Audacity] are recommended.<br />
<br />
=== Optional Tools ===<br />
<br />
These tools are optional but highly recommended.<br />
<br />
* '''[https://www.chronocrash.com/forum/resources/chronocrash-modders-tools.139/ ChronoCrash Modders Tools (CMT)]''' – Visual editing application for building OpenBOR games.<br />
* '''[https://www.chronocrash.com/forum/resources/palapply.15/ PalApply]''' – Applies a palette to one or more images and exports optimized <code>.png</code> files ready for use with OpenBOR.<br />
<br />
== What Open Source Means ==<br />
Because the term has caused confusion and disputes in the past, it is important to clarify what open source means in the context of OpenBOR.<br />
<br />
OpenBOR’s existing codebase is available under a permissive [https://github.com/DCurrent/openbor/blob/master/LICENSE BSD-derived license]. '''Creators may use the engine to make, license, and sell games and other content they rightfully own.''' The OpenBOR license does not claim or control that content.<br />
<br />
Open source does not mean a free-for-all. It provides no implied permission to modify or redistribute another creator’s work without consent. The license also permits binary distribution without requiring source disclosure - it does not compel the team to release existing or future source code, and by extension it does not entitle anyone to the source code of closed-source extensions or obligate the development team to release it. The public repository is provided and maintained as a voluntary act of good faith, not as an obligation imposed by the license.<br />
<br />
The OpenBOR development team may produce proprietary features, such as encrypted pack handling, and license them separately at its discretion.</div>Dcurrenthttps://chronocrash.com/openbor/wiki/index.php?title=Main_Page&diff=1075Main Page2026-08-22T03:59:54Z<p>Dcurrent: </p>
<hr />
<div>== Introduction ==<br />
<br />
=== What is OpenBOR? ===<br />
OpenBOR is a royalty-free, open-source engine for sprite-based games. It combines a complete native game framework - including controls, movement, combat, artificial intelligence, levels, audio, menus, saving, and local multiplayer - with an integrated C-like scripting language that can extend or replace nearly every system.<br />
<br />
OpenBOR specializes in side-scrolling action games such as Double Dragon and Streets of Rage, but its three-dimensional game world, configurable simulation, declarative object system, and scriptable graphics pipeline also support platformers, shooters, role-playing games, puzzle games, and other genres.<br />
<br />
Beginners can build complete games primarily from assets and configuration. Advanced creators can manipulate engine objects, replace native behavior, construct rendering pipelines, and even compile new script programs while a module is running.<br />
<br />
=== Why OpenBOR? ===<br />
What sets OpenBOR apart is how far it extends in both directions. Creators do not need to build their own asset handling, controls, movement, artificial intelligence, collision and combat logic, audio playback, or other foundational systems. Everything is integrated and ready to use. Gather the assets and a fully functional game can be running within hours.<br />
<br />
At the opposite extreme, OpenBOR exposes low-level primitives and engine objects through configuration and script. Creators can inspect runtime state, customize selected behavior, replace complete subsystems, or build new ones without modifying engine source or depending on third-party plugins. Native functionality is therefore a starting point, not a boundary.<br />
<br />
* '''Complete native gameplay''' - Controls, movement, gravity, level trees, platforms, combat, blocking, grabbing, throwing, artificial intelligence, cameras, audio, menus, HUDs, and saving work without custom code.<br />
* '''[[Script Overview|Engine-wide scripting]]''' - Object APIs and over [[:Category:Script Events|70 event hooks]] expose input, animation, movement, collision, damage, spawning, audio, drawing, and other runtime systems for inspection, modification, or replacement.<br />
* '''[[Time|High-resolution simulation]]''' - The configurable logical clock runs at 200 Hz by default and remains independent of display updates.<br />
* '''[[Geometry Overview|Three-dimensional sprite worlds]]''' - Floating-point X, Y, and Z geometry provides subpixel movement, terrain, altitude, and depth sorting.<br />
* '''[[Collision|Declarative combat collision]]''' - Indexed three-dimensional attack and body boxes carry damage, reaction, motion, status, and presentation behavior.<br />
* '''[[Factions|Composable relationships]]''' - Four independent 52-bit faction masks provide hardware-speed membership, hostility, direct-damage, and indirect-damage rules.<br />
* '''[[Subscreens|Recursive graphics composition]]''' - Script-created subscreens support nested rendering, layer capture, transformations, masks, split screens, and feedback effects.<br />
* '''[[Runtime Script Compilation|Runtime metaprogramming]]''' - Modules can load and combine source files, compile them into independently owned programs, retain persistent state, execute them repeatedly, and replace them during play.<br />
* '''Optimized performance -''' Native systems, high-frequency simulation, and script integration are engineered to maintain steady frame rates and butter smooth motion with dozens or hundreds of active objects.<br />
<br />
== Getting Started ==<br />
<br />
'''[https://www.chronocrash.com/forum/resources/openbor.1/ Download OpenBOR]''' | '''[https://www.chronocrash.com/forum/resources/categories/samples-and-tutorials.5/?prefix_id=3 Start Building]''' | '''[[:Category:Openbor|Browse the Reference]]''' | '''[https://chronocrash.com Visit the Community]''' | '''[https://github.com/DCurrent/openbor View the Source]'''<br />
<br />
This wiki is the comprehensive technical reference for OpenBOR, but please note it is not intended as a walk-through. For more in-depth instruction, consult the tutorials and guides available through the [https://chronocrash.com/forum ChronoCrash community].<br />
<br />
=== Guides and Resources ===<br />
<br />
* [[OpenBOR Overview]] – General overview of OpenBOR functionality and runtime layout.<br />
* [[:Category:Openbor|OpenBOR Hub]] – Main jumping off point for categories and individual wiki articles.<br />
* [[:Category:OpenBOR Index|OpenBOR Index]] – Simple index of OpenBOR commands, settings, and functions.<br />
* [[Legacy Manual]] – Archival monolithic manual.<br />
* [https://chronocrash.com/ ChronoCrash] – OpenBOR’s home community, including its help forum, downloadable games, and in-depth tutorials.<br />
* [https://github.com/DCurrent/openbor OpenBOR Repository] – Public-facing OpenBOR code base.<br />
<br />
== Development Environment ==<br />
<br />
=== Essential Tools ===<br />
<br />
The following tools are needed to begin building games with OpenBOR. You will need a [https://chronocrash.com/forum ChronoCrash community] account to download some resources.<br />
<br />
* [https://www.chronocrash.com/forum/resources/categories/engine.3/ OpenBOR engine executable] – The latest stable engine release.<br />
* '''[https://www.chronocrash.com/forum/resources/neo-edit-pack.2/ Edit Pack]''' – Tools for packing and unpacking OpenBOR game modules.<br />
* '''Development environment''' – OpenBOR uses a combination of text files and optional script files to configure game functionality. Any text editor may be used. [https://code.visualstudio.com/ Visual Studio Code] is recommended, together with [https://github.com Git] or another version-control system for managing project files.<br />
* '''Graphics software''' – Any graphics-editing application capable of exporting <code>.png</code> images. [https://www.adobe.com Adobe Photoshop] or [https://www.gimp.org/ GIMP] are recommended.<br />
* '''Audio software''' – An audio-editing application capable of exporting <code>.wav</code> files for sound effects and, optionally, <code>.ogg</code> files for music. [https://www.adobe.com/products/audition.html Adobe Audition] or [https://www.audacityteam.org/ Audacity] are recommended.<br />
<br />
=== Optional Tools ===<br />
<br />
These tools are optional but highly recommended.<br />
<br />
* '''[https://www.chronocrash.com/forum/resources/chronocrash-modders-tools.139/ ChronoCrash Modders Tools (CMT)]''' – Visual editing application for building OpenBOR games.<br />
* '''[https://www.chronocrash.com/forum/resources/palapply.15/ PalApply]''' – Applies a palette to one or more images and exports optimized <code>.png</code> files ready for use with OpenBOR.<br />
<br />
== What Open Source Means ==<br />
Because the term has caused confusion and disputes in the past, it is important to clarify what open source means in the context of OpenBOR.<br />
<br />
OpenBOR’s existing codebase is available under a permissive [https://github.com/DCurrent/openbor/blob/master/LICENSE BSD-derived license]. '''Creators may use the engine to make, license, and sell games and other content they rightfully own.''' The OpenBOR license does not claim or control that content.<br />
<br />
Open source does not mean a free-for-all. It provides no implied permission to modify or redistribute another creator’s work without consent. The license also permits binary distribution without requiring source disclosure - it does not compel the team to release existing or future source code, and by extension it does not entitle anyone to the source code of closed-source extensions or obligate the development team to release it. The public repository is provided and maintained as a voluntary act of good faith, not as an obligation imposed by the license.<br />
<br />
The OpenBOR development team may produce proprietary features, such as encrypted pack handling, and license them separately at its discretion.</div>Dcurrenthttps://chronocrash.com/openbor/wiki/index.php?title=Model_Lifecycle_Scripts&diff=1074Model Lifecycle Scripts2026-08-22T03:49:31Z<p>Dcurrent: </p>
<hr />
<div>[[Category:Model]]<br />
[[Category:Script]]<br />
'''Model lifecycle scripts''' are event hooks that execute when a model template enters or leaves OpenBOR's loaded model collection. The series provides project-wide global observers and model-owned callbacks for both load and unload transitions.<br />
<br />
{| class="wikitable"<br />
! Hook<br />
! Scope<br />
! Execution point<br />
|-<br />
| <code>modelloadscript</code><br />
| Model-owned<br />
| After that model finishes loading<br />
|-<br />
| <code>data/scripts/modelload.c</code><br />
| Project-wide<br />
| After the loaded model's <code>modelloadscript</code><br />
|-<br />
| <code>modelunloadscript</code><br />
| Model-owned<br />
| Before that model begins native destruction<br />
|-<br />
| <code>data/scripts/modelunload.c</code><br />
| Project-wide<br />
| After the model's <code>modelunloadscript</code>, before native destruction<br />
|}<br />
<br />
Model lifecycle is distinct from entity lifecycle. Loading a model makes its template available for spawning one or many entities. Unloading removes that template from active memory. Neither transition represents an entity spawn, death, or removal.<br />
<br />
This distinction makes the series useful for model registries, template-specific initialization, dynamic loading systems, model analysis, custom resource maps, diagnostics, subsystem registration, teardown, and other work that should occur once per model transition instead of once per spawned entity or once per loading-screen update.<br />
<br />
== Global Usage ==<br />
<br />
Create either or both global files in <code>data/scripts</code>:<br />
<br />
* <code>data/scripts/modelload.c</code><br />
* <code>data/scripts/modelunload.c</code><br />
<br />
OpenBOR loads them automatically. <code>modelload.c</code> observes every completed model load, while <code>modelunload.c</code> observes every model immediately before it is destroyed.<br />
<br />
<syntaxhighlight lang="c" line><br />
void main()<br />
{<br />
setglobalvar("last_loaded_model_name", modelname);<br />
setglobalvar("last_loaded_model_index", modelindex);<br />
setglobalvar("model_registry_dirty", 1);<br />
}<br />
</syntaxhighlight><br />
<br />
The example is suitable for <code>modelload.c</code>. Central managers can use the reported name and index to refresh only the affected registry entry rather than scanning the full loaded-model collection during every [[Loading|loading.c]] execution.<br />
<br />
== Model Usage ==<br />
<br />
Add either command to a model definition and provide the path to its script file:<br />
<br />
<syntaxhighlight lang="text"><br />
modelloadscript data/scripts/models/boss_template_load.c<br />
modelunloadscript data/scripts/models/boss_template_unload.c<br />
</syntaxhighlight><br />
<br />
The commands belong to the model template that declares them. They do not belong to spawned entities and are not copied into entity <code>modeldata</code>.<br />
<br />
<syntaxhighlight lang="c" line><br />
void main()<br />
{<br />
setglobalvar("boss_template_ready", 1);<br />
setglobalvar("boss_template_index", modelindex);<br />
}<br />
</syntaxhighlight><br />
<br />
Model-owned callbacks are useful when one template requires specialized setup or teardown that does not belong in the global observer.<br />
<br />
Only one <code>modelloadscript</code> and one <code>modelunloadscript</code> may be assigned to a model. Global and model-owned layers may be used independently or together.<br />
<br />
== Inline Model Scripts ==<br />
<br />
Both commands support inline script blocks:<br />
<br />
<syntaxhighlight lang="text"><br />
modelloadscript @script<br />
void main()<br />
{<br />
setglobalvar("guardian_template_loaded", 1);<br />
}<br />
@end_script<br />
<br />
modelunloadscript @script<br />
void main()<br />
{<br />
setglobalvar("guardian_template_loaded", 0);<br />
}<br />
@end_script<br />
</syntaxhighlight><br />
<br />
Inline form is convenient for concise model-specific bookkeeping. External files are easier to reuse and organize when lifecycle work contains several systems or helper functions.<br />
<br />
== Event Data ==<br />
<br />
All four lifecycle hooks receive the same automatic local variables:<br />
<br />
{| class="wikitable sortable"<br />
! Variable<br />
! Type<br />
! Description<br />
|-<br />
| <code>model</code><br />
| Object pointer<br />
| Pointer to the loaded model template. The pointer is fully available during both load and unload callbacks.<br />
|-<br />
| <code>modelindex</code><br />
| Integer<br />
| Stable index of the model's cache entry.<br />
|-<br />
| <code>modelname</code><br />
| String<br />
| Name assigned to the model's cache entry.<br />
|}<br />
<br />
<syntaxhighlight lang="c" line><br />
void main()<br />
{<br />
if (model)<br />
{<br />
setglobalvar("lifecycle_model_name", modelname);<br />
setglobalvar("lifecycle_model_index", modelindex);<br />
}<br />
}<br />
</syntaxhighlight><br />
<br />
The <code>model</code> value refers to a template rather than an entity. Entity property functions and entity-local assumptions do not apply to it. Use the model property API or another model-aware system when inspecting or modifying the template.<br />
<br />
<code>modelindex</code> identifies the cache slot and remains stable when an unloadable model is later loaded again. <code>modelname</code> is safe to preserve after an unload callback. The <code>model</code> pointer is not safe to retain after unloading completes.<br />
<br />
== Model Load Event ==<br />
<br />
The load event executes only after OpenBOR successfully finishes parsing and constructing the model. Defaults, inherited model data, animations, scripts, palettes, collision information, and other declared properties have already been processed when <code>modelloadscript</code> begins.<br />
<br />
The load sequence is:<br />
<br />
# OpenBOR locates the model's existing cache entry.<br />
# The model file is read and its template is constructed.<br />
# Model properties, animations, ordinary event scripts, and lifecycle commands are parsed.<br />
# Temporary parser resources are released.<br />
# The model's <code>modelloadscript</code> executes when declared.<br />
# Global <code>data/scripts/modelload.c</code> executes when present.<br />
# The model enters its normal loaded state and the original load request receives the completed template.<br />
<br />
Model-owned logic always executes before the global observer. The global script may therefore consume registration, flags, or other state established by the model's own callback.<br />
<br />
Requesting a model that is already loaded does not produce another load event. The event represents an actual transition from cached model definition to loaded template, not each lookup or each entity spawn using that template.<br />
<br />
== Model Unload Event ==<br />
<br />
The unload event executes while the model remains intact and immediately before OpenBOR begins native destruction.<br />
<br />
The unload sequence is:<br />
<br />
# OpenBOR receives a valid request to unload a currently loaded model or begins a native model-cleanup operation.<br />
# The model's <code>modelunloadscript</code> executes when declared.<br />
# Global <code>data/scripts/modelunload.c</code> executes when present.<br />
# OpenBOR frees the template's animations, palettes, scripts, collections, and other owned resources.<br />
# The template is removed from the loaded model collection while its cache entry remains available for a later reload.<br />
<br />
Model-owned teardown always executes before the global observer. Both layers may inspect the model and coordinate cleanup while <code>model</code> is still valid.<br />
<br />
The pointer becomes invalid after the unload chain returns and native destruction begins. Cleanup systems that need persistent identification should retain <code>modelname</code>, <code>modelindex</code>, or creator-owned data instead of retaining the pointer.<br />
<br />
<syntaxhighlight lang="c" line><br />
void main()<br />
{<br />
setglobalvar("last_unloaded_model_name", modelname);<br />
setglobalvar("last_unloaded_model_index", modelindex);<br />
setglobalvar("model_registry_dirty", 1);<br />
}<br />
</syntaxhighlight><br />
<br />
The example allows a registry manager to remove or rebuild the affected entry without touching the model pointer after the event ends.<br />
<br />
== Cache and Reload Behavior ==<br />
<br />
OpenBOR distinguishes a cached model definition from a loaded model template. Entries created from <code>data/models.txt</code> retain the model name, source path, flags, and stable cache position even while the full template is unloaded.<br />
<br />
Lifecycle scripts follow transitions of the full template:<br />
<br />
* Registering the cache entry alone does not execute <code>modelload</code>.<br />
* Loading and completing the template executes the load chain once.<br />
* Looking up or requesting an already loaded template does not repeat the chain.<br />
* Unloading the template executes the unload chain once.<br />
* Loading the same cache entry again parses its model lifecycle commands and executes a new load chain.<br />
* Requesting <code>unload_model()</code> for an absent model does not load it and therefore produces no lifecycle event.<br />
<br />
This behavior provides precise change notifications without requiring a recurring scan to discover whether the loaded collection changed.<br />
<br />
== Lifecycle Safety ==<br />
<br />
OpenBOR guards lifecycle transitions against recursive self-removal and partially constructed templates. An unload request targeting the same model from its load or unload callback is ignored because that model is already inside a protected lifecycle phase.<br />
<br />
The guard keeps one callback from re-entering destruction of its own template. Lifecycle scripts may still coordinate creator-owned cleanup, request later work through flags or registries, and operate on other valid systems during the event.<br />
<br />
Model subclasses do not inherit <code>modelloadscript</code> or <code>modelunloadscript</code> from their parent template. Each subclass may declare its own lifecycle callbacks. This prevents parent and child cache entries from sharing compiled callback ownership while preserving normal inheritance for ordinary model data and supported entity event scripts.<br />
<br />
== Lifecycle Events and Entity Events ==<br />
<br />
{| class="wikitable"<br />
! Hook<br />
! Object represented<br />
! Frequency<br />
! Typical responsibility<br />
|-<br />
| <code>modelloadscript</code> and <code>modelload.c</code><br />
| Loaded model template<br />
| Once per actual template load<br />
| Template registration, analysis, and initialization<br />
|-<br />
| [[Onmodelcopyscript|onmodelcopyscript]]<br />
| Model data being copied for an entity<br />
| During applicable model-copy operations<br />
| Per-instance model-data adjustment<br />
|-<br />
| [[Onspawnscript|onspawnscript]]<br />
| Newly created entity<br />
| Once per applicable entity creation<br />
| Entity initialization<br />
|-<br />
| [[Ondeathscript|ondeathscript]]<br />
| Dying entity<br />
| During applicable entity death processing<br />
| Entity-specific death behavior<br />
|-<br />
| [[Onkillscript|onkillscript]]<br />
| Entity being removed<br />
| Immediately before applicable entity removal<br />
| Entity cleanup<br />
|-<br />
| <code>modelunloadscript</code> and <code>modelunload.c</code><br />
| Loaded model template<br />
| Once per actual template unload<br />
| Template deregistration and teardown<br />
|}<br />
<br />
One loaded model may create many entities. Model lifecycle scripts execute for the template transition, while entity events execute separately for individual instances.<br />
<br />
== Global and Model-Owned Responsibilities ==<br />
<br />
The two scopes support a useful division of responsibility:<br />
<br />
* Model-owned <code>modelloadscript</code> and <code>modelunloadscript</code> handle behavior unique to one template.<br />
* Global <code>modelload.c</code> and <code>modelunload.c</code> maintain project-wide registries and systems after the model-owned callback has run.<br />
<br />
For example, a boss model can publish its specialized combat role during <code>modelloadscript</code>. Global <code>modelload.c</code> can then add the completed template to a project-wide model registry. During removal, the model-owned callback can release its custom relationships before <code>modelunload.c</code> reconciles the common registry.<br />
<br />
== Other Uses ==<br />
<br />
Quick applications include:<br />
<br />
* '''Model registries''' - Add and remove exact cache entries without repeatedly scanning every loaded model.<br />
* '''Template analysis''' - Inspect capabilities, animations, classifications, resources, or creator-defined metadata once after parsing.<br />
* '''Subsystem registration''' - Connect models to combat managers, factories, selectors, randomizers, encounter systems, or development tools.<br />
* '''Dynamic loading''' - Track runtime <code>loadmodel()</code> and <code>unload_model()</code> transitions as they occur.<br />
* '''Model-specific initialization''' - Prepare template-owned creator state before any entity needs to use it.<br />
* '''Resource coordination''' - Build or release creator-managed lookup tables, auxiliary assets, caches, or relationships alongside a template.<br />
* '''Diagnostics''' - Log load order, unload order, names, cache indices, reloads, or unexpected lifecycle transitions.<br />
* '''Loading optimization''' - Replace repeated full-model scans in <code>loading.c</code> with exact event-driven notifications.<br />
<br />
== Related Scripts ==<br />
<br />
{| class="wikitable"<br />
! Script<br />
! Relationship<br />
|-<br />
| [[Loading|loading.c]]<br />
| Recurring loading-screen hook. Model lifecycle events provide exact template transition notifications without repeated collection scans.<br />
|-<br />
| [[Onmodelcopyscript|onmodelcopyscript]]<br />
| Executes during applicable model-data copy operations rather than model-cache loading.<br />
|-<br />
| [[Onspawnscript|onspawnscript]]<br />
| Executes for applicable entity creation after a model template is available.<br />
|-<br />
| [[Ondeathscript|ondeathscript]]<br />
| Model-owned hook for entity death processing.<br />
|-<br />
| [[Onkillscript|onkillscript]]<br />
| Model-owned hook for entity removal.<br />
|}<br />
<br />
== See Also ==<br />
<br />
* [[Loading]]<br />
* [[Model Properties]]<br />
* [[Onmodelcopyscript]]<br />
* [[Onspawnscript]]<br />
* [[Ondeathscript]]<br />
* [[Onkillscript]]<br />
* [[Models]]<br />
* [[Script Overview]]<br />
[[Category:Openbor]]</div>Dcurrenthttps://chronocrash.com/openbor/wiki/index.php?title=Modelunloadscript&diff=1073Modelunloadscript2026-08-22T03:48:45Z<p>Dcurrent: Redirected page to Model Lifecycle Scripts#Model Usage</p>
<hr />
<div>#REDIRECT [[Model_Lifecycle_Scripts#Model_Usage]]<br />
[[Category:OpenBOR Index]]<br />
[[Category:Model]]<br />
[[Category:Script Events]]</div>Dcurrenthttps://chronocrash.com/openbor/wiki/index.php?title=Modelloadscript&diff=1072Modelloadscript2026-08-22T03:48:19Z<p>Dcurrent: Redirected page to Model Lifecycle Scripts#Model Usage</p>
<hr />
<div>#REDIRECT [[Model_Lifecycle_Scripts#Model_Usage]]<br />
[[Category:OpenBOR Index]]<br />
[[Category:Model]]<br />
[[Category:Script Events]]</div>Dcurrenthttps://chronocrash.com/openbor/wiki/index.php?title=Modelunload&diff=1071Modelunload2026-08-22T03:47:23Z<p>Dcurrent: Redirected page to Model Lifecycle Scripts#Global Usage</p>
<hr />
<div>#REDIRECT [[Model Lifecycle Scripts#Global Usage]]<br />
[[Category:OpenBOR Index]]<br />
[[Category:Model]]<br />
[[Category:Script Events]]</div>Dcurrenthttps://chronocrash.com/openbor/wiki/index.php?title=Modelload&diff=1070Modelload2026-08-22T03:47:04Z<p>Dcurrent: Redirected page to Model Lifecycle Scripts#Global Usage</p>
<hr />
<div>#REDIRECT [[Model Lifecycle Scripts#Global Usage]]<br />
[[Category:OpenBOR Index]]<br />
[[Category:Model]]<br />
[[Category:Script Events]]</div>Dcurrenthttps://chronocrash.com/openbor/wiki/index.php?title=Model_Load_Scripts&diff=1069Model Load Scripts2026-08-22T03:45:24Z<p>Dcurrent: Dcurrent moved page Model Load Scripts to Model Lifecycle Scripts: Misspelled title</p>
<hr />
<div>#REDIRECT [[Model Lifecycle Scripts]]</div>Dcurrenthttps://chronocrash.com/openbor/wiki/index.php?title=Model_Lifecycle_Scripts&diff=1068Model Lifecycle Scripts2026-08-22T03:45:24Z<p>Dcurrent: Dcurrent moved page Model Load Scripts to Model Lifecycle Scripts: Misspelled title</p>
<hr />
<div>[[Category:Model]]<br />
[[Category:Script]]<br />
[[Category:Script Events]]<br />
<br />
'''Model lifecycle scripts''' are event hooks that execute when a model template enters or leaves OpenBOR's loaded model collection. The series provides project-wide global observers and model-owned callbacks for both load and unload transitions.<br />
<br />
{| class="wikitable"<br />
! Hook<br />
! Scope<br />
! Execution point<br />
|-<br />
| <code>modelloadscript</code><br />
| Model-owned<br />
| After that model finishes loading<br />
|-<br />
| <code>data/scripts/modelload.c</code><br />
| Project-wide<br />
| After the loaded model's <code>modelloadscript</code><br />
|-<br />
| <code>modelunloadscript</code><br />
| Model-owned<br />
| Before that model begins native destruction<br />
|-<br />
| <code>data/scripts/modelunload.c</code><br />
| Project-wide<br />
| After the model's <code>modelunloadscript</code>, before native destruction<br />
|}<br />
<br />
Model lifecycle is distinct from entity lifecycle. Loading a model makes its template available for spawning one or many entities. Unloading removes that template from active memory. Neither transition represents an entity spawn, death, or removal.<br />
<br />
This distinction makes the series useful for model registries, template-specific initialization, dynamic loading systems, model analysis, custom resource maps, diagnostics, subsystem registration, teardown, and other work that should occur once per model transition instead of once per spawned entity or once per loading-screen update.<br />
<br />
== Global Usage ==<br />
<br />
Create either or both global files in <code>data/scripts</code>:<br />
<br />
* <code>data/scripts/modelload.c</code><br />
* <code>data/scripts/modelunload.c</code><br />
<br />
OpenBOR loads them automatically. <code>modelload.c</code> observes every completed model load, while <code>modelunload.c</code> observes every model immediately before it is destroyed.<br />
<br />
<syntaxhighlight lang="c" line><br />
void main()<br />
{<br />
setglobalvar("last_loaded_model_name", modelname);<br />
setglobalvar("last_loaded_model_index", modelindex);<br />
setglobalvar("model_registry_dirty", 1);<br />
}<br />
</syntaxhighlight><br />
<br />
The example is suitable for <code>modelload.c</code>. Central managers can use the reported name and index to refresh only the affected registry entry rather than scanning the full loaded-model collection during every [[Loading|loading.c]] execution.<br />
<br />
== Model Usage ==<br />
<br />
Add either command to a model definition and provide the path to its script file:<br />
<br />
<syntaxhighlight lang="text"><br />
modelloadscript data/scripts/models/boss_template_load.c<br />
modelunloadscript data/scripts/models/boss_template_unload.c<br />
</syntaxhighlight><br />
<br />
The commands belong to the model template that declares them. They do not belong to spawned entities and are not copied into entity <code>modeldata</code>.<br />
<br />
<syntaxhighlight lang="c" line><br />
void main()<br />
{<br />
setglobalvar("boss_template_ready", 1);<br />
setglobalvar("boss_template_index", modelindex);<br />
}<br />
</syntaxhighlight><br />
<br />
Model-owned callbacks are useful when one template requires specialized setup or teardown that does not belong in the global observer.<br />
<br />
Only one <code>modelloadscript</code> and one <code>modelunloadscript</code> may be assigned to a model. Global and model-owned layers may be used independently or together.<br />
<br />
== Inline Model Scripts ==<br />
<br />
Both commands support inline script blocks:<br />
<br />
<syntaxhighlight lang="text"><br />
modelloadscript @script<br />
void main()<br />
{<br />
setglobalvar("guardian_template_loaded", 1);<br />
}<br />
@end_script<br />
<br />
modelunloadscript @script<br />
void main()<br />
{<br />
setglobalvar("guardian_template_loaded", 0);<br />
}<br />
@end_script<br />
</syntaxhighlight><br />
<br />
Inline form is convenient for concise model-specific bookkeeping. External files are easier to reuse and organize when lifecycle work contains several systems or helper functions.<br />
<br />
== Event Data ==<br />
<br />
All four lifecycle hooks receive the same automatic local variables:<br />
<br />
{| class="wikitable sortable"<br />
! Variable<br />
! Type<br />
! Description<br />
|-<br />
| <code>model</code><br />
| Object pointer<br />
| Pointer to the loaded model template. The pointer is fully available during both load and unload callbacks.<br />
|-<br />
| <code>modelindex</code><br />
| Integer<br />
| Stable index of the model's cache entry.<br />
|-<br />
| <code>modelname</code><br />
| String<br />
| Name assigned to the model's cache entry.<br />
|}<br />
<br />
<syntaxhighlight lang="c" line><br />
void main()<br />
{<br />
if (model)<br />
{<br />
setglobalvar("lifecycle_model_name", modelname);<br />
setglobalvar("lifecycle_model_index", modelindex);<br />
}<br />
}<br />
</syntaxhighlight><br />
<br />
The <code>model</code> value refers to a template rather than an entity. Entity property functions and entity-local assumptions do not apply to it. Use the model property API or another model-aware system when inspecting or modifying the template.<br />
<br />
<code>modelindex</code> identifies the cache slot and remains stable when an unloadable model is later loaded again. <code>modelname</code> is safe to preserve after an unload callback. The <code>model</code> pointer is not safe to retain after unloading completes.<br />
<br />
== Model Load Event ==<br />
<br />
The load event executes only after OpenBOR successfully finishes parsing and constructing the model. Defaults, inherited model data, animations, scripts, palettes, collision information, and other declared properties have already been processed when <code>modelloadscript</code> begins.<br />
<br />
The load sequence is:<br />
<br />
# OpenBOR locates the model's existing cache entry.<br />
# The model file is read and its template is constructed.<br />
# Model properties, animations, ordinary event scripts, and lifecycle commands are parsed.<br />
# Temporary parser resources are released.<br />
# The model's <code>modelloadscript</code> executes when declared.<br />
# Global <code>data/scripts/modelload.c</code> executes when present.<br />
# The model enters its normal loaded state and the original load request receives the completed template.<br />
<br />
Model-owned logic always executes before the global observer. The global script may therefore consume registration, flags, or other state established by the model's own callback.<br />
<br />
Requesting a model that is already loaded does not produce another load event. The event represents an actual transition from cached model definition to loaded template, not each lookup or each entity spawn using that template.<br />
<br />
== Model Unload Event ==<br />
<br />
The unload event executes while the model remains intact and immediately before OpenBOR begins native destruction.<br />
<br />
The unload sequence is:<br />
<br />
# OpenBOR receives a valid request to unload a currently loaded model or begins a native model-cleanup operation.<br />
# The model's <code>modelunloadscript</code> executes when declared.<br />
# Global <code>data/scripts/modelunload.c</code> executes when present.<br />
# OpenBOR frees the template's animations, palettes, scripts, collections, and other owned resources.<br />
# The template is removed from the loaded model collection while its cache entry remains available for a later reload.<br />
<br />
Model-owned teardown always executes before the global observer. Both layers may inspect the model and coordinate cleanup while <code>model</code> is still valid.<br />
<br />
The pointer becomes invalid after the unload chain returns and native destruction begins. Cleanup systems that need persistent identification should retain <code>modelname</code>, <code>modelindex</code>, or creator-owned data instead of retaining the pointer.<br />
<br />
<syntaxhighlight lang="c" line><br />
void main()<br />
{<br />
setglobalvar("last_unloaded_model_name", modelname);<br />
setglobalvar("last_unloaded_model_index", modelindex);<br />
setglobalvar("model_registry_dirty", 1);<br />
}<br />
</syntaxhighlight><br />
<br />
The example allows a registry manager to remove or rebuild the affected entry without touching the model pointer after the event ends.<br />
<br />
== Cache and Reload Behavior ==<br />
<br />
OpenBOR distinguishes a cached model definition from a loaded model template. Entries created from <code>data/models.txt</code> retain the model name, source path, flags, and stable cache position even while the full template is unloaded.<br />
<br />
Lifecycle scripts follow transitions of the full template:<br />
<br />
* Registering the cache entry alone does not execute <code>modelload</code>.<br />
* Loading and completing the template executes the load chain once.<br />
* Looking up or requesting an already loaded template does not repeat the chain.<br />
* Unloading the template executes the unload chain once.<br />
* Loading the same cache entry again parses its model lifecycle commands and executes a new load chain.<br />
* Requesting <code>unload_model()</code> for an absent model does not load it and therefore produces no lifecycle event.<br />
<br />
This behavior provides precise change notifications without requiring a recurring scan to discover whether the loaded collection changed.<br />
<br />
== Lifecycle Safety ==<br />
<br />
OpenBOR guards lifecycle transitions against recursive self-removal and partially constructed templates. An unload request targeting the same model from its load or unload callback is ignored because that model is already inside a protected lifecycle phase.<br />
<br />
The guard keeps one callback from re-entering destruction of its own template. Lifecycle scripts may still coordinate creator-owned cleanup, request later work through flags or registries, and operate on other valid systems during the event.<br />
<br />
Model subclasses do not inherit <code>modelloadscript</code> or <code>modelunloadscript</code> from their parent template. Each subclass may declare its own lifecycle callbacks. This prevents parent and child cache entries from sharing compiled callback ownership while preserving normal inheritance for ordinary model data and supported entity event scripts.<br />
<br />
== Lifecycle Events and Entity Events ==<br />
<br />
{| class="wikitable"<br />
! Hook<br />
! Object represented<br />
! Frequency<br />
! Typical responsibility<br />
|-<br />
| <code>modelloadscript</code> and <code>modelload.c</code><br />
| Loaded model template<br />
| Once per actual template load<br />
| Template registration, analysis, and initialization<br />
|-<br />
| [[Onmodelcopyscript|onmodelcopyscript]]<br />
| Model data being copied for an entity<br />
| During applicable model-copy operations<br />
| Per-instance model-data adjustment<br />
|-<br />
| [[Onspawnscript|onspawnscript]]<br />
| Newly created entity<br />
| Once per applicable entity creation<br />
| Entity initialization<br />
|-<br />
| [[Ondeathscript|ondeathscript]]<br />
| Dying entity<br />
| During applicable entity death processing<br />
| Entity-specific death behavior<br />
|-<br />
| [[Onkillscript|onkillscript]]<br />
| Entity being removed<br />
| Immediately before applicable entity removal<br />
| Entity cleanup<br />
|-<br />
| <code>modelunloadscript</code> and <code>modelunload.c</code><br />
| Loaded model template<br />
| Once per actual template unload<br />
| Template deregistration and teardown<br />
|}<br />
<br />
One loaded model may create many entities. Model lifecycle scripts execute for the template transition, while entity events execute separately for individual instances.<br />
<br />
== Global and Model-Owned Responsibilities ==<br />
<br />
The two scopes support a useful division of responsibility:<br />
<br />
* Model-owned <code>modelloadscript</code> and <code>modelunloadscript</code> handle behavior unique to one template.<br />
* Global <code>modelload.c</code> and <code>modelunload.c</code> maintain project-wide registries and systems after the model-owned callback has run.<br />
<br />
For example, a boss model can publish its specialized combat role during <code>modelloadscript</code>. Global <code>modelload.c</code> can then add the completed template to a project-wide model registry. During removal, the model-owned callback can release its custom relationships before <code>modelunload.c</code> reconciles the common registry.<br />
<br />
== Other Uses ==<br />
<br />
Quick applications include:<br />
<br />
* '''Model registries''' - Add and remove exact cache entries without repeatedly scanning every loaded model.<br />
* '''Template analysis''' - Inspect capabilities, animations, classifications, resources, or creator-defined metadata once after parsing.<br />
* '''Subsystem registration''' - Connect models to combat managers, factories, selectors, randomizers, encounter systems, or development tools.<br />
* '''Dynamic loading''' - Track runtime <code>loadmodel()</code> and <code>unload_model()</code> transitions as they occur.<br />
* '''Model-specific initialization''' - Prepare template-owned creator state before any entity needs to use it.<br />
* '''Resource coordination''' - Build or release creator-managed lookup tables, auxiliary assets, caches, or relationships alongside a template.<br />
* '''Diagnostics''' - Log load order, unload order, names, cache indices, reloads, or unexpected lifecycle transitions.<br />
* '''Loading optimization''' - Replace repeated full-model scans in <code>loading.c</code> with exact event-driven notifications.<br />
<br />
== Related Scripts ==<br />
<br />
{| class="wikitable"<br />
! Script<br />
! Relationship<br />
|-<br />
| [[Loading|loading.c]]<br />
| Recurring loading-screen hook. Model lifecycle events provide exact template transition notifications without repeated collection scans.<br />
|-<br />
| [[Onmodelcopyscript|onmodelcopyscript]]<br />
| Executes during applicable model-data copy operations rather than model-cache loading.<br />
|-<br />
| [[Onspawnscript|onspawnscript]]<br />
| Executes for applicable entity creation after a model template is available.<br />
|-<br />
| [[Ondeathscript|ondeathscript]]<br />
| Model-owned hook for entity death processing.<br />
|-<br />
| [[Onkillscript|onkillscript]]<br />
| Model-owned hook for entity removal.<br />
|}<br />
<br />
== See Also ==<br />
<br />
* [[Loading]]<br />
* [[Model Properties]]<br />
* [[Onmodelcopyscript]]<br />
* [[Onspawnscript]]<br />
* [[Ondeathscript]]<br />
* [[Onkillscript]]<br />
* [[Models]]<br />
* [[Script Overview]]</div>Dcurrenthttps://chronocrash.com/openbor/wiki/index.php?title=Model_Lifecycle_Scripts&diff=1067Model Lifecycle Scripts2026-08-22T03:44:33Z<p>Dcurrent: Created page with "Category:Model Category:Script Category:Script Events '''Model lifecycle scripts''' are event hooks that execute when a model template enters or leaves OpenBOR's loaded model collection. The series provides project-wide global observers and model-owned callbacks for both load and unload transitions. {| class="wikitable" ! Hook ! Scope ! Execution point |- | <code>modelloadscript</code> | Model-owned | After that model finishes loading |- | <code>data/script..."</p>
<hr />
<div>[[Category:Model]]<br />
[[Category:Script]]<br />
[[Category:Script Events]]<br />
<br />
'''Model lifecycle scripts''' are event hooks that execute when a model template enters or leaves OpenBOR's loaded model collection. The series provides project-wide global observers and model-owned callbacks for both load and unload transitions.<br />
<br />
{| class="wikitable"<br />
! Hook<br />
! Scope<br />
! Execution point<br />
|-<br />
| <code>modelloadscript</code><br />
| Model-owned<br />
| After that model finishes loading<br />
|-<br />
| <code>data/scripts/modelload.c</code><br />
| Project-wide<br />
| After the loaded model's <code>modelloadscript</code><br />
|-<br />
| <code>modelunloadscript</code><br />
| Model-owned<br />
| Before that model begins native destruction<br />
|-<br />
| <code>data/scripts/modelunload.c</code><br />
| Project-wide<br />
| After the model's <code>modelunloadscript</code>, before native destruction<br />
|}<br />
<br />
Model lifecycle is distinct from entity lifecycle. Loading a model makes its template available for spawning one or many entities. Unloading removes that template from active memory. Neither transition represents an entity spawn, death, or removal.<br />
<br />
This distinction makes the series useful for model registries, template-specific initialization, dynamic loading systems, model analysis, custom resource maps, diagnostics, subsystem registration, teardown, and other work that should occur once per model transition instead of once per spawned entity or once per loading-screen update.<br />
<br />
== Global Usage ==<br />
<br />
Create either or both global files in <code>data/scripts</code>:<br />
<br />
* <code>data/scripts/modelload.c</code><br />
* <code>data/scripts/modelunload.c</code><br />
<br />
OpenBOR loads them automatically. <code>modelload.c</code> observes every completed model load, while <code>modelunload.c</code> observes every model immediately before it is destroyed.<br />
<br />
<syntaxhighlight lang="c" line><br />
void main()<br />
{<br />
setglobalvar("last_loaded_model_name", modelname);<br />
setglobalvar("last_loaded_model_index", modelindex);<br />
setglobalvar("model_registry_dirty", 1);<br />
}<br />
</syntaxhighlight><br />
<br />
The example is suitable for <code>modelload.c</code>. Central managers can use the reported name and index to refresh only the affected registry entry rather than scanning the full loaded-model collection during every [[Loading|loading.c]] execution.<br />
<br />
== Model Usage ==<br />
<br />
Add either command to a model definition and provide the path to its script file:<br />
<br />
<syntaxhighlight lang="text"><br />
modelloadscript data/scripts/models/boss_template_load.c<br />
modelunloadscript data/scripts/models/boss_template_unload.c<br />
</syntaxhighlight><br />
<br />
The commands belong to the model template that declares them. They do not belong to spawned entities and are not copied into entity <code>modeldata</code>.<br />
<br />
<syntaxhighlight lang="c" line><br />
void main()<br />
{<br />
setglobalvar("boss_template_ready", 1);<br />
setglobalvar("boss_template_index", modelindex);<br />
}<br />
</syntaxhighlight><br />
<br />
Model-owned callbacks are useful when one template requires specialized setup or teardown that does not belong in the global observer.<br />
<br />
Only one <code>modelloadscript</code> and one <code>modelunloadscript</code> may be assigned to a model. Global and model-owned layers may be used independently or together.<br />
<br />
== Inline Model Scripts ==<br />
<br />
Both commands support inline script blocks:<br />
<br />
<syntaxhighlight lang="text"><br />
modelloadscript @script<br />
void main()<br />
{<br />
setglobalvar("guardian_template_loaded", 1);<br />
}<br />
@end_script<br />
<br />
modelunloadscript @script<br />
void main()<br />
{<br />
setglobalvar("guardian_template_loaded", 0);<br />
}<br />
@end_script<br />
</syntaxhighlight><br />
<br />
Inline form is convenient for concise model-specific bookkeeping. External files are easier to reuse and organize when lifecycle work contains several systems or helper functions.<br />
<br />
== Event Data ==<br />
<br />
All four lifecycle hooks receive the same automatic local variables:<br />
<br />
{| class="wikitable sortable"<br />
! Variable<br />
! Type<br />
! Description<br />
|-<br />
| <code>model</code><br />
| Object pointer<br />
| Pointer to the loaded model template. The pointer is fully available during both load and unload callbacks.<br />
|-<br />
| <code>modelindex</code><br />
| Integer<br />
| Stable index of the model's cache entry.<br />
|-<br />
| <code>modelname</code><br />
| String<br />
| Name assigned to the model's cache entry.<br />
|}<br />
<br />
<syntaxhighlight lang="c" line><br />
void main()<br />
{<br />
if (model)<br />
{<br />
setglobalvar("lifecycle_model_name", modelname);<br />
setglobalvar("lifecycle_model_index", modelindex);<br />
}<br />
}<br />
</syntaxhighlight><br />
<br />
The <code>model</code> value refers to a template rather than an entity. Entity property functions and entity-local assumptions do not apply to it. Use the model property API or another model-aware system when inspecting or modifying the template.<br />
<br />
<code>modelindex</code> identifies the cache slot and remains stable when an unloadable model is later loaded again. <code>modelname</code> is safe to preserve after an unload callback. The <code>model</code> pointer is not safe to retain after unloading completes.<br />
<br />
== Model Load Event ==<br />
<br />
The load event executes only after OpenBOR successfully finishes parsing and constructing the model. Defaults, inherited model data, animations, scripts, palettes, collision information, and other declared properties have already been processed when <code>modelloadscript</code> begins.<br />
<br />
The load sequence is:<br />
<br />
# OpenBOR locates the model's existing cache entry.<br />
# The model file is read and its template is constructed.<br />
# Model properties, animations, ordinary event scripts, and lifecycle commands are parsed.<br />
# Temporary parser resources are released.<br />
# The model's <code>modelloadscript</code> executes when declared.<br />
# Global <code>data/scripts/modelload.c</code> executes when present.<br />
# The model enters its normal loaded state and the original load request receives the completed template.<br />
<br />
Model-owned logic always executes before the global observer. The global script may therefore consume registration, flags, or other state established by the model's own callback.<br />
<br />
Requesting a model that is already loaded does not produce another load event. The event represents an actual transition from cached model definition to loaded template, not each lookup or each entity spawn using that template.<br />
<br />
== Model Unload Event ==<br />
<br />
The unload event executes while the model remains intact and immediately before OpenBOR begins native destruction.<br />
<br />
The unload sequence is:<br />
<br />
# OpenBOR receives a valid request to unload a currently loaded model or begins a native model-cleanup operation.<br />
# The model's <code>modelunloadscript</code> executes when declared.<br />
# Global <code>data/scripts/modelunload.c</code> executes when present.<br />
# OpenBOR frees the template's animations, palettes, scripts, collections, and other owned resources.<br />
# The template is removed from the loaded model collection while its cache entry remains available for a later reload.<br />
<br />
Model-owned teardown always executes before the global observer. Both layers may inspect the model and coordinate cleanup while <code>model</code> is still valid.<br />
<br />
The pointer becomes invalid after the unload chain returns and native destruction begins. Cleanup systems that need persistent identification should retain <code>modelname</code>, <code>modelindex</code>, or creator-owned data instead of retaining the pointer.<br />
<br />
<syntaxhighlight lang="c" line><br />
void main()<br />
{<br />
setglobalvar("last_unloaded_model_name", modelname);<br />
setglobalvar("last_unloaded_model_index", modelindex);<br />
setglobalvar("model_registry_dirty", 1);<br />
}<br />
</syntaxhighlight><br />
<br />
The example allows a registry manager to remove or rebuild the affected entry without touching the model pointer after the event ends.<br />
<br />
== Cache and Reload Behavior ==<br />
<br />
OpenBOR distinguishes a cached model definition from a loaded model template. Entries created from <code>data/models.txt</code> retain the model name, source path, flags, and stable cache position even while the full template is unloaded.<br />
<br />
Lifecycle scripts follow transitions of the full template:<br />
<br />
* Registering the cache entry alone does not execute <code>modelload</code>.<br />
* Loading and completing the template executes the load chain once.<br />
* Looking up or requesting an already loaded template does not repeat the chain.<br />
* Unloading the template executes the unload chain once.<br />
* Loading the same cache entry again parses its model lifecycle commands and executes a new load chain.<br />
* Requesting <code>unload_model()</code> for an absent model does not load it and therefore produces no lifecycle event.<br />
<br />
This behavior provides precise change notifications without requiring a recurring scan to discover whether the loaded collection changed.<br />
<br />
== Lifecycle Safety ==<br />
<br />
OpenBOR guards lifecycle transitions against recursive self-removal and partially constructed templates. An unload request targeting the same model from its load or unload callback is ignored because that model is already inside a protected lifecycle phase.<br />
<br />
The guard keeps one callback from re-entering destruction of its own template. Lifecycle scripts may still coordinate creator-owned cleanup, request later work through flags or registries, and operate on other valid systems during the event.<br />
<br />
Model subclasses do not inherit <code>modelloadscript</code> or <code>modelunloadscript</code> from their parent template. Each subclass may declare its own lifecycle callbacks. This prevents parent and child cache entries from sharing compiled callback ownership while preserving normal inheritance for ordinary model data and supported entity event scripts.<br />
<br />
== Lifecycle Events and Entity Events ==<br />
<br />
{| class="wikitable"<br />
! Hook<br />
! Object represented<br />
! Frequency<br />
! Typical responsibility<br />
|-<br />
| <code>modelloadscript</code> and <code>modelload.c</code><br />
| Loaded model template<br />
| Once per actual template load<br />
| Template registration, analysis, and initialization<br />
|-<br />
| [[Onmodelcopyscript|onmodelcopyscript]]<br />
| Model data being copied for an entity<br />
| During applicable model-copy operations<br />
| Per-instance model-data adjustment<br />
|-<br />
| [[Onspawnscript|onspawnscript]]<br />
| Newly created entity<br />
| Once per applicable entity creation<br />
| Entity initialization<br />
|-<br />
| [[Ondeathscript|ondeathscript]]<br />
| Dying entity<br />
| During applicable entity death processing<br />
| Entity-specific death behavior<br />
|-<br />
| [[Onkillscript|onkillscript]]<br />
| Entity being removed<br />
| Immediately before applicable entity removal<br />
| Entity cleanup<br />
|-<br />
| <code>modelunloadscript</code> and <code>modelunload.c</code><br />
| Loaded model template<br />
| Once per actual template unload<br />
| Template deregistration and teardown<br />
|}<br />
<br />
One loaded model may create many entities. Model lifecycle scripts execute for the template transition, while entity events execute separately for individual instances.<br />
<br />
== Global and Model-Owned Responsibilities ==<br />
<br />
The two scopes support a useful division of responsibility:<br />
<br />
* Model-owned <code>modelloadscript</code> and <code>modelunloadscript</code> handle behavior unique to one template.<br />
* Global <code>modelload.c</code> and <code>modelunload.c</code> maintain project-wide registries and systems after the model-owned callback has run.<br />
<br />
For example, a boss model can publish its specialized combat role during <code>modelloadscript</code>. Global <code>modelload.c</code> can then add the completed template to a project-wide model registry. During removal, the model-owned callback can release its custom relationships before <code>modelunload.c</code> reconciles the common registry.<br />
<br />
== Other Uses ==<br />
<br />
Quick applications include:<br />
<br />
* '''Model registries''' - Add and remove exact cache entries without repeatedly scanning every loaded model.<br />
* '''Template analysis''' - Inspect capabilities, animations, classifications, resources, or creator-defined metadata once after parsing.<br />
* '''Subsystem registration''' - Connect models to combat managers, factories, selectors, randomizers, encounter systems, or development tools.<br />
* '''Dynamic loading''' - Track runtime <code>loadmodel()</code> and <code>unload_model()</code> transitions as they occur.<br />
* '''Model-specific initialization''' - Prepare template-owned creator state before any entity needs to use it.<br />
* '''Resource coordination''' - Build or release creator-managed lookup tables, auxiliary assets, caches, or relationships alongside a template.<br />
* '''Diagnostics''' - Log load order, unload order, names, cache indices, reloads, or unexpected lifecycle transitions.<br />
* '''Loading optimization''' - Replace repeated full-model scans in <code>loading.c</code> with exact event-driven notifications.<br />
<br />
== Related Scripts ==<br />
<br />
{| class="wikitable"<br />
! Script<br />
! Relationship<br />
|-<br />
| [[Loading|loading.c]]<br />
| Recurring loading-screen hook. Model lifecycle events provide exact template transition notifications without repeated collection scans.<br />
|-<br />
| [[Onmodelcopyscript|onmodelcopyscript]]<br />
| Executes during applicable model-data copy operations rather than model-cache loading.<br />
|-<br />
| [[Onspawnscript|onspawnscript]]<br />
| Executes for applicable entity creation after a model template is available.<br />
|-<br />
| [[Ondeathscript|ondeathscript]]<br />
| Model-owned hook for entity death processing.<br />
|-<br />
| [[Onkillscript|onkillscript]]<br />
| Model-owned hook for entity removal.<br />
|}<br />
<br />
== See Also ==<br />
<br />
* [[Loading]]<br />
* [[Model Properties]]<br />
* [[Onmodelcopyscript]]<br />
* [[Onspawnscript]]<br />
* [[Ondeathscript]]<br />
* [[Onkillscript]]<br />
* [[Models]]<br />
* [[Script Overview]]</div>Dcurrenthttps://chronocrash.com/openbor/wiki/index.php?title=Logic_Update_Scripts&diff=1066Logic Update Scripts2026-08-22T03:42:48Z<p>Dcurrent: </p>
<hr />
<div>[[Category:Level]]<br />
[[Category:Script]]<br />
'''Logical update scripts''' are recurring event hooks tied directly to [[Time#Elapsed Time|OpenBOR's logical clock]]. They provide paired entry points immediately before and after each logical tick processed by the engine.<br />
<br />
OpenBOR supplies both project-wide global files and level-specific commands:<br />
<br />
{| class="wikitable"<br />
! Hook<br />
! Scope<br />
! Execution point<br />
|-<br />
| <code>data/scripts/updatelogic.c</code><br />
| Project-wide<br />
| Before native processing for each logical tick<br />
|-<br />
| <code>updatelogicscript</code><br />
| Current level<br />
| After global <code>updatelogic.c</code>, before native tick processing<br />
|-<br />
| <code>data/scripts/updatedlogic.c</code><br />
| Project-wide<br />
| After native processing for each logical tick<br />
|-<br />
| <code>updatedlogicscript</code><br />
| Current level<br />
| After global <code>updatedlogic.c</code>, before the logical clock advances<br />
|}<br />
<br />
These hooks differ from the outer-cycle [[Update]] and [[Updated]] events. Outer update frequency may follow display synchronization, platform timing, and runtime workload. Logical update scripts instead execute once for every simulation tick OpenBOR actually processes, including each tick of a multi-tick catch-up cycle.<br />
<br />
This direct relationship to the logical clock makes the series useful for deterministic state machines, tick-accurate controllers, custom simulation systems, pre-simulation preparation, post-simulation reconciliation, replay instrumentation, synchronized hazards, and other features that should advance with engine logic rather than display frequency.<br />
<br />
== Global Usage ==<br />
<br />
Create either or both global files in <code>data/scripts</code>:<br />
<br />
* <code>data/scripts/updatelogic.c</code><br />
* <code>data/scripts/updatedlogic.c</code><br />
<br />
OpenBOR loads them automatically. Both use a <code>main()</code> entry point and receive no automatic event variables.<br />
<br />
<syntaxhighlight lang="c" line><br />
void main()<br />
{<br />
long logical_tick = openborvariant("elapsed_time");<br />
<br />
setglobalvar("logical_tick_begin", logical_tick);<br />
}<br />
</syntaxhighlight><br />
<br />
<code>updatelogic.c</code> is the first script in the logical-tick sequence. <code>updatedlogic.c</code> is the first script after native tick processing.<br />
<br />
Projects may use either hook independently or use both as a matched pair.<br />
<br />
== Level Usage ==<br />
<br />
Add either command to a level definition and provide the path to its script file:<br />
<br />
<syntaxhighlight lang="text"><br />
updatelogicscript data/scripts/levels/foundry_updatelogic.c<br />
updatedlogicscript data/scripts/levels/foundry_updatedlogic.c<br />
</syntaxhighlight><br />
<br />
Each referenced script uses a <code>main()</code> entry point and receives no automatic event variables.<br />
<br />
<syntaxhighlight lang="c" line><br />
void main()<br />
{<br />
// Perform level-specific logical-tick work here.<br />
}<br />
</syntaxhighlight><br />
<br />
OpenBOR loads these scripts with the level and executes them only while that level remains available. One <code>updatelogicscript</code> and one <code>updatedlogicscript</code> may be assigned to a level.<br />
<br />
== Inline Level Scripts ==<br />
<br />
Both level commands support inline script blocks:<br />
<br />
<syntaxhighlight lang="text"><br />
updatelogicscript @script<br />
void main()<br />
{<br />
setglobalvar("foundry_tick_active", 1);<br />
}<br />
@end_script<br />
<br />
updatedlogicscript @script<br />
void main()<br />
{<br />
setglobalvar("foundry_tick_complete", 1);<br />
}<br />
@end_script<br />
</syntaxhighlight><br />
<br />
Inline form is convenient for concise level-only behavior. External files are easier to reuse and organize when logical controllers contain several systems or helper functions.<br />
<br />
== Execution Order ==<br />
<br />
The relevant recurring sequence is:<br />
<br />
# OpenBOR begins an outer update cycle and refreshes timing and input state.<br />
# Global <code>data/scripts/update.c</code> executes when eligible.<br />
# The current level's <code>updatescript</code> executes when declared.<br />
# OpenBOR processes applicable key events and determines how many logical ticks are due.<br />
# For each logical tick:<br />
## Global <code>data/scripts/updatelogic.c</code> executes.<br />
## The current level's <code>updatelogicscript</code> executes.<br />
## OpenBOR processes native logical work, including applicable scrolling, timer, status, and entity updates.<br />
## Global <code>data/scripts/updatedlogic.c</code> executes.<br />
## The current level's <code>updatedlogicscript</code> executes.<br />
## OpenBOR advances the logical clock to the next tick.<br />
# After all due ticks finish, OpenBOR prepares the display queue.<br />
# Global <code>data/scripts/updated.c</code> executes.<br />
# The current level's <code>updatedscript</code> executes when declared.<br />
<br />
Global logic always executes before the matching level logic. Level scripts can therefore specialize or consume project-wide state established by their global counterparts during the same phase.<br />
<br />
When an outer update cycle processes several logical ticks, the complete pre-tick and post-tick chain repeats for each one. When no logical tick is due, none of the four logical hooks executes during that outer cycle.<br />
<br />
== Logical Clock Value ==<br />
<br />
Both sides of the pair observe the same logical clock value. OpenBOR executes <code>updatedlogic.c</code> and <code>updatedlogicscript</code> after native tick processing but before incrementing the clock.<br />
<br />
<syntaxhighlight lang="c" line><br />
void main()<br />
{<br />
long logical_tick = openborvariant("elapsed_time");<br />
<br />
setglobalvar("logical_tick_finished", logical_tick);<br />
}<br />
</syntaxhighlight><br />
<br />
This timing allows the early hook to capture or prepare state for tick <code>N</code>, while the late hook examines the results of that same tick <code>N</code>. The following logical iteration then begins with tick <code>N + 1</code>.<br />
<br />
OpenBOR uses a default logical rate of 200 ticks per second. Projects may configure a different logical clock rate, so scripts should use the clock value or project timing configuration when converting ticks into real-time units.<br />
<br />
== Pause and Eligibility ==<br />
<br />
Logical update scripts execute only while OpenBOR is actively processing logical ticks. Pausing prevents the logical loop from advancing, so neither the early nor late logical hook executes during paused outer cycles.<br />
<br />
The <code>alwaysupdate</code> setting expands eligibility beyond normal in-game update calls. It does not bypass pause or create a logical tick when the current outer cycle has none to process.<br />
<br />
This differs from outer-cycle <code>updated</code> hooks, which may still execute during paused in-game cycles. Systems that must remain active while paused belong in an appropriate outer update or presentation hook rather than the logical series.<br />
<br />
== Before and After Native Simulation ==<br />
<br />
<code>updatelogic</code> is suited to work that must be ready before the engine updates gameplay state. Quick applications include applying queued decisions, advancing custom input state, preparing movement rules, selecting active hazards, updating custom clocks, or publishing values that entity scripts will consume during the current tick.<br />
<br />
<code>updatedlogic</code> is suited to work that depends on the results of native processing. Quick applications include resolving objectives after entity updates, reconciling custom physics, recording resulting state, counting surviving participants, evaluating synchronized conditions, or preparing state for the next logical tick.<br />
<br />
<syntaxhighlight lang="c" line><br />
void main()<br />
{<br />
int pending_phase = getglobalvar("pending_phase");<br />
<br />
if (pending_phase)<br />
{<br />
setglobalvar("active_phase", pending_phase);<br />
setglobalvar("pending_phase", 0);<br />
}<br />
}<br />
</syntaxhighlight><br />
<br />
The example is appropriate for <code>updatelogic.c</code> when the new phase must be visible to every system during the upcoming native tick.<br />
<br />
<syntaxhighlight lang="c" line><br />
void main()<br />
{<br />
int targets_remaining = getglobalvar("targets_remaining");<br />
<br />
if (targets_remaining <= 0)<br />
{<br />
setglobalvar("pending_phase", 3);<br />
}<br />
}<br />
</syntaxhighlight><br />
<br />
The matching <code>updatedlogic.c</code> can evaluate values produced during native processing and queue a phase change for the next tick.<br />
<br />
== Choosing an Update Hook ==<br />
<br />
{| class="wikitable"<br />
! Hook<br />
! Frequency<br />
! Phase<br />
! Typical responsibility<br />
|-<br />
| Global <code>update.c</code> and level <code>updatescript</code><br />
| Once per eligible outer update cycle<br />
| Before key events and logical processing<br />
| Outer-cycle coordination and early preparation<br />
|-<br />
| Global <code>updatelogic.c</code> and level <code>updatelogicscript</code><br />
| Once per processed logical tick<br />
| Immediately before native tick work<br />
| Tick-accurate preparation and custom simulation input<br />
|-<br />
| [[Updateentityscript|updateentityscript]]<br />
| During applicable entity updates<br />
| Within native logical processing<br />
| Per-entity recurring behavior<br />
|-<br />
| Global <code>updatedlogic.c</code> and level <code>updatedlogicscript</code><br />
| Once per processed logical tick<br />
| After native tick work, before clock advancement<br />
| Tick-accurate resolution and resulting-state inspection<br />
|-<br />
| Global <code>updated.c</code> and level <code>updatedscript</code><br />
| Once per eligible outer update cycle<br />
| After logical processing and display preparation<br />
| Late-cycle coordination and presentation<br />
|}<br />
<br />
Display synchronization does not define logical-script frequency. One outer cycle may process zero, one, or several logical ticks, and the logical hooks follow the tick count exactly.<br />
<br />
== Other Uses ==<br />
<br />
Quick applications include:<br />
<br />
* '''Deterministic controllers''' - Advance custom state machines exactly once per engine logical tick.<br />
* '''Custom simulation''' - Run project-defined movement, resources, hazards, clocks, or world systems beside native logic.<br />
* '''Pre-tick preparation''' - Publish values, apply queued commands, choose rules, or establish state consumed during the current tick.<br />
* '''Post-tick reconciliation''' - Evaluate entity results, resolve simultaneous conditions, or queue changes for the next tick.<br />
* '''Synchronized encounters''' - Coordinate hazards, waves, objectives, formations, or multi-part sequences on a common clock.<br />
* '''Replay and diagnostics''' - Record pre-tick and post-tick state, identify the exact logical time of a change, or compare deterministic results.<br />
* '''Level simulation''' - Keep stage-specific clock logic with the level while common systems remain in the global files.<br />
* '''Timing tools''' - Build profilers, counters, test harnesses, or controlled simulation instrumentation around exact tick boundaries.<br />
<br />
== Related Scripts ==<br />
<br />
{| class="wikitable"<br />
! Script<br />
! Relationship<br />
|-<br />
| [[Update|update.c]]<br />
| Global early outer-cycle hook that executes before logical processing begins.<br />
|-<br />
| [[Updatescript (Level)|updatescript]]<br />
| Level-specific early outer-cycle hook.<br />
|-<br />
| [[Updateentityscript|updateentityscript]]<br />
| Model hook executed for individual entities during native logical processing.<br />
|-<br />
| [[Updated|updated.c]]<br />
| Global late outer-cycle hook that executes after all due logical ticks.<br />
|-<br />
| [[Updatedscript (Level)|updatedscript]]<br />
| Level-specific late outer-cycle hook.<br />
|}<br />
<br />
== See Also ==<br />
<br />
* [[Update]]<br />
* [[Updatescript (Level)]]<br />
* [[Updateentityscript]]<br />
* [[Updated]]<br />
* [[Updatedscript (Level)]]<br />
* [[Time]]<br />
* [[Enhanced Delay]]<br />
* [[Script Overview]]<br />
[[Category:Openbor]]</div>Dcurrenthttps://chronocrash.com/openbor/wiki/index.php?title=Updatedlogicscript&diff=1065Updatedlogicscript2026-08-22T03:42:05Z<p>Dcurrent: Redirected page to Logic Update Scripts#Level Usage</p>
<hr />
<div>#REDIRECT [[Logic_Update_Scripts#Level_Usage]]<br />
[[Category:Level]]<br />
[[Category:OpenBOR Index]]<br />
[[Category:Script Events]]</div>Dcurrenthttps://chronocrash.com/openbor/wiki/index.php?title=Updatelogicscript&diff=1064Updatelogicscript2026-08-22T03:41:49Z<p>Dcurrent: Redirected page to Logic Update Scripts#Level Usage</p>
<hr />
<div>#REDIRECT [[Logic_Update_Scripts#Level_Usage]]<br />
[[Category:Level]]<br />
[[Category:OpenBOR Index]]<br />
[[Category:Script Events]]</div>Dcurrenthttps://chronocrash.com/openbor/wiki/index.php?title=Updatedlogic&diff=1063Updatedlogic2026-08-22T03:40:54Z<p>Dcurrent: Redirected page to Logic Update Scripts#Global Usage</p>
<hr />
<div>#REDIRECT [[Logic Update Scripts#Global Usage]]<br />
[[Category:Level]]<br />
[[Category:OpenBOR Index]]<br />
[[Category:Script Events]]</div>Dcurrenthttps://chronocrash.com/openbor/wiki/index.php?title=Updatelogic&diff=1062Updatelogic2026-08-22T03:40:37Z<p>Dcurrent: Redirected page to Logic Update Scripts#Global Usage</p>
<hr />
<div>#REDIRECT [[Logic Update Scripts#Global Usage]]<br />
[[Category:Level]]<br />
[[Category:OpenBOR Index]]<br />
[[Category:Script Events]]</div>Dcurrenthttps://chronocrash.com/openbor/wiki/index.php?title=Logic_Update_Scripts&diff=1061Logic Update Scripts2026-08-22T03:39:23Z<p>Dcurrent: </p>
<hr />
<div>[[Category:Level]]<br />
[[Category:Script]]<br />
[[Category:Script Events]]<br />
<br />
'''Logical update scripts''' are recurring event hooks tied directly to [[Time#Elapsed Time|OpenBOR's logical clock]]. They provide paired entry points immediately before and after each logical tick processed by the engine.<br />
<br />
OpenBOR supplies both project-wide global files and level-specific commands:<br />
<br />
{| class="wikitable"<br />
! Hook<br />
! Scope<br />
! Execution point<br />
|-<br />
| <code>data/scripts/updatelogic.c</code><br />
| Project-wide<br />
| Before native processing for each logical tick<br />
|-<br />
| <code>updatelogicscript</code><br />
| Current level<br />
| After global <code>updatelogic.c</code>, before native tick processing<br />
|-<br />
| <code>data/scripts/updatedlogic.c</code><br />
| Project-wide<br />
| After native processing for each logical tick<br />
|-<br />
| <code>updatedlogicscript</code><br />
| Current level<br />
| After global <code>updatedlogic.c</code>, before the logical clock advances<br />
|}<br />
<br />
These hooks differ from the outer-cycle [[Update]] and [[Updated]] events. Outer update frequency may follow display synchronization, platform timing, and runtime workload. Logical update scripts instead execute once for every simulation tick OpenBOR actually processes, including each tick of a multi-tick catch-up cycle.<br />
<br />
This direct relationship to the logical clock makes the series useful for deterministic state machines, tick-accurate controllers, custom simulation systems, pre-simulation preparation, post-simulation reconciliation, replay instrumentation, synchronized hazards, and other features that should advance with engine logic rather than display frequency.<br />
<br />
== Global Usage ==<br />
<br />
Create either or both global files in <code>data/scripts</code>:<br />
<br />
* <code>data/scripts/updatelogic.c</code><br />
* <code>data/scripts/updatedlogic.c</code><br />
<br />
OpenBOR loads them automatically. Both use a <code>main()</code> entry point and receive no automatic event variables.<br />
<br />
<syntaxhighlight lang="c" line><br />
void main()<br />
{<br />
long logical_tick = openborvariant("elapsed_time");<br />
<br />
setglobalvar("logical_tick_begin", logical_tick);<br />
}<br />
</syntaxhighlight><br />
<br />
<code>updatelogic.c</code> is the first script in the logical-tick sequence. <code>updatedlogic.c</code> is the first script after native tick processing.<br />
<br />
Projects may use either hook independently or use both as a matched pair.<br />
<br />
== Level Usage ==<br />
<br />
Add either command to a level definition and provide the path to its script file:<br />
<br />
<syntaxhighlight lang="text"><br />
updatelogicscript data/scripts/levels/foundry_updatelogic.c<br />
updatedlogicscript data/scripts/levels/foundry_updatedlogic.c<br />
</syntaxhighlight><br />
<br />
Each referenced script uses a <code>main()</code> entry point and receives no automatic event variables.<br />
<br />
<syntaxhighlight lang="c" line><br />
void main()<br />
{<br />
// Perform level-specific logical-tick work here.<br />
}<br />
</syntaxhighlight><br />
<br />
OpenBOR loads these scripts with the level and executes them only while that level remains available. One <code>updatelogicscript</code> and one <code>updatedlogicscript</code> may be assigned to a level.<br />
<br />
== Inline Level Scripts ==<br />
<br />
Both level commands support inline script blocks:<br />
<br />
<syntaxhighlight lang="text"><br />
updatelogicscript @script<br />
void main()<br />
{<br />
setglobalvar("foundry_tick_active", 1);<br />
}<br />
@end_script<br />
<br />
updatedlogicscript @script<br />
void main()<br />
{<br />
setglobalvar("foundry_tick_complete", 1);<br />
}<br />
@end_script<br />
</syntaxhighlight><br />
<br />
Inline form is convenient for concise level-only behavior. External files are easier to reuse and organize when logical controllers contain several systems or helper functions.<br />
<br />
== Execution Order ==<br />
<br />
The relevant recurring sequence is:<br />
<br />
# OpenBOR begins an outer update cycle and refreshes timing and input state.<br />
# Global <code>data/scripts/update.c</code> executes when eligible.<br />
# The current level's <code>updatescript</code> executes when declared.<br />
# OpenBOR processes applicable key events and determines how many logical ticks are due.<br />
# For each logical tick:<br />
## Global <code>data/scripts/updatelogic.c</code> executes.<br />
## The current level's <code>updatelogicscript</code> executes.<br />
## OpenBOR processes native logical work, including applicable scrolling, timer, status, and entity updates.<br />
## Global <code>data/scripts/updatedlogic.c</code> executes.<br />
## The current level's <code>updatedlogicscript</code> executes.<br />
## OpenBOR advances the logical clock to the next tick.<br />
# After all due ticks finish, OpenBOR prepares the display queue.<br />
# Global <code>data/scripts/updated.c</code> executes.<br />
# The current level's <code>updatedscript</code> executes when declared.<br />
<br />
Global logic always executes before the matching level logic. Level scripts can therefore specialize or consume project-wide state established by their global counterparts during the same phase.<br />
<br />
When an outer update cycle processes several logical ticks, the complete pre-tick and post-tick chain repeats for each one. When no logical tick is due, none of the four logical hooks executes during that outer cycle.<br />
<br />
== Logical Clock Value ==<br />
<br />
Both sides of the pair observe the same logical clock value. OpenBOR executes <code>updatedlogic.c</code> and <code>updatedlogicscript</code> after native tick processing but before incrementing the clock.<br />
<br />
<syntaxhighlight lang="c" line><br />
void main()<br />
{<br />
long logical_tick = openborvariant("elapsed_time");<br />
<br />
setglobalvar("logical_tick_finished", logical_tick);<br />
}<br />
</syntaxhighlight><br />
<br />
This timing allows the early hook to capture or prepare state for tick <code>N</code>, while the late hook examines the results of that same tick <code>N</code>. The following logical iteration then begins with tick <code>N + 1</code>.<br />
<br />
OpenBOR uses a default logical rate of 200 ticks per second. Projects may configure a different logical clock rate, so scripts should use the clock value or project timing configuration when converting ticks into real-time units.<br />
<br />
== Pause and Eligibility ==<br />
<br />
Logical update scripts execute only while OpenBOR is actively processing logical ticks. Pausing prevents the logical loop from advancing, so neither the early nor late logical hook executes during paused outer cycles.<br />
<br />
The <code>alwaysupdate</code> setting expands eligibility beyond normal in-game update calls. It does not bypass pause or create a logical tick when the current outer cycle has none to process.<br />
<br />
This differs from outer-cycle <code>updated</code> hooks, which may still execute during paused in-game cycles. Systems that must remain active while paused belong in an appropriate outer update or presentation hook rather than the logical series.<br />
<br />
== Before and After Native Simulation ==<br />
<br />
<code>updatelogic</code> is suited to work that must be ready before the engine updates gameplay state. Quick applications include applying queued decisions, advancing custom input state, preparing movement rules, selecting active hazards, updating custom clocks, or publishing values that entity scripts will consume during the current tick.<br />
<br />
<code>updatedlogic</code> is suited to work that depends on the results of native processing. Quick applications include resolving objectives after entity updates, reconciling custom physics, recording resulting state, counting surviving participants, evaluating synchronized conditions, or preparing state for the next logical tick.<br />
<br />
<syntaxhighlight lang="c" line><br />
void main()<br />
{<br />
int pending_phase = getglobalvar("pending_phase");<br />
<br />
if (pending_phase)<br />
{<br />
setglobalvar("active_phase", pending_phase);<br />
setglobalvar("pending_phase", 0);<br />
}<br />
}<br />
</syntaxhighlight><br />
<br />
The example is appropriate for <code>updatelogic.c</code> when the new phase must be visible to every system during the upcoming native tick.<br />
<br />
<syntaxhighlight lang="c" line><br />
void main()<br />
{<br />
int targets_remaining = getglobalvar("targets_remaining");<br />
<br />
if (targets_remaining <= 0)<br />
{<br />
setglobalvar("pending_phase", 3);<br />
}<br />
}<br />
</syntaxhighlight><br />
<br />
The matching <code>updatedlogic.c</code> can evaluate values produced during native processing and queue a phase change for the next tick.<br />
<br />
== Choosing an Update Hook ==<br />
<br />
{| class="wikitable"<br />
! Hook<br />
! Frequency<br />
! Phase<br />
! Typical responsibility<br />
|-<br />
| Global <code>update.c</code> and level <code>updatescript</code><br />
| Once per eligible outer update cycle<br />
| Before key events and logical processing<br />
| Outer-cycle coordination and early preparation<br />
|-<br />
| Global <code>updatelogic.c</code> and level <code>updatelogicscript</code><br />
| Once per processed logical tick<br />
| Immediately before native tick work<br />
| Tick-accurate preparation and custom simulation input<br />
|-<br />
| [[Updateentityscript|updateentityscript]]<br />
| During applicable entity updates<br />
| Within native logical processing<br />
| Per-entity recurring behavior<br />
|-<br />
| Global <code>updatedlogic.c</code> and level <code>updatedlogicscript</code><br />
| Once per processed logical tick<br />
| After native tick work, before clock advancement<br />
| Tick-accurate resolution and resulting-state inspection<br />
|-<br />
| Global <code>updated.c</code> and level <code>updatedscript</code><br />
| Once per eligible outer update cycle<br />
| After logical processing and display preparation<br />
| Late-cycle coordination and presentation<br />
|}<br />
<br />
Display synchronization does not define logical-script frequency. One outer cycle may process zero, one, or several logical ticks, and the logical hooks follow the tick count exactly.<br />
<br />
== Other Uses ==<br />
<br />
Quick applications include:<br />
<br />
* '''Deterministic controllers''' - Advance custom state machines exactly once per engine logical tick.<br />
* '''Custom simulation''' - Run project-defined movement, resources, hazards, clocks, or world systems beside native logic.<br />
* '''Pre-tick preparation''' - Publish values, apply queued commands, choose rules, or establish state consumed during the current tick.<br />
* '''Post-tick reconciliation''' - Evaluate entity results, resolve simultaneous conditions, or queue changes for the next tick.<br />
* '''Synchronized encounters''' - Coordinate hazards, waves, objectives, formations, or multi-part sequences on a common clock.<br />
* '''Replay and diagnostics''' - Record pre-tick and post-tick state, identify the exact logical time of a change, or compare deterministic results.<br />
* '''Level simulation''' - Keep stage-specific clock logic with the level while common systems remain in the global files.<br />
* '''Timing tools''' - Build profilers, counters, test harnesses, or controlled simulation instrumentation around exact tick boundaries.<br />
<br />
== Related Scripts ==<br />
<br />
{| class="wikitable"<br />
! Script<br />
! Relationship<br />
|-<br />
| [[Update|update.c]]<br />
| Global early outer-cycle hook that executes before logical processing begins.<br />
|-<br />
| [[Updatescript (Level)|updatescript]]<br />
| Level-specific early outer-cycle hook.<br />
|-<br />
| [[Updateentityscript|updateentityscript]]<br />
| Model hook executed for individual entities during native logical processing.<br />
|-<br />
| [[Updated|updated.c]]<br />
| Global late outer-cycle hook that executes after all due logical ticks.<br />
|-<br />
| [[Updatedscript (Level)|updatedscript]]<br />
| Level-specific late outer-cycle hook.<br />
|}<br />
<br />
== See Also ==<br />
<br />
* [[Update]]<br />
* [[Updatescript (Level)]]<br />
* [[Updateentityscript]]<br />
* [[Updated]]<br />
* [[Updatedscript (Level)]]<br />
* [[Time]]<br />
* [[Enhanced Delay]]<br />
* [[Script Overview]]</div>Dcurrenthttps://chronocrash.com/openbor/wiki/index.php?title=Logic_Update_Scripts&diff=1060Logic Update Scripts2026-08-22T03:37:01Z<p>Dcurrent: Created page with "Category:Level Category:Script Category:Script Events '''Logical update scripts''' are recurring event hooks tied directly to OpenBOR's logical clock. They provide paired entry points immediately before and after each logical tick processed by the engine. OpenBOR supplies both project-wide global files and level-specific commands: {| class="wikitable" ! Hook ! Scope ! Execution point |- | <code>data/scripts/updatelogic.c</code> | Project-wide | Before nati..."</p>
<hr />
<div>[[Category:Level]]<br />
[[Category:Script]]<br />
[[Category:Script Events]]<br />
<br />
'''Logical update scripts''' are recurring event hooks tied directly to OpenBOR's logical clock. They provide paired entry points immediately before and after each logical tick processed by the engine.<br />
<br />
OpenBOR supplies both project-wide global files and level-specific commands:<br />
<br />
{| class="wikitable"<br />
! Hook<br />
! Scope<br />
! Execution point<br />
|-<br />
| <code>data/scripts/updatelogic.c</code><br />
| Project-wide<br />
| Before native processing for each logical tick<br />
|-<br />
| <code>updatelogicscript</code><br />
| Current level<br />
| After global <code>updatelogic.c</code>, before native tick processing<br />
|-<br />
| <code>data/scripts/updatedlogic.c</code><br />
| Project-wide<br />
| After native processing for each logical tick<br />
|-<br />
| <code>updatedlogicscript</code><br />
| Current level<br />
| After global <code>updatedlogic.c</code>, before the logical clock advances<br />
|}<br />
<br />
These hooks differ from the outer-cycle [[Update]] and [[Updated]] events. Outer update frequency may follow display synchronization, platform timing, and runtime workload. Logical update scripts instead execute once for every simulation tick OpenBOR actually processes, including each tick of a multi-tick catch-up cycle.<br />
<br />
This direct relationship to the logical clock makes the series useful for deterministic state machines, tick-accurate controllers, custom simulation systems, pre-simulation preparation, post-simulation reconciliation, replay instrumentation, synchronized hazards, and other features that should advance with engine logic rather than display frequency.<br />
<br />
== Global Usage ==<br />
<br />
Create either or both global files in <code>data/scripts</code>:<br />
<br />
* <code>data/scripts/updatelogic.c</code><br />
* <code>data/scripts/updatedlogic.c</code><br />
<br />
OpenBOR loads them automatically. Both use a <code>main()</code> entry point and receive no automatic event variables.<br />
<br />
<syntaxhighlight lang="c" line><br />
void main()<br />
{<br />
long logical_tick = openborvariant("elapsed_time");<br />
<br />
setglobalvar("logical_tick_begin", logical_tick);<br />
}<br />
</syntaxhighlight><br />
<br />
<code>updatelogic.c</code> is the first script in the logical-tick sequence. <code>updatedlogic.c</code> is the first script after native tick processing.<br />
<br />
Projects may use either hook independently or use both as a matched pair.<br />
<br />
== Level Usage ==<br />
<br />
Add either command to a level definition and provide the path to its script file:<br />
<br />
<syntaxhighlight lang="text"><br />
updatelogicscript data/scripts/levels/foundry_updatelogic.c<br />
updatedlogicscript data/scripts/levels/foundry_updatedlogic.c<br />
</syntaxhighlight><br />
<br />
Each referenced script uses a <code>main()</code> entry point and receives no automatic event variables.<br />
<br />
<syntaxhighlight lang="c" line><br />
void main()<br />
{<br />
// Perform level-specific logical-tick work here.<br />
}<br />
</syntaxhighlight><br />
<br />
OpenBOR loads these scripts with the level and executes them only while that level remains available. One <code>updatelogicscript</code> and one <code>updatedlogicscript</code> may be assigned to a level.<br />
<br />
== Inline Level Scripts ==<br />
<br />
Both level commands support inline script blocks:<br />
<br />
<syntaxhighlight lang="text"><br />
updatelogicscript @script<br />
void main()<br />
{<br />
setglobalvar("foundry_tick_active", 1);<br />
}<br />
@end_script<br />
<br />
updatedlogicscript @script<br />
void main()<br />
{<br />
setglobalvar("foundry_tick_complete", 1);<br />
}<br />
@end_script<br />
</syntaxhighlight><br />
<br />
Inline form is convenient for concise level-only behavior. External files are easier to reuse and organize when logical controllers contain several systems or helper functions.<br />
<br />
== Execution Order ==<br />
<br />
The relevant recurring sequence is:<br />
<br />
# OpenBOR begins an outer update cycle and refreshes timing and input state.<br />
# Global <code>data/scripts/update.c</code> executes when eligible.<br />
# The current level's <code>updatescript</code> executes when declared.<br />
# OpenBOR processes applicable key events and determines how many logical ticks are due.<br />
# For each logical tick:<br />
## Global <code>data/scripts/updatelogic.c</code> executes.<br />
## The current level's <code>updatelogicscript</code> executes.<br />
## OpenBOR processes native logical work, including applicable scrolling, timer, status, and entity updates.<br />
## Global <code>data/scripts/updatedlogic.c</code> executes.<br />
## The current level's <code>updatedlogicscript</code> executes.<br />
## OpenBOR advances the logical clock to the next tick.<br />
# After all due ticks finish, OpenBOR prepares the display queue.<br />
# Global <code>data/scripts/updated.c</code> executes.<br />
# The current level's <code>updatedscript</code> executes when declared.<br />
<br />
Global logic always executes before the matching level logic. Level scripts can therefore specialize or consume project-wide state established by their global counterparts during the same phase.<br />
<br />
When an outer update cycle processes several logical ticks, the complete pre-tick and post-tick chain repeats for each one. When no logical tick is due, none of the four logical hooks executes during that outer cycle.<br />
<br />
== Logical Clock Value ==<br />
<br />
Both sides of the pair observe the same logical clock value. OpenBOR executes <code>updatedlogic.c</code> and <code>updatedlogicscript</code> after native tick processing but before incrementing the clock.<br />
<br />
<syntaxhighlight lang="c" line><br />
void main()<br />
{<br />
long logical_tick = openborvariant("elapsed_time");<br />
<br />
setglobalvar("logical_tick_finished", logical_tick);<br />
}<br />
</syntaxhighlight><br />
<br />
This timing allows the early hook to capture or prepare state for tick <code>N</code>, while the late hook examines the results of that same tick <code>N</code>. The following logical iteration then begins with tick <code>N + 1</code>.<br />
<br />
OpenBOR uses a default logical rate of 200 ticks per second. Projects may configure a different logical clock rate, so scripts should use the clock value or project timing configuration when converting ticks into real-time units.<br />
<br />
== Pause and Eligibility ==<br />
<br />
Logical update scripts execute only while OpenBOR is actively processing logical ticks. Pausing prevents the logical loop from advancing, so neither the early nor late logical hook executes during paused outer cycles.<br />
<br />
The <code>alwaysupdate</code> setting expands eligibility beyond normal in-game update calls. It does not bypass pause or create a logical tick when the current outer cycle has none to process.<br />
<br />
This differs from outer-cycle <code>updated</code> hooks, which may still execute during paused in-game cycles. Systems that must remain active while paused belong in an appropriate outer update or presentation hook rather than the logical series.<br />
<br />
== Before and After Native Simulation ==<br />
<br />
<code>updatelogic</code> is suited to work that must be ready before the engine updates gameplay state. Quick applications include applying queued decisions, advancing custom input state, preparing movement rules, selecting active hazards, updating custom clocks, or publishing values that entity scripts will consume during the current tick.<br />
<br />
<code>updatedlogic</code> is suited to work that depends on the results of native processing. Quick applications include resolving objectives after entity updates, reconciling custom physics, recording resulting state, counting surviving participants, evaluating synchronized conditions, or preparing state for the next logical tick.<br />
<br />
<syntaxhighlight lang="c" line><br />
void main()<br />
{<br />
int pending_phase = getglobalvar("pending_phase");<br />
<br />
if (pending_phase)<br />
{<br />
setglobalvar("active_phase", pending_phase);<br />
setglobalvar("pending_phase", 0);<br />
}<br />
}<br />
</syntaxhighlight><br />
<br />
The example is appropriate for <code>updatelogic.c</code> when the new phase must be visible to every system during the upcoming native tick.<br />
<br />
<syntaxhighlight lang="c" line><br />
void main()<br />
{<br />
int targets_remaining = getglobalvar("targets_remaining");<br />
<br />
if (targets_remaining <= 0)<br />
{<br />
setglobalvar("pending_phase", 3);<br />
}<br />
}<br />
</syntaxhighlight><br />
<br />
The matching <code>updatedlogic.c</code> can evaluate values produced during native processing and queue a phase change for the next tick.<br />
<br />
== Choosing an Update Hook ==<br />
<br />
{| class="wikitable"<br />
! Hook<br />
! Frequency<br />
! Phase<br />
! Typical responsibility<br />
|-<br />
| Global <code>update.c</code> and level <code>updatescript</code><br />
| Once per eligible outer update cycle<br />
| Before key events and logical processing<br />
| Outer-cycle coordination and early preparation<br />
|-<br />
| Global <code>updatelogic.c</code> and level <code>updatelogicscript</code><br />
| Once per processed logical tick<br />
| Immediately before native tick work<br />
| Tick-accurate preparation and custom simulation input<br />
|-<br />
| [[Updateentityscript|updateentityscript]]<br />
| During applicable entity updates<br />
| Within native logical processing<br />
| Per-entity recurring behavior<br />
|-<br />
| Global <code>updatedlogic.c</code> and level <code>updatedlogicscript</code><br />
| Once per processed logical tick<br />
| After native tick work, before clock advancement<br />
| Tick-accurate resolution and resulting-state inspection<br />
|-<br />
| Global <code>updated.c</code> and level <code>updatedscript</code><br />
| Once per eligible outer update cycle<br />
| After logical processing and display preparation<br />
| Late-cycle coordination and presentation<br />
|}<br />
<br />
Display synchronization does not define logical-script frequency. One outer cycle may process zero, one, or several logical ticks, and the logical hooks follow the tick count exactly.<br />
<br />
== Other Uses ==<br />
<br />
Quick applications include:<br />
<br />
* '''Deterministic controllers''' - Advance custom state machines exactly once per engine logical tick.<br />
* '''Custom simulation''' - Run project-defined movement, resources, hazards, clocks, or world systems beside native logic.<br />
* '''Pre-tick preparation''' - Publish values, apply queued commands, choose rules, or establish state consumed during the current tick.<br />
* '''Post-tick reconciliation''' - Evaluate entity results, resolve simultaneous conditions, or queue changes for the next tick.<br />
* '''Synchronized encounters''' - Coordinate hazards, waves, objectives, formations, or multi-part sequences on a common clock.<br />
* '''Replay and diagnostics''' - Record pre-tick and post-tick state, identify the exact logical time of a change, or compare deterministic results.<br />
* '''Level simulation''' - Keep stage-specific clock logic with the level while common systems remain in the global files.<br />
* '''Timing tools''' - Build profilers, counters, test harnesses, or controlled simulation instrumentation around exact tick boundaries.<br />
<br />
== Related Scripts ==<br />
<br />
{| class="wikitable"<br />
! Script<br />
! Relationship<br />
|-<br />
| [[Update|update.c]]<br />
| Global early outer-cycle hook that executes before logical processing begins.<br />
|-<br />
| [[Updatescript (Level)|updatescript]]<br />
| Level-specific early outer-cycle hook.<br />
|-<br />
| [[Updateentityscript|updateentityscript]]<br />
| Model hook executed for individual entities during native logical processing.<br />
|-<br />
| [[Updated|updated.c]]<br />
| Global late outer-cycle hook that executes after all due logical ticks.<br />
|-<br />
| [[Updatedscript (Level)|updatedscript]]<br />
| Level-specific late outer-cycle hook.<br />
|}<br />
<br />
== See Also ==<br />
<br />
* [[Update]]<br />
* [[Updatescript (Level)]]<br />
* [[Updateentityscript]]<br />
* [[Updated]]<br />
* [[Updatedscript (Level)]]<br />
* [[Time]]<br />
* [[Enhanced Delay]]<br />
* [[Script Overview]]</div>Dcurrenthttps://chronocrash.com/openbor/wiki/index.php?title=Main_Page&diff=1059Main Page2026-08-21T02:31:20Z<p>Dcurrent: /* Essential Tools */</p>
<hr />
<div>== Introduction ==<br />
<br />
=== What is OpenBOR? ===<br />
OpenBOR is a royalty-free, open-source engine for sprite-based games. It combines a complete native game framework - including controls, movement, combat, artificial intelligence, levels, audio, menus, saving, and local multiplayer - with an integrated C-like scripting language that can extend or replace nearly every system.<br />
<br />
OpenBOR specializes in side-scrolling action games such as Double Dragon and Streets of Rage, but its three-dimensional game world, configurable simulation, declarative object system, and scriptable graphics pipeline also support platformers, shooters, role-playing games, puzzle games, and other genres.<br />
<br />
Beginners can build complete games primarily from assets and configuration. Advanced creators can manipulate engine objects, replace native behavior, construct rendering pipelines, and even compile new script programs while a module is running.<br />
<br />
=== Why OpenBOR? ===<br />
What sets OpenBOR apart is how far it extends in both directions. Creators do not need to build their own asset handling, controls, movement, artificial intelligence, collision and combat logic, audio playback, or other foundational systems. Everything is integrated and ready to use. Gather the assets and a fully functional game can be running within hours.<br />
<br />
At the opposite extreme, OpenBOR exposes low-level primitives and engine objects through configuration and script. Creators can inspect runtime state, customize selected behavior, replace complete subsystems, or build new ones without modifying engine source or depending on third-party plugins. Native functionality is therefore a starting point, not a boundary.<br />
<br />
* '''Complete native gameplay''' - Controls, movement, gravity, level trees, platforms, combat, blocking, grabbing, throwing, artificial intelligence, cameras, audio, menus, HUDs, and saving work without custom code.<br />
* '''[[Script Overview|Engine-wide scripting]]''' - Object APIs and dozens of [[:Category:Script Events|event hooks]] expose input, animation, movement, collision, damage, spawning, audio, drawing, and other runtime systems for inspection, modification, or replacement.<br />
* '''[[Time|High-resolution simulation]]''' - The configurable logical clock runs at 200 Hz by default and remains independent of display updates.<br />
* '''[[Geometry Overview|Three-dimensional sprite worlds]]''' - Floating-point X, Y, and Z geometry provides subpixel movement, terrain, altitude, and depth sorting.<br />
* '''[[Collision|Declarative combat collision]]''' - Indexed three-dimensional attack and body boxes carry damage, reaction, motion, status, and presentation behavior.<br />
* '''[[Factions|Composable relationships]]''' - Four independent 52-bit faction masks provide hardware-speed membership, hostility, direct-damage, and indirect-damage rules.<br />
* '''[[Subscreens|Recursive graphics composition]]''' - Script-created subscreens support nested rendering, layer capture, transformations, masks, split screens, and feedback effects.<br />
* '''[[Runtime Script Compilation|Runtime metaprogramming]]''' - Modules can load and combine source files, compile them into independently owned programs, retain persistent state, execute them repeatedly, and replace them during play.<br />
* '''Optimized performance -''' Native systems, high-frequency simulation, and script integration are engineered to maintain steady frame rates and butter smooth motion with dozens or hundreds of active objects.<br />
<br />
== Getting Started ==<br />
<br />
'''[https://www.chronocrash.com/forum/resources/openbor.1/ Download OpenBOR]''' | '''[https://www.chronocrash.com/forum/resources/categories/samples-and-tutorials.5/?prefix_id=3 Start Building]''' | '''[[:Category:Openbor|Browse the Reference]]''' | '''[https://chronocrash.com Visit the Community]''' | '''[https://github.com/DCurrent/openbor View the Source]'''<br />
<br />
This wiki is the comprehensive technical reference for OpenBOR, but please note it is not intended as a walk-through. For more in-depth instruction, consult the tutorials and guides available through the [https://chronocrash.com/forum ChronoCrash community].<br />
<br />
=== Guides and Resources ===<br />
<br />
* [[OpenBOR Overview]] – General overview of OpenBOR functionality and runtime layout.<br />
* [[:Category:Openbor|OpenBOR Hub]] – Main jumping off point for categories and individual wiki articles.<br />
* [[:Category:OpenBOR Index|OpenBOR Index]] – Simple index of OpenBOR commands, settings, and functions.<br />
* [[Legacy Manual]] – Archival monolithic manual.<br />
* [https://chronocrash.com/ ChronoCrash] – OpenBOR’s home community, including its help forum, downloadable games, and in-depth tutorials.<br />
* [https://github.com/DCurrent/openbor OpenBOR Repository] – Public-facing OpenBOR code base.<br />
<br />
== Development Environment ==<br />
<br />
=== Essential Tools ===<br />
<br />
The following tools are needed to begin building games with OpenBOR. You will need a [https://chronocrash.com/forum ChronoCrash community] account to download some resources.<br />
<br />
* [https://www.chronocrash.com/forum/resources/categories/engine.3/ OpenBOR engine executable] – The latest stable engine release.<br />
* '''[https://www.chronocrash.com/forum/resources/neo-edit-pack.2/ Edit Pack]''' – Tools for packing and unpacking OpenBOR game modules.<br />
* '''Development environment''' – OpenBOR uses a combination of text files and optional script files to configure game functionality. Any text editor may be used. [https://code.visualstudio.com/ Visual Studio Code] is recommended, together with [https://github.com Git] or another version-control system for managing project files.<br />
* '''Graphics software''' – Any graphics-editing application capable of exporting <code>.png</code> images. [https://www.adobe.com Adobe Photoshop] or [https://www.gimp.org/ GIMP] are recommended.<br />
* '''Audio software''' – An audio-editing application capable of exporting <code>.wav</code> files for sound effects and, optionally, <code>.ogg</code> files for music. [https://www.adobe.com/products/audition.html Adobe Audition] or [https://www.audacityteam.org/ Audacity] are recommended.<br />
<br />
=== Optional Tools ===<br />
<br />
These tools are optional but highly recommended.<br />
<br />
* '''[https://www.chronocrash.com/forum/resources/chronocrash-modders-tools.139/ ChronoCrash Modders Tools (CMT)]''' – Visual editing application for building OpenBOR games.<br />
* '''[https://www.chronocrash.com/forum/resources/palapply.15/ PalApply]''' – Applies a palette to one or more images and exports optimized <code>.png</code> files ready for use with OpenBOR.<br />
<br />
== What Open Source Means ==<br />
Because the term has caused confusion and disputes in the past, it is important to clarify what open source means in the context of OpenBOR.<br />
<br />
OpenBOR’s existing codebase is available under a permissive [https://github.com/DCurrent/openbor/blob/master/LICENSE BSD-derived license]. '''Creators may use the engine to make, license, and sell games and other content they rightfully own.''' The OpenBOR license does not claim or control that content.<br />
<br />
Open source does not mean a free-for-all. It provides no implied permission to modify or redistribute another creator’s work without consent. The license also permits binary distribution without requiring source disclosure - it does not compel the team to release existing or future source code, and by extension it does not entitle anyone to the source code of closed-source extensions or obligate the development team to release it. The public repository is provided and maintained as a voluntary act of good faith, not as an obligation imposed by the license.<br />
<br />
The OpenBOR development team may produce proprietary features, such as encrypted pack handling, and license them separately at its discretion.</div>Dcurrenthttps://chronocrash.com/openbor/wiki/index.php?title=Respawn4&diff=1058Respawn42026-08-21T01:56:41Z<p>Dcurrent: </p>
<hr />
<div>#REDIRECT [[Player Respawn Scripts]]<br />
[[Category:OpenBOR Index]]<br />
[[Category:Player]]<br />
[[Category:Script Events]]</div>Dcurrenthttps://chronocrash.com/openbor/wiki/index.php?title=Respawn3&diff=1057Respawn32026-08-21T01:56:26Z<p>Dcurrent: </p>
<hr />
<div>#REDIRECT [[Player Respawn Scripts]]<br />
[[Category:OpenBOR Index]]<br />
[[Category:Player]]<br />
[[Category:Script Events]]</div>Dcurrenthttps://chronocrash.com/openbor/wiki/index.php?title=Respawn2&diff=1056Respawn22026-08-21T01:55:55Z<p>Dcurrent: </p>
<hr />
<div>#REDIRECT [[Player Respawn Scripts]]<br />
[[Category:OpenBOR Index]]<br />
[[Category:Player]]<br />
[[Category:Script Events]]</div>Dcurrent