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.

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.

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.

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.

See Coordinate System and Movement.

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.

See Collision, Attack Types, and Damage Mitigation.

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.

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 Script Overview, Script Functions, Variables, Strings, and Arrays.

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                 │
│                                                        │
└────────────────────────────────────────────────────────┘

Scripts are not a separate system added after native processing. 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.