Model Registry

The model registry is arguably the single most important aspect of an OpenBOR project, and is a required element. It should not be confused with individual models, which are singular, reusable templates used to create players, enemies, items, obstacles, projectiles, and other entities.

models.txt is the project-wide model registry. Its default location is:

data/models.txt

The file serves three primary purposes:

• Registers model names and their definition files.
• Selects which models are loaded during startup and which remain available for later loading.
• Configures project-wide animation capacities and gameplay defaults.

models.txt does not contain the individual model definitions. Commands such as load and know point OpenBOR to the files containing those definitions.

Syntax

Each nonempty line begins with a command followed by its arguments. Whitespace separates arguments, quoted strings may contain spaces, and # begins a comment.

# This is a comment.
load player data/chars/player/player.txt

Note: The models setting in video.txt can select an alternate model registry. In the current engine implementation, animation-capacity settings are still read from data/models.txt.

Model Registry

OpenBOR must register a model before native engine logic can load or spawn it. The load and know commands both add a model to the registry, but differ in when the complete model is loaded.

Load

load {name} {path}

Registers a model and loads it during startup.

• {name} is the model's registry name.
• {path} is the path to its definition file.
• The model and its required resources are loaded before normal gameplay begins.
• Models needed outside active levels, such as selectable players, should ordinarily use load.

Example:

load Player data/chars/player/player.txt

OpenBOR registers every model in the file before processing the complete definitions of models marked with load. This deferred loading allows a model to reference another registered model even when the referenced entry appears later in models.txt. OpenBOR also checks the model definition file for its internal name property. When present, the internal name replaces the registry name supplied by models.txt. Matching both names avoids ambiguous references.

# models.txt
load Player data/chars/player/player.txt

# data/chars/player/player.txt
name Player

Cascading load is also supported. See Cascading Load below.

Know

know {name} {path}

Registers a model without loading its complete definition during startup.

Models registered with know are available to the automatic loader when requested by a level, another model, or native loading command. This reduces initial loading time and avoids keeping every project resource in memory from the beginning.

Example:

know Enemy data/chars/enemy/enemy.txt
know Knife data/chars/misc/knife.txt

Models required by player selection screens or other pre-level systems should use load. Enemies, items, obstacles, and other models encountered during levels are generally suitable for know.

Note: By default, OpenBOR does not discard a model after loading it into memory. As models registered with know are loaded during play, the game's total memory footprint therefore increases. This is sometimes enormously attributed to a memory leak, but it is intended behavior because most game designs reuse models after introducing them. Models may be configured to unload when conserving memory is necessary.

Global Model

When a loaded model's internal name is global_model, it receives special script treatment.

load global_model data/chars/global_model.txt

The following scripts from global_model execute before the corresponding script belonging to an individual entity:

• didhitscript
• onspawnscript

This provides a central location for project-wide reactions to entity spawning and successful attacks. The model must be loaded for these global scripts to be available.

Cascading Load

Cascading load allows a model to load its dependencies from within its own definition. A loaded model may load another model, which may in turn load further models.

load {name} {unload}

• {name} - Registered name of the model to load.
• {unload} - Optional unloading behavior applied to the loaded model.

For example:

# models.txt

know projectile data/chars/projectile.txt
know hit_flash  data/chars/hit_flash.txt
load player     data/chars/player.txt

# player.txt

name player
load projectile 1

Loading `player` produces the following cascade:

player
  └─ projectile
       └─ hit_flash

Each target model must first be registered by a know or load entry in models.txt. Registration supplies the model name and file path required by the cache. The model does not need to be loaded into memory before the cascading load command is encountered.

OpenBOR scans the complete models.txt and registers every know and load entry before loading any models. Registration order therefore does not matter.

If the requested model is already loaded, OpenBOR reuses the existing model and updates its unload setting rather than loading a duplicate.

Note: The load command in an individual model accepts a registered model name, not a file path. It cannot register an unknown model. Attempting to load a model without a cache entry causes a fatal error. OpenBOR reads the target file's internal name property while creating its cache entry. Cascading references should use that declared model name.

Animation Capacity

OpenBOR assigns numeric identifiers to animations. Several animation families have expandable capacities configured through models.txt.

During startup, OpenBOR scans data/models.txt for these settings before allocating animation identifier tables and loading model definitions. Their position within the file therefore does not affect allocation, though placing them near the beginning improves readability.

Command	Default	Purpose
maxattacks {int}	4	Sets the highest numbered normal attack animation, such as attack4 or attack6.
maxattacktypes {int}	10	Sets the highest creator-numbered attack type and its corresponding reaction animation families. See Maxattacktypes.
maxfollows {int}	4	Sets the highest numbered follow animation. See Maxfollows.
maxfreespecials {int}	8	Sets the highest numbered freespecial animation. See Maxfreespecials.
maxidles {int}	1	Sets the highest numbered idle animation. See Idle.
maxwalks {int}	1	Sets the highest numbered walk animation. See Basic Movement.
maxbackwalks {int}	1	Sets the highest numbered backwalk animation. See Basic Movement.
maxups {int}	1	Sets the highest numbered up animation. See Basic Movement.
maxdowns {int}	1	Sets the highest numbered down animation. See Basic Movement.

Values below the built-in minimum are raised to that minimum.

maxattacks and maxattacktypes control different systems:

• maxattacks expands the numbered attack animations an entity may perform - mainly used for native combo series.
• maxattacktypes expands numbered damage types and their associated reaction animations.

Each additional attack type creates identifiers for twelve related reaction families:

• pain
• backpain
• fall
• backfall
• rise
• backrise
• riseattack
• backriseattack
• blockpain
• backblockpain
• death
• backdeath

Animation capacities are global. Increasing them enlarges the animation table allocated for every loaded model. Configure only the capacities the project requires.

Example:

# Enable attack1 through attack6.
maxattacks 6

# Enable numbered attack types through attack12.
maxattacktypes 12

# Enable freespecial1 through freespecial10.
maxfreespecials 10

# Enable follow1 through follow6.
maxfollows 6

Global Configuration

models.txt also accepts project-wide settings affecting controls, combat, timing, model defaults, menus, and presentation. Many of these settings provide legacy boilerplate for traditional beat 'em up games. Advanced creators may prefer to leave them unused or override them with object-specific settings and scripts when designing more nuanced combat systems or other game genres.

Some legacy commands have been left intentionally undocumented as their functionality has been replaced by newer options. If an item does not appear here, do not use it. See www.chronocrash.com for questions.

Controls and Player Selection

Command	Default	Purpose
ajspecial {value}	Special	Selects the input used for the native breakaway special and related blocking behavior. See Ajspecial for details.
autoland {int}	0	Controls player landing behavior after being thrown by the native legacy throw animation. 0 - Players can land safely by pressing Up + Jump before impact. 1 - Enables automatic landing where possible. 2 - Disables the normal commanded landing.
colourselect {int}	0	Enables palette selection on the player selection screen. 0 - No color selection. 1 - Players may cycle available color palettes by pressing Up or Down.
noaircancel {int}	0	Controls native cancellation between jumping attacks and aerial specials. 0 - Players may cancel jump attack sito each other as log as the next attack is a different animation from the previous (ex. Up + Attack, Dow + Attack). 1 - Players may not cancel jump attacks. Note, this only applies to native jump attacks and has no effect on cancel sequences.
spdirection {p1} {p2} {p3} {p4}	Right Left Right Left	Sets the initial facing direction of each player preview on the selection screen. left right

Combat and Player Rules

Command	Default	Purpose
blockratio {int}	0	Controls the global compatibility block ratio. Defense.block ratio overrides this setting. 0 - Default block negates damage. 1 - Blocking reduces damage to 25%.
mpblock {int}	0	Selects whether blocking damage consumes MP before HP. Defense.block.type overrides this setting. 0 - Blocking affects only HP. 1 - Blocking consumes MP, then HP if MP is insufficient.
nochipdeath {int}	0	Prevents blocking damage from reducing an entity below one HP. 0 - Chip damage can KO entities. 1 - Chip damage can reduce HP to 1, but not below.
nocost {int}	0	Enables the legacy behavior that delays a special's resource cost until the attack connects. Special refers to the native "breakaway" special mapped to special key or Attack + Jump. 0 - Special consumes energy on each use. 1 - Special only consumes energy if it makes contact with a opponent.
nolost {int}	0	Suppresses the global weapon-loss behavior associated with native grabbing. 0 - Current weapon dropped when grabbing. 1- Current weapon retained when grabbing.
nomaxrushreset {int}	0	Controls preservation of the player's maximum rush value through death and respawning. 0 - Rush counter maximum resets on death. 1 - Rush counter maximum retained on death.
nodropen	0	Prevents the engine from dropping active enemies when a player joins or respawns. 0 - Enemies knocked down on player entry, 1 - Enemies not knocked down.
nodropspawn	0	Disables the default aerial drop-in placement used for applicable spawned entities when no Y position is set. 0 - Enemies spawn at a random 0 - 40 pixels above top of screen. 1 - Enemies begin at base height.
versusdamage {int}	0	Controls damage between players. 0 - Verses damage off 1 - Verses damage on. 2 - Verses damage appears as option in menu.

Timing, Scoring, and Model Defaults

Command	Default	Purpose
combodelay {int}	0	Sets the number of logical ticks before the current combo expires. Only applies to the native series (mash attack) combo. By adding delay, you can prevent the common trick of players stunlocking enemies with repeat non-knockdown combo strings.
global_config_game_speed {int}	200	Sets the global logical timing rate. See Time.
lifescore {int}	50000	Sets the score interval for earning an extra life.
dropv {y} {x} {z}	3.0 1.2 0.0	Sets the default knockdown velocity used by attacks and related native damage effects. Notice that the Y argument appears before X.
grabdistance {float}	36.0	Sets the default grab distance copied into newly loaded models.
jumpheight {float}	4.0	Sets the default jump and running-jump height copied into newly loaded models.
jumpspeed {float}	1.0	Sets the default jump speed copied into newly loaded models.

Model definition properties may override the applicable defaults for individual models.

Menus, Cheats, Audio, and Hit Flashes

Command	Default	Purpose
global_config_cheats {flags}	None	Replaces the project cheat-option bitfield with the supplied named flags. See Cheats.
nodebug {int}	0	Hides the debug-settings entry from the system options menu. 0 - Debug menu enabled. 1 - Debug menu disabled.
music {path} {offset}	none 0	Music track to play on start up until title screen appears. See Music. path - Is a string path relative to root folder. offset - Is the sample track loops back to.
global_config_flash_layer_adjust {int}	1	Adds a global layer adjustment when positioning hit flashes. See Hit Effects.
global_config_flash_layer_source {int}	255	Sets the global source-layer contribution used by hit-flash placement. See Hit Effects.
global_config_flash_z_source {int}	0	Sets the global Z-source contribution used by hit-flash placement. See Hit Effects.

Settings are processed in file order. Order therefore matters when multiple commands modify the same global configuration, such as nocheats and global_config_cheats. In the case of a conflict, the last command in order takes priority,

Loading Process

During normal startup, OpenBOR performs the relevant operations in the following order:

1. Scans data/models.txt for animation-capacity settings.
2. Allocates global animation identifiers and per-model animation-table capacity.
3. Reads the active model registry and applies global settings in file order.
4. Registers every load and know entry.
5. Loads the complete definitions of models marked with load.

Registering the entire list before loading complete models allows nested references to resolve even when their entries appear later in the file.

Example

# Animation capacities.
maxattacks       6
maxattacktypes   12
maxfreespecials  10
maxfollows       6

# Project defaults.
colourselect 1
lifescore   50000
combodelay  100

# Models required before gameplay.
load global_model data/chars/global_model.txt
load Player       data/chars/player/player.txt

# Models available to the automatic loader.
know Enemy  data/chars/enemy/enemy.txt
know Knife  data/chars/misc/knife.txt
know Barrel data/chars/misc/barrel.txt

Troubleshooting

Invalid Animation Name

Verify that the matching capacity is high enough.

For example, anim attack6 requires:

maxattacks 6

A reaction such as anim pain12 requires:

maxattacktypes 12

Model Cannot Be Found

Check the following:

• The model has a load or know entry.
• The path points to the correct model definition file.
• The model's internal name matches the name used by other files.
• Letter case is consistent across paths and references.

Model Is Needed Before a Level

Replace know with load when the model is required by a selection screen or another system that runs before normal level loading.

Excessive Memory Use

Reduce animation-capacity settings to the highest identifiers actually used by the project. Capacity increases affect every loaded model, even models that do not use the additional animations.

Collision Index Out of Range

Use collision indexes from 0 through 63. Collision capacity is fixed per animation frame and is unrelated to the animation-capacity settings in models.txt.

See Also

• Animation
• Controls
• Entity
• Model
• Time