View source for 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. 

<code>models.txt</code> is the project-wide model registry. Its default location is:<pre>
data/models.txt
</pre>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.

<code>models.txt</code> does not contain the individual model definitions. Commands such as <code>load</code> and <code>know</code> 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 <code>#</code> begins a comment.<syntaxhighlight lang="text">
# This is a comment.
load player data/chars/player/player.txt
</syntaxhighlight>'''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 ===
 load {name} {path}
Registers a model and loads it during startup.

* <code>{name}</code> is the model's registry name.
* <code>{path}</code> 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 <code>load</code>.

Example:<pre>
load Player data/chars/player/player.txt
</pre>

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

# data/chars/player/player.txt
name Player
</pre>Cascading load is also supported. See [[Model Registry#Cascading Load|Cascading Load]] below.

=== Know ===
<pre>
know {name} {path}
</pre>Registers a model without loading its complete definition during startup.

Models registered with <code>know</code> 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:<pre>
know Enemy data/chars/enemy/enemy.txt
know Knife data/chars/misc/knife.txt
</pre>Models required by player selection screens or other pre-level systems should use <code>load</code>. Enemies, items, obstacles, and other models encountered during levels are generally suitable for <code>know</code>. 

'''Note:''' By default, OpenBOR does not discard a model after loading it into memory. As models registered with <code>know</code> 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 <code>global_model</code>, it receives special script treatment.<pre>
load global_model data/chars/global_model.txt
</pre>The following scripts from <code>global_model</code> 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.<pre>
load {name} {unload}
</pre>

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

For example:<syntaxhighlight lang="text">
# models.txt

know projectile data/chars/projectile.txt
know hit_flash  data/chars/hit_flash.txt
load player     data/chars/player.txt
</syntaxhighlight><syntaxhighlight lang="text">
# player.txt

name player
load projectile 1
</syntaxhighlight>Loading `player` produces the following cascade:<pre>
player
  └─ projectile
       └─ hit_flash
</pre>Each target model must first be registered by a <code>know</code> or <code>load</code> 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 <code>load</code> command is encountered.

OpenBOR scans the complete <code>models.txt</code> 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 <code>load</code> 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 <code>models.txt</code>.

During startup, OpenBOR scans <code>data/models.txt</code> 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.
{| class="wikitable"
!Command
!Default
!Purpose
|-
|<code>maxattacks {int}</code>
|<code>4</code>
|Sets the highest numbered normal attack animation, such as <code>attack4</code> or <code>attack6</code>.
|-
|<code>maxattacktypes {int}</code>
|<code>10</code>
|Sets the highest creator-numbered attack type and its corresponding reaction animation families. See [[Maxattacktypes]].
|-
|<code>maxfollows {int}</code>
|<code>4</code>
|Sets the highest numbered <code>follow</code> animation. See [[Maxfollows]].
|-
|<code>maxfreespecials {int}</code>
|<code>8</code>
|Sets the highest numbered <code>freespecial</code> animation. See [[Maxfreespecials]].
|-
|<code>maxidles {int}</code>
|<code>1</code>
|Sets the highest numbered <code>idle</code> animation. See [[Idle]].
|-
|<code>maxwalks {int}</code>
|<code>1</code>
|Sets the highest numbered <code>walk</code> animation. See [[Basic Movemet|Basic Movement]].
|-
|<code>maxbackwalks {int}</code>
|<code>1</code>
|Sets the highest numbered <code>backwalk</code> animation. See [[Basic Movemet|Basic Movement]].
|-
|<code>maxups {int}</code>
|<code>1</code>
|Sets the highest numbered <code>up</code> animation. See [[Basic Movemet|Basic Movement]].
|-
|<code>maxdowns {int}</code>
|<code>1</code>
|Sets the highest numbered <code>down</code> animation. See [[Basic Movemet|Basic Movement]].
|}
Values below the built-in minimum are raised to that minimum.

<code>maxattacks</code> and <code>maxattacktypes</code> control different systems:

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

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

* <code>pain</code>
* <code>backpain</code>
* <code>fall</code>
* <code>backfall</code>
* <code>rise</code>
* <code>backrise</code>
* <code>riseattack</code>
* <code>backriseattack</code>
* <code>blockpain</code>
* <code>backblockpain</code>
* <code>death</code>
* <code>backdeath</code>

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

Example:<pre>
# 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
</pre>

== Global Configuration ==
<code>models.txt</code> 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 [https://www.chronocrash.com/forum www.chronocrash.com] for questions.

=== Controls and Player Selection ===
{| class="wikitable"
!Command
!Default
!Purpose
|-
|<code>ajspecial {value}</code>
|<code>Special</code>
|Selects the input used for the native breakaway special and related blocking behavior. See [[Ajspecial]] for details.
|-
|<code>autoland {int}</code>
|<code>0</code>
|Controls player landing behavior after being thrown by the native legacy throw animation. 

* <code>0</code> - Players can land safely by pressing Up + Jump before impact.
* <code>1</code> - Enables automatic landing where possible. 
* <code>2</code> - Disables the normal commanded landing.
|-
|<code>colourselect {int}</code>
|<code>0</code>
|Enables palette selection on the player selection screen.

* <code>0</code> - No color selection.
* <code>1</code> - Players may cycle available color palettes by pressing Up or Down.
|-
|<code>noaircancel {int}</code>
|<code>0</code>
|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|cancel sequences]].
|-
|<code>spdirection {p1} {p2} {p3} {p4}</code>
|<code>Right Left Right Left</code>
|Sets the initial facing direction of each player preview on the selection screen.

* <code>left</code>
* <code>right</code>
|}

=== Combat and Player Rules ===
{| class="wikitable"
!Command
!Default
!Purpose
|-
|<code>blockratio {int}</code>
|<code>0</code>
|Controls the global compatibility block ratio. [[Defense.block.ratio|Defense.block ratio]] overrides this setting.

* <code>0</code> - Default block negates damage. 
* <code>1</code> - Blocking reduces damage to 25%.
|-
|<code>mpblock {int}</code>
|<code>0</code>
|Selects whether blocking damage consumes MP before HP. [[Defense.block.type]] overrides this setting.

* <code>0</code> - Blocking affects only HP.
* <code>1</code> - Blocking consumes MP, then HP if MP is insufficient.
|-
|<code>nochipdeath {int}</code>
|<code>0</code>
|Prevents blocking damage from reducing an entity below one HP.

* <code>0</code> - Chip damage can KO entities.
* <code>1</code> - Chip damage can reduce HP to 1, but not below.
|-
|<code>nocost {int}</code>
|<code>0</code>
|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.

* <code>0</code> - Special consumes energy on each use.
* <code>1</code> - Special only consumes energy if it makes contact with a opponent.
|-
|<code>nolost {int}</code>
|<code>0</code>
|Suppresses the global weapon-loss behavior associated with native grabbing.

* <code>0</code> - Current weapon dropped when grabbing.
* <code>1</code>- Current weapon retained when grabbing.
|-
|<code>nomaxrushreset {int}</code>
|<code>0</code>
|Controls preservation of the player's maximum rush value through death and respawning.

* <code>0</code> - Rush counter maximum resets on death.
* <code>1</code> - Rush counter maximum retained on death.
|-
|<code>nodropen</code>
|<code>0</code>
|Prevents the engine from dropping active enemies when a player joins or respawns.

* <code>0</code> - Enemies knocked down on player entry,
* <code>1</code> - Enemies not knocked down.
|-
|<code>nodropspawn</code>
|<code>0</code>
|Disables the default aerial drop-in placement used for applicable spawned entities when no Y position is set.

* <code>0</code> - Enemies spawn at a random 0 - 40 pixels above top of screen.
* <code>1</code> - Enemies begin at base height.
|-
|<code>versusdamage {int}</code>
|<code>0</code>
|Controls damage between players. 

* <code>0</code>  - Verses damage off
* <code>1</code> - Verses damage on. 
* <code>2</code> - Verses damage appears as option in menu.
|}

=== Timing, Scoring, and Model Defaults ===
{| class="wikitable"
!Command
!Default
!Purpose
|-
|<code>combodelay {int}</code>
|<code>0</code>
|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.
|-
|<code>global_config_game_speed {int}</code>
|<code>200</code>
|Sets the global logical timing rate. See [[Time]].
|-
|<code>lifescore {int}</code>
|<code>50000</code>
|Sets the score interval for earning an extra life.
|-
|<code>dropv {y} {x} {z}</code>
|<code>3.0 1.2 0.0</code> 
|Sets the default knockdown velocity used by attacks and related native damage effects. Notice that the Y argument appears before X.
|-
|<code>grabdistance {float}</code>
|<code>36.0</code>
|Sets the default grab distance copied into newly loaded models.
|-
|<code>jumpheight {float}</code>
|<code>4.0</code>
|Sets the default jump and running-jump height copied into newly loaded models.
|-
|<code>jumpspeed {float}</code>
|<code>1.0</code>
|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 ===
{| class="wikitable"
!Command
!Default
!Purpose
|-
|<code>global_config_cheats {flags}</code>
|<code>None</code>
|Replaces the project cheat-option bitfield with the supplied named flags. See [[Cheats]].
|-
|<code>nodebug {int}</code>
|<code>0</code>
|Hides the debug-settings entry from the system options menu.
<code>0</code> - Debug menu enabled.
<code>1</code> - Debug menu disabled.
|-
|<code>music {path} {offset}</code>
|<code>none 0</code>
|Music track to play on start up until title screen appears. See [[Music]].

* <code>path</code> - Is a string path relative to root folder. 
* <code>offset</code> - Is the sample track loops back to.
|-
|<code>global_config_flash_layer_adjust {int}</code>
|<code>1</code>
|Adds a global layer adjustment when positioning hit flashes. See [[Hit Effects]].
|-
|<code>global_config_flash_layer_source {int}</code>
|<code>255</code>
|Sets the global source-layer contribution used by hit-flash placement. See [[Hit Effects]].
|-
|<code>global_config_flash_z_source {int}</code>
|<code>0</code>
|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 <code>nocheats</code> and <code>global_config_cheats</code>. 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:

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

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

== Example ==
<pre>
# 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
</pre>

== Troubleshooting ==

=== Invalid Animation Name ===
Verify that the matching capacity is high enough.

For example, <code>anim attack6</code> requires:<pre>
maxattacks 6
</pre>A reaction such as <code>anim pain12</code> requires:<pre>
maxattacktypes 12
</pre>

=== Model Cannot Be Found ===
Check the following:

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

=== Model Is Needed Before a Level ===
Replace <code>know</code> with <code>load</code> 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 <code>0</code> through <code>63</code>. Collision capacity is fixed per animation frame and is unrelated to the animation-capacity settings in <code>models.txt</code>.

== See Also ==

* [[Animation]]
* [[Controls]]
* [[Entity]]
* [[Model]]
* [[Time]]
[[Category:Openbor]]
[[Category:Models]]