Model Registry - Revision history

Dcurrent: /* Combat and Player Rules */

2026-08-04T01:02:32Z

Combat and Player Rules

← Older revision		Revision as of 21:02, 3 August 2026
Line 235:		Line 235:
	\|<code>blockratio {int}</code>		\|<code>blockratio {int}</code>
	\|<code>0</code>		\|<code>0</code>
	\|Controls the global compatibility block ratio. [[Defense.block.ratio\|Defense.block ratio]] overrides this setting.		\|Controls the global compatibility block ratio. [[Defense.block.ratio\|Defense.block ratio]] overrides this setting. See [[Blocking#Block Ratio\|Block Ratio]] for details.

	* <code>0</code> - Default block negates damage.		* <code>0</code> - Default block negates damage.
Line 242:		Line 242:
	\|<code>mpblock {int}</code>		\|<code>mpblock {int}</code>
	\|<code>0</code>		\|<code>0</code>
	\|Selects whether blocking damage consumes MP before HP. [[Defense.block.type]] overrides this setting.		\|Selects whether blocking damage consumes MP before HP. [[Defense.block.type]] overrides this setting. See [[Blocking#MP Block\|MP Block]] for details.

	* <code>0</code> - Blocking affects only HP.		* <code>0</code> - Blocking affects only HP.
Line 249:		Line 249:
	\|<code>nochipdeath {int}</code>		\|<code>nochipdeath {int}</code>
	\|<code>0</code>		\|<code>0</code>
	\|Prevents blocking damage from reducing an entity below one HP.		\|Prevents blocking damage from reducing an entity below one HP. See [[Blocking#No Chip Death\|No Chip Death]] for details.

	* <code>0</code> - Chip damage can KO entities.		* <code>0</code> - Chip damage can KO entities.

Dcurrent: /* Timing, Scoring, and Model Defaults */

2026-08-03T04:10:33Z

Timing, Scoring, and Model Defaults

← Older revision		Revision as of 00:10, 3 August 2026
Line 318:		Line 318:
	\|<code>dropv {y} {x} {z}</code>		\|<code>dropv {y} {x} {z}</code>
	\|<code>3.0 1.2 0.0</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.		\|Sets the default [[Collision#Dropv\|knockdown velocity]] used by attacks and related native damage effects. Notice that the Y argument appears before X.
	\|-		\|-
	\|<code>grabdistance {float}</code>		\|<code>grabdistance {float}</code>

Dcurrent: /* Cascading Load */

2026-07-27T05:50:58Z

Cascading Load

← Older revision		Revision as of 01:50, 27 July 2026
Line 67:		Line 67:

	=== Cascading Load ===		=== 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>		Cascading load allows a model to load its dependencies from within its own definition. Loaded models may load other models, which may in turn load further models.<pre>
	load {name} {unload}		load {name} {unload}
	</pre>		</pre>

Dcurrent: /* Know */

2026-07-26T18:45:49Z

Know

← Older revision		Revision as of 14:45, 26 July 2026
Line 54:		Line 54:
	</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>.		</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.		'''Note:''' By default, OpenBOR follows a cache-warming pattern: once loaded, a model remains in memory until shutdown. Consequently, loading models registered with <code>know</code> during play increases the game’s total memory footprint. This is sometimes erroneously 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 ===		=== Global Model ===

Dcurrent: /* Model Registry */

2026-07-26T18:36:37Z

Model Registry

← Older revision		Revision as of 14:36, 26 July 2026
Line 18:		Line 18:
	</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>.		</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~~ ==		== Register Models ==
	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.		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.

Dcurrent at 18:33, 26 July 2026

2026-07-26T18:33:32Z

← Older revision		Revision as of 14:33, 26 July 2026
Line 1:		Line 1:
	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.		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.

	<code>models.txt</code> is the project-wide model registry. Its default location is:<pre>		<code>models.txt</code> is the project-wide model registry. Its default location is:<pre>

Dcurrent at 18:32, 26 July 2026

2026-07-26T18:32:31Z

← Older revision		Revision as of 14:32, 26 July 2026
Line 11:		Line 11:
	<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.		<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.

			=== Syntax ===

	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">		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">

Dcurrent: /* Load */

2026-07-26T18:30:00Z

Load

← Older revision		Revision as of 14:30, 26 July 2026
Line 33:		Line 33:
	load Player data/chars/player/player.txt		load Player data/chars/player/player.txt
	</pre>		</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>		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>

Dcurrent at 18:29, 26 July 2026

2026-07-26T18:29:41Z

← Older revision		Revision as of 14:29, 26 July 2026
Line 11:		Line 11:
	<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.		<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.<~~pre~~>

			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.		# This is a comment.
	load player data/chars/player/player.txt		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>.
	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 ==		== Model Registry ==
Line 21:		Line 22:

	=== Load ===		=== Load ===
	~~<pre>~~		load {name} {path}
	load {name} {path}		Registers a model and loads it during startup.
	~~</pre>~~Registers a model and loads it during startup.

	* <code>{name}</code> is the model's registry name.		* <code>{name}</code> is the model's registry name.
Line 34:		Line 34:
	</pre>		</pre>

	~~== Registration ==~~
	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>		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		# models.txt
Line 41:		Line 41:
	# data/chars/player/player.txt		# data/chars/player/player.txt
	name Player		name Player
	</pre>		</pre>Cascading load is also supported. See [[Model Registry#Cascading Load\|Cascading Load]] below.

	=== Know ===		=== Know ===
Line 54:		Line 54:
	know Knife data/chars/misc/knife.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>.		</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 ===		=== Global Model ===
	A loaded model ~~whose~~ internal name is <code>global_model</code> receives special script treatment.<pre>		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		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:		</pre>The following scripts from <code>global_model</code> execute before the corresponding script belonging to an individual entity:

	* ~~<code>didhit</code>~~		* [[didhitscript]]
	* ~~<code>onspawn</code>~~		* [[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.		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~~ <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~~.		=== 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 ==		== Animation Capacity ==

Dcurrent at 18:11, 26 July 2026

2026-07-26T18:11:05Z

← Older revision		Revision as of 14:11, 26 July 2026
Line 32:		Line 32:
	Example:<pre>		Example:<pre>
	load Player data/chars/player/player.txt		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>		</pre>

			== Registration ==
			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		# models.txt
	load Player data/chars/player/player.txt		load Player data/chars/player/player.txt