OpenBOR Overview

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.

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.

Engine Structure

An OpenBOR game consists of two principal components:

• Engine – The executable and supporting platform files that provide OpenBOR’s runtime systems.
• Module – The game’s configuration, models, levels, scripts, graphics, and audio.

During development, a module may be loaded directly from an unpacked data directory. For distribution, the same directory can be packaged into a .pak file.

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.

Module Layout

A typical unpacked module has the following layout:

data/
├── models.txt
├── levels.txt
├── video.txt
├── lifebar.txt
├── menu.txt
├── script.txt
├── bgs/
├── chars/
├── levels/
├── music/
├── scenes/
├── sounds/
├── sprites/
└── scripts/

The subdirectory names are organizational conventions. Creators may use any directory structure they prefer as long as referenced paths are correct.

The principal root files are:

• models.txt – Registers entity models, controls how they are loaded, and provides several model-related module settings.
• levels.txt – Defines level sets, game modes, stage order, and several general level and interface settings.
• video.txt – Optional display and video configuration.
• lifebar.txt – Optional lifebar presentation configuration.
• menu.txt – Optional menu configuration.
• script.txt – Optional scripting limits and global script behavior.

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.

Models and Entities

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.

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.

Model files may define statistics, movement, artificial intelligence, animations, attacks, defense, collision, palettes, sounds, projectiles, and event scripts.

See Models and Entities.

Animations

Animations organize an entity’s visual frames, timing, and actions. OpenBOR recognizes animation types such as IDLE, WALK, ATTACK, PAIN, FALL, and RISE and uses them to control common entity behavior.

Animation data may include:

• Sprite frames and delays.
• Entity-origin offsets.
• Attack and body collision boxes.
• Movement and velocity instructions.
• Sounds and visual effects.
• Spawned entities.
• Frame-specific commands and scripts.

Animations therefore serve as both visual sequences and configurable entity states.

See Animations.

Levels and Level Sets

A level describes a playable area. Level files arrange backgrounds, terrain, boundaries, spawn points, music, environmental objects, and other stage content.

A level set is an ordered collection of levels and scenes declared in levels.txt. Level sets may represent game modes, routes, episodes, or difficulty selections.

See Levels, Level Sets, and Scenes.

Scenes and Media Playback

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.

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.

See Scenes and WebM.

Game World

OpenBOR places entities in a three-dimensional Cartesian game field:

• X – Horizontal position.
• Y – Height.
• Z – Lateral depth toward or away from the camera.
• Base – The height on which an entity currently stands.

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.

See Geometry Overview.

Collision and Combat

Collision boxes describe the physical areas used for attacks, damage reception, terrain, and entity contact.

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.

• Collision - Defining collision boxes, including body (hurt) and attack.
• Attack Types - Native reactive system to differing attack types.
• Damage Control - Damage mitigation - defense and offense - for differing attack types.

Native Functionality

OpenBOR provides native systems for common game functionality, including:

• Player input and control mapping.
• Movement, jumping, gravity, and platforms.
• Enemy targeting and artificial intelligence.
• Attacks, blocking, grabbing, throwing, and counters.
• Damage, pain, knockdown, and death.
• Projectiles, weapons, items, and summoned entities.
• Cameras, scrolling, layers, palettes, and shadows.
• Menus, player selection, HUD elements, and saved progress.
• Music and sound effects.

Creators may use these systems directly, combine their settings into new behaviors, or modify them through script.

Time

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.

See Time.

Scripting

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.

Scripts may inspect or modify engine objects, implement custom mechanics, draw graphics, control audio, manage data, and create reusable function libraries. See the following.

• Script Overview - Detailed overview of script syntax and operators.
• Script Functions - List of native script functions.
• Variables - Variable types and implications.
• Strings - String specific functions.
• Arrays - Arracy ad linked list API.
• File Operations - File CRUD API.

Runtime Layout

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.

                       MODULE DATA
       ┌──────────────────┼──────────────────┐
       │                  │                  │
  models.txt         levels.txt        Assets and scripts
       │                  │                  │
       ▼                  ▼                  ▼
  Model files       Levels and scenes   Graphics, audio,
       │                                and custom logic
       └──────────────────┬──────────────────┘
                          ▼
                    RUNTIME WORLD
                          │
                          ▼
┌──────────────── REPEATING ENGINE CYCLE ────────────────┐
│                                                        │
│  Read player input                                     │
│    └─ Input and key script hooks                       │
│                                                        │
│  Run global and level update scripts                   │
│                                                        │
│  Update entities                                       │
│    ├─ Entity update and think script hooks             │
│    ├─ Player control and artificial intelligence       │
│    ├─ Animation and frame script hooks                 │
│    ├─ Movement, gravity, and terrain                   │
│    └─ Collision, attacks, damage, and reaction hooks   │
│                                                        │
│  Queue graphics                                        │
│    └─ Entity drawing script hooks                      │
│                                                        │
│  Run post-update scripts                               │
│                                                        │
│  Draw the completed frame and continue                 │
│                                                        │
└────────────────────────────────────────────────────────┘

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.

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.

Graphic Layout

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.

As of OpenBOR 4.x, all rendering and composition prior to the final video_copy_screen() 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.

Graphics Sources
│
├── Loaded Assets
│   ├── Animation frames and sprites
│   ├── Level backgrounds and graphic layers
│   ├── Fonts and interface graphics
│   └── Menu and scene graphics
│
├── Native Engine Rendering
│   ├── Level layers and terrain
│   ├── Entities, shadows, and effects
│   ├── HUD and status displays
│   └── Menus, text, and overlays
│
└── Script Rendering
    ├── Sprites
    ├── Text
    ├── Lines, boxes, and other primitives
    └── Subscreen surfaces (s_screen)
        ├── Allocate an off-screen surface
        ├── Draw graphics onto the surface
        ├── Combine multiple elements or surfaces
        └── Queue the completed surface with drawscreen()
                         │
                         ▼
                  Sprite/Draw Queue
                         │
                         ├── Layer and Z ordering
                         ├── Position and clipping
                         ├── Palette and remap
                         ├── Transparency and blending
                         └── Scaling, rotation, and other draw methods
                         │
                         ▼
             Main Virtual Screen (vscreen)
             ─────────────────────────────
             Queue contents are composited
             into the current video frame.
                         │
                         ├── Optional screenshot capture
                         └── Debug and final overlays
                         │
                         ▼
                  video_copy_screen()
                         │
                         ├── Output scaling
                         ├── Video filtering
                         ├── Color adjustment
                         └── Window or fullscreen presentation
                         │
                         ▼
                   Physical Display