Model Registry

The model registry is arguably the single most important aspect of an OpenBOR project, and is a required element. It is 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.

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 <code>models</code> setting in <code>video.txt</code> can select an alternate model registry. In the current engine implementation, animation-capacity settings are still read from <code>data/models.txt</code>.

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

=== Load ===
<pre>
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

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.

Global Model

A loaded model whose internal name is global_model 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:

• didhit
• onspawn

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.

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.

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