Weapons post thumbnail image

OpenBOR includes a native weapon system, allowing in game characters to attain new abilities, power ups, or as the name implies, usable weapons. In actuality, each weapon is an alternate model that partially replaces traits from the default model. For example, the weapon model for a sword might replace idle, walking, and jumping animations with new ones carrying a sword, and the attack animation with a sword swing. All the other model traits like name, hit-points, and so on remain the same.

All entity types can use weapons. By default computer controlled entities will seek out and collect available weapon pickups.

Initial Setup

To begin, you will need to create a new model for the weapon (see Weapon Model). It is similar in principal to a normal model, but you do not need to include any properties or animations which are the same as the original model. When the weapon is in use, the original model is “upgraded” with the new model. Properties (animations, icons, etc.) that differ from the original model are replaced. Any new properties are added. Properties not found in the weapon model text are unchanged unless noted otherwise.

The original model’s com list is not copied. This is so you can redefine available commands in the weapon model (i.e. no hurricane kick if you’re carrying a two ton rock over your head). Cancel commands do copy since they are part of an animation. If you want to disable cancels, just include the animation in your weapon model without the cancels in it.

Make sure the weapon model is loaded before you try to use it. This works like loading any other model. Once you have a weapon model, you need to add it to the original model’s weapons list. After this step, your model is ready to use the weapon. Weapons can be equipped in a variety of ways, including collectable items, commands, or script.

If the weapon is meant to be an item found in levels or taken from opponents, you will also need a Weapon Item. Weapon items are very similar to other collectable items, with some properties added to activate the weapon model.

By default, entities lose a weapon when taking any hits. If the weapon was an item pickup, it drops in front of the entity that carried it. After three drops, the weapon is killed. You can modify any of these behaviors and much more, so be sure to study the properties below.



Unless noted otherwise, these properties are usable by both the default model and any weapon models. This allows you to dictate new weapon behaviors based on the current weapon. For example, you might want to prevent picking up other weapons while carrying a large barrel or rock to throw.

Weapon List​

weapons <weapon models>

weapons none

List of weapons a model can use. Accepts a list of model names. The first model weapon is weapon 1, the next weapon 2, and so on (weapon 0 is the default model with no weapon). When an entity is instructed to set its weapon it switches to the weapon model by its position in the list. For example, if the second model in the weapon list is baseball_bat, picking up an item with weapnum 2 (see below) will switch to the baseball_bat model.

You may use none for a model name to disable that weapon number. For example if the weapons list is weapons none baseball_bat knife, the entity will ignore any attempt to set its weapon to 1.

Weapon Loss Condition​

weapon_loss_condition <flags>

weapon_loss_condition pain fall grab

Set in game conditions that cause loss of carried weapon. Accepts one or more of the following flags. If used, you must provide all the flags you want to enable.

  • none – No effect if any other flag is used. Use this by itself if you want to override the model’s default configuration with all flags false.
  • damage – Any native damage.
  • death – Dies from damage.
  • default – Shortcut that adds default flags (damage, death, fall, grabbed, grabbing, land_damage, and pain).
  • fall – Knocked down.
  • grabbed – Grabbed by another entity.
  • grabbing – Grabs another entity.
  • land_damage – Takes damage from a throw or blast on landing.
  • pain – Put in hitstun.
  • stage – Stage transition.

Accessible to script as model property using following bitmask constants.

  • openborconstant("WEAPON_LOSS_CONDITION_NONE")
  • openborconstant("WEAPON_LOSS_CONDITION_DAMAGE")
  • openborconstant("WEAPON_LOSS_CONDITION_DEATH")
  • openborconstant("WEAPON_LOSS_CONDITION_FALL")
  • openborconstant("WEAPON_LOSS_CONDITION_GRABBED")
  • openborconstant("WEAPON_LOSS_CONDITION_PAIN")
  • openborconstant("WEAPON_LOSS_CONDITION_STAGE")
  • openborconstant("WEAPON_LOSS_CONDITION_DEFAULT")

Weapon Loss Index​

weapon_loss_index <int>

weapon_loss_index 0

Accepts an integer value corresponding to the desired weapon list index. Entity reverts to the specified entry in its weapon list when losing current weapon. If this property is not used, the entity reverts to weapon 0 (default model).

Example: When this entity meets conditions for losing a weapon, it will instead revert to weapon 2 (ax_red_dragon).

weapons  ax_chicken ax_red_dragon ax_blue_dragon

weapon_loss_index 2

Model Copy​

modelflag <flags>

modelflag none

Configure copy behavior when switching to a new model (i.e picking up a weapon). Accepts one or more of the following.

  • none (default) – No flags. Standard copy that includes most items from original model.
  • no_basic – Don’t copy animations, icons, diesound, dust, speed, model header projectile properties, or running properties.
  • no_weapon – Don’t copy weapon list.
  • no_script – Don’t copy scripts.

Accessible to script as a model property using following bitmask constants:

  • openborconstant("MODEL_COPY_FLAG_NONE")
  • openborconstant("MODEL_COPY_FLAG_NO_BASIC")
  • openborconstant("MODEL_COPY_FLAG_NO_WEAPON")
  • openborconstant("MODEL_COPY_FLAG_NO_SCRIPT")
int model_flag_value = get_model_property(model_property, "model_flag");

if(model_flag_value & openborconstant("MODEL_COPY_FLAG_NO_WEAPON"))
     /* Do something here if no weapon copy is active. */

* Now turn the no weapon copy bit off 
* and apply it to model_flag.
model_flag_value &= ~openborconstant("MODEL_COPY_FLAG_NO_WEAPON");

set_model_property(model_property, "model_flag", model_flag_value);

Weapon Frame​

weaponframe <frame> <index>

Not defined.

Animation header command. When the animation reaches frame, the entity will switch to index in its weapons list.

Level Design

The following are used by level text files to set up weapons mid game as entities spawn.

Set Weapon​

setweap <index>

setweap 0

Level header command. Player entities start the level using index weapon in their weapons list.

Weapon On Spawn​

weapon <item name>

Not defined.

Level spawn command. Item model is model name of a weapon item. The entity will spawn into play having already “picked up” the weapon item, and using it if possible.

Weapon Item

Weapon items are collectable items that when picked up instruct the entity to switch to a weapon model. Picked up items drop at the entity’s location if their weapon is lost. After a set number of drops (see counter), the weapon item is killed.

Computer controlled entities will find and pick up usable weapon items. The computer ignores items if the entity can’t use them.

To set up a weapon item, create an Item model, and give it the weapon subtype. Then configure the following properties.


Weapon pickup items need one of the following subtypes.

  • weapon – Normal weapon behavior. Use this for most weapons and power ups.
  • project – Instead of swapping models, this populates the model projectile property. See project.

Weapon Index​

weapnum <index>

weapnum 0

Accepts an integer value corresponding to a weapon list index. Entities that pick up the item switch to the weapon model in the specified index position of their weapons list. If an entity does not have a weapons list entry in index position, does not have a weapons list at all, or if the model name in index position is none, the entity cannot collect the item.

Drop Limit​

counter <int>

counter 3

Accepts an integer value to set the number of losses before weapon item is removed from play.


animal <int>

animal 0

If true, activates following default behaviors to approximate riding a creature:

  • Any incoming attacks knock the entity down and cause weapon loss.
  • Permanent weapon loss causes the dropped item to run away (i.e. fly out of screen view).
  • Entity is immune to grabs.

Projectile Model​

project <model name>

project none

For use with project subtype. Model is the model name of projectile. When this item is picked up, model is copied to the collecting entity’s model project property. You may then use throwframe to spawn the model as a projectile entity.


reload <int>

reload 0

If the collecting entity has a limited use weapon (see shootnum), this item adds int to remaining uses. Otherwise does nothing.

Weapon Model

Weapon models are the alternate models an entity may assume when using a weapon. They are similar to a normal model text, but usually less extensive as you only need to include changed properties. Weapon models should be type none. The following properties are unique to weapon models.

Weapon models can technically be any type, but to avoid conflicts you should always use type none.

Use Limit​

shootnum <int>

shootnum 0

If int (default 0) is any positive number, this becomes a limited use weapon. Once int uses are depleted, the entity reverts back to its default model.

Use Limit Display​


typeshot 0

Used in conjunction with shootnum to control behavior of limited use weapons. This property has no effect if shootnum is not in use. If enabled (1), Remaining weapon uses appear as a counter in the HUD.


The following is an explanation of how the engine handles weapons internally. This could be useful for advanced creators wishing to take greater advantage of the weapon system.

When an entity picks up a weapon item, the following events occur:

  1. The receiving entity switches to its weapons list entry model matching the weapnum index on weapon item.
  2. The receiving entity has a property that is populated with the weapon item entity’s pointer.
  3. The weapon item entity moves to a hidden location in the level (a hardcoded Z position where the camera can’t show it).

When an entity drops a weapon, the following happens:

  1. The dropping entity returns to its default model.
  2. The weapon item property on dropping entity is used to reference the weapon item entity. and perform following actions:
    • The weapon item entity moves to dropping entity’s current position.
    • The weapon item entity plays SPAWN or RESPAWN animations if it has them (RESPAWN has priority).
    • If the dropping entity’s weapon counter is 0, the weapon item entity goes into engine’s default (blink & disappear) death routine.
  3. The weapon item property on dropping entity clears to NULL.

1 thought on “Weapons”

Comments are closed.

Related Post


Under Construction Filestreams allow CRUD (Create, Read, Update, Delete) operations on user defined files during gameplay. You can sue these to build databases and add persistence features to games.