OpenBOR Manual

From Beats Of Rage

(Difference between revisions)

Revision as of 02:45, 3 August 2013

2JAimu Thanks a lot for the article post.Really looking forward to read more. Much obliged.

Thanks for sharing, this is a fantastic blog post.Really looking forward to read more. Cool.

ajiZhb Really appreciate you sharing this blog article.Much thanks again. Cool.

WSEkGs Great blog.Thanks Again. Will read on...

nNZDBP Wow, great article.Really thank you! Want more.

7rm7XH Thanks so much for the blog post.Really thank you!

czuegV I loved your article.Thanks Again. Keep writing.

JII8p4 Great post.Much thanks again. Cool.

1dQbI1 I value the blog article.Really looking forward to read more. Really Great.

Animation Data

loop {bi}

Determines whether or not an animation repeats itself when finished.

0 means the animation ends when the last frame is reached.

1 means the animation repeats itself after the last frame.

You can change it during the animation, but there's not really much of a point...

Some animations should NOT be set to loop. Examples include most attacks and injured animations.

fastattack {bi}

Normally, in order for an attack to hit entities multiple times, the attack boxes must be separated by at least one frame with an empty attack box (one set to all 0) and must also be separated by a brief delay.

If this is set to 1, this animation's attack boxes are not restricted by the delay (it will still need an empty attack box between frames, though).

hitfx {path}

{path} should point to a .wav file.

If this animation has an attack box which makes contact with a victim, this sound will play instead of the normal 'beat1.wav' sound.

Like the normal hitsfx, the higher the attack power, the slower this sound will play.

hitflash {name}

{name} is the name of an entity declared in MODELS.txt.

If this animation has an attack box which makes contact with a victim, this hitflash will play instead of the normal hitflash for this character.

custknife {name}

{name} is the name of an entity declared in MODELS.txt.

If present, for this animation only, the entity's default 'knife' entity will be replaced with this entity.

You still need to fire the entity at some point in the animation for this to do anything.

Don't forget to load the entity in MODELS.txt!

Knives can't be used by enemies during a jump.

custstar {name}

{name} is the name of an entity declared in MODELS.txt.

If present, for this animation only, the enemy's default 'star' entity will be replaced with this entity.

You still need to fire the entity at some point in the animation for this to do anything.

Don't forget to load the entity in MODELS.txt!

custbomb {name} custpbomb {name}

`Use "custbomb" for enemies and "custpbomb" for players.

{name} is the name of an entity declared in MODELS.txt.

If present, for this animation only, the entity's default 'bomb' entity will be replaced with this entity.

You still need to fire the entity at some point in the animation for this to do anything.

Don't forget to load the entity in MODELS.txt!

delay {int}

{int} is a number that tells how slowly the animation plays. 1 is extremely fast, past 25 will go very slow.

{int} is measured in centiseconds, or hundredths of a second. Pretty fast.

Can be used multiple times in one animation to change speed mid-animation

offset {x} {y}

Determines where the "base" of the animation is.

The center of the entity's "shadow" graphic is placed here if the player is on the ground. Also used by enemies to find where you are.

'offset 0 0' would be the upper left corner. Larger {x} values move the {x} down. Larger {y} values move the {y} right.

You can use negative numbers or numbers outside of the frame's edges.

Most entities will automatically die if their offset goes more than 80 pixels offscreen left or right (their x value must stay between -80 and 400). Knives are the only exception: they can go up to 180 either way (-180 to 500).

Common symptoms of incorrect offsets are misplaced shadows, sudden "warps" to different positions and back, and enemies/shadows who seem to think you're ten feet away.

Can be used multiple times in one animation to change position mid-animation

bbox {x} {y} {right} {down}

Determines where the entity can be hit.

{x} and {y} are the x and y coordinates of the top left corner of the box, starting from the top left corner of the frame and moving right/down. {right} is how far to the right of {x} the box extends. {down} is how far down from {y} the box extends.

You can use negative numbers or numbers outside of the frame's edges. This can save a bit of memory by shaving a few excess rows or columns of pixels off an animation.

Can be used multiple times in one animation to change hittable areas mid-animation.

To give an entity frames where they cannot be hit, use 'bbox 0 0 0 0'. Be sure to add a new bbox when the entity is vulnerable again.

For items, this determines where the object can be picked up from.

frame {path}

{path} points to a graphics file to be used in this animation.

The frame will be displayed at the entity's position. It's about as simple as it sounds.

OpenBoR uses 256-color (or lower) .bmp, .gif, or .pcx files. However, .gif files are far and away the smallest, so don't use .bmp or .pcx, just .gif.

Also, OpenBoR seems to have trouble with certain .bmps. They may need to be saved with Photoshop for OpenBoR to read them. .pcx are fine, but they're still larger than .gif files, so .gifs are preferred.

If you want to convert a lot of images which are already in the desired pallette into .gif files, you may want to try Irfanview (at http://www.irfanview.us/).

range {min} {max}

Used for enemy attacks and jumps. Also used by homing projectiles.

This command lets the enemy know when to perform their attacks or to jump on platforms..

For the enemy to use the attack, a player must be more than {min} away, but less than {max} away in x axis.

For the enemy to jump on a platform, the enemy must be within {min} pixels of the platform, and the platform must be less than {max} pixels high.

This is measured in pixels, starting at the enemy's offset point and moving towards the player's offset.

If not included, the first number will default to -10, and the second to 20 times the entity's jumpheight variable.

For homing projectiles, this determines their targeting range.

If this command is declared together with 'rangez' and/or 'rangea', opponent's location must be within ALL of them before attack animation is performed.

Default 'range' for ATTACK{#} is 0 75, for JUMPATTACK and JUMPATTACK2 is 0 150, for UPPER -10 120 and for BLOCK is 1 100. The last one only has effect if enemy uses 'nopassiveblock'.

rangez {min} {max}

This command works similar with 'range' (see above) except that it works in z axis instead.

Default values for {min} and {max} are '-grabdistance/3' and 'grabdistance/3' respectively.

If this command is declared together with 'range' and/or 'rangea', opponent's location must be within ALL of them before attack animation is performed.

rangea {min} {max}

This command works similar with 'range' (see above) except that it works in y axis or altitude instead.

Default values for {min} and {max} are -1000 and 1000 respectively.

If this command is declared together with 'range' and/or 'rangez', opponent's location must be within ALL of them before attack animation is performed.

attack{#} {x} {y} {right} {down} {damage} {power} {block} {noflash} {pausetime} {z}

An attack box which can hit bboxes

OpenBoR supports 10 different attack boxes by default and {#} determines which one the frame is using. There's no space between 'attack' and {#} though.

You can only have one type of attack box per frame (that is, you can't have two attack boxes or an attack and an attack4 box in the same frame). You can 'fake' an extra box or two by adding in extra frames with different boxes and changing the delay accordingly, but this takes up more memory (for the extra frames) and doesn't work perfectly, so try to do so sparingly.

{x}, {y}, {right}, and {down} work exactly like in a bbox.

{damage} determines how much damage the attack does. Setting it to 0 also works. Great for making launchers, slams and paralyze attacks.

{power} is an integer value that determines how strong the knockdown effect of this attack. 0 means no knockdown, 1 means knockdown level 1, etc. This is used in conjunction with 'knockdowncount' (see above).

{block} is a binary value which determines if an attack is unblockable.

{noflash} is a binary value which controls whether the flash is displayed. 0 means flash, 1 means no flash.

{pausetime} is an integer which will cause the attacker and attackee to be paused for {pausetime} if the attack hits something.

{z} determines attackbox' width in z axis.

If you change or repeat an attack box's declaration later in the animation, you can create combos in same animation. However, a certain amount of time must pass before targets can be hit again (This can be avoided with 'fastattack'). Also, you must have at least one frame with a blank attack box (One set to 'attack 0') between the two frames or sets of frames which combo.

You can use negative numbers or numbers outside of the frame's edges.

Can be used multiple times in one animation to change hit areas mid-animation

When the attacking part of the animation is over, use 'attack 0'. Otherwise, the attack box will remain and can continue hitting people for the rest of the animation!

Each 'attack{#}' has respective PAIN, FALL and DEATH animation. For instance, if attacker hits opponent with attack2, the latter will play PAIN2 (if attack2 doesn't knock him/her down) or FALL2 (if attack2 knocks him/her down) or DEATH2 (if attack2 kills him/her).

attack11,attack12,...

These attacks are only usable if you have increased attacktype limit. To increase the limit use 'maxattacktypes' (see details above in Models.txt section).

After they are available, they work just like other attacks. That also means respective PAIN,FALL and DEATH animations are also available.

blast {x} {y} {right} {down} {damage} {block} {noflash} {pausetime} {z}

An attack box which can hit bboxes.

Unless otherwise specified, this works exactly like an 'attack' command.

blast attacks always knock the enemy down, and sends them flying farther than normal. A 'blast'ed enemy will also be able to hit other entities and knock them down.

shock {x} {y} {right} {down} {damage} {knockdown} {block} {noflash} {pausetime} {z}

A shock attack box which can hit bboxes.

Unless otherwise specified, this works exactly like an 'attack' command.

If this attack hits an enemy or player, they will play their SPAIN or SHOCK animation.

burn {x} {y} {right} {down} {damage} {knockdown} {block} {noflash} {pausetime} {z}

A burn attack box which can hit bboxes.

Unless otherwise specified, this works exactly like an 'attack' command.

If this attack hits an enemy or player, they will play their BPAIN or BURN animation.

freeze {x} {y} {right} {down} {damage} {time} {block} {noflash} {pausetime} {z}

A paralyzing attack box which can hit bboxes.

Unless otherwise specified, this works exactly like an 'attack' command.

The target will be frozen solid for {time}. They will be unable to attack, move, use specials, etc. If they have an fmap, they will change to that pallete.

{time} is measured in seconds.

Any attacks to a frozen target will cause knockdown. Freeze attacks on their own do not knock enemies down (Unless they were frozen to begin with).

steal {x} {y} {right} {down} {damage} {knockdown} {block} {noflash} {pausetime} {z}

An attack box which can hit bboxes.

Unless otherwise specified, this works exactly like an 'attack' command.

If this box hits a player or enemy, it will drain life from the target and give it to the attacker.

quakeframe {frame} {loops} {intensity}

Used to make screen shakes with certain intensity.

{frame} determines at which frame the quake/shake starts.

{loops} determines how many quake this animation will make after quake starts. Bear in mind that if the animation ends, there won't be another quake. And you have to provide a frame for each quake.

{intensity} determines how strong the quake would be. Technically it is how far the panel would go down in pixels. Negative value works for this.

move {x}

Starting with the next frame, the entity will move forward (x) pixels with every new frame.

This value must be set to 0 again to stop the entity from moving any further during the animation.

You can use a negative value for (x) to move the entity backwards (Or slow their movement if they move automatically, like a jump attack).

Somewhere above 200, this value will allow an entity to run offscreen, out of play, and into oblivion. If you want to get rid of a sprite, this should fit the bill, but otherwise you'll have a suicidal entity. If you ARE trying to kill something, use a value like 1000, just in case.

movea {a}

Starting with the next frame, the entity will move upward (a) pixels with every new frame.

This value must be set to 0 again to stop the entity from moving any further during the animation.

You can use a negative value for (a) to move the entity back down towards the ground (Or maybe a pit if they aren't paying attention!).

movez {z}

Starting with the next frame, the entity will move (z) pixels towards the screen with every new frame.

This value must be set to 0 again to stop the entity from moving any further during the animation.

You can use a negative value for (z) to move the entity away from the screen, towards the background.

seta {a}

Changes the entity's altitude off the ground to {a}.

The entity will remain at this altitude until changed again with 'seta' or the animation ends.

If the animation ends and the entity is off the ground, they will fall back down while playing their IDLE animation.

Setting a>0, allows entity to fly above holes or simply not fall to holes.

platform {upperleft} {lowerleft} {upperright} {lowerright} {depth} {alt}

Turns an entity into a walkable platform.

The fields are all the same as in normal platforms defined in a stage's .txt file.

This can be changed on a per-frame basis to make platforms move up and down or shift left and right (or both, or neither).

If this entity moves with seta or move, any entities on top of it will also move up and down with it.

You can stack multiple platforms on top of each other. If you do, seta commands will be cumulative (that is, if you have a platform with seta 30 spawn on top of one with seta 50, it will be treated as being 50+30= 80 pixels off the ground, instead of 30 or 50.)

dive {hori} {vert}

Allows characters to dive while in air. So obviously, they need to be in the air for it to work.

{hori} controls how quickly the diving entity will move forward, horizontally.

{vert} controls how quickly the diving entity will move downward, vertically.

Note that a move with dive in it always starts diving at the first frame.

energycost {int}

Determines energy loss behavior for a specific animation.

Can be used in an entity's Special, Special2, and Freespecial(#) animations.

{int} (default: 6 for Special, 0 for all others.)
Amount of energy to be used.

If the entity has enough mp to perform the move, {int} is subtracted from it's mp. If not, the difference will be subtracted from the entitiy's health. This can be modified on a per move basis with mponly settings.

If the entity does not have sufficient energy, the move cannot be performed. A player controlled entity in the air will play Jumpcant if it is available. In all other cases player commands for the move are simply ignored.

AI controlled entities will not attempt to perform a move if their energy is insufficient.

mponly {int}

Determines the type of energy needed (and required) for an animation.

{int} (default: 0)
0 = If the entity has enough mp to perform the move, {int} is subtracted from it's mp. If not, the difference will be subtracted from the entitiy's health.
1 = Only mp.
2 = Only health.

sound {path}

{path} points to a sound effect. The sound will be played as soon as the next frame is reached.

Only one sound can be played per animation. If you really want more, you can either fuse the two sounds into one file, or have the entity fire a projectile with no graphics which plays one of the sounds at the appropriate time.

pshotframe {frame} {a}

If this command is present, the player will fire it's 'pshot' once frame {frame} is reached.

The projectile will be spawned at altitude {a}. Since you can't use 0 for {a}, if you want to have the projectile on the ground (and thus able to fall into pits it crosses) use -1 instead. It will spawn at 0, not -1.

The shot is defined by using the 'playshot' command.

{a} defaults to 70.

This command is outdated since all entities including players can use throwframe for same purpose.

throwframe {frame} {a}

If this command is present, the entity will throw it's 'star' or 'knife' once frame {frame} is reached.

The projectile will be spawned at altitude {a}. Since you can't use 0 for {a}, if you want to have the projectile on the ground (and thus able to fall into pits it crosses) use -1 instead. It will spawn at 0, not -1.

The projectile is defined by using the 'star' or 'knife' commands.

Actually putting 'load star' or 'load knife' in the .txt file works also but it's only loads projectile named 'star' and 'knife' respectively.

{a} defaults to 70.

Knives will be used if the entity is on the ground. Three stars will be used if the entity is airborne.

If you want entity to throw knives while entity is airborne use 'shootframe' instead.

tossframe {frame} {a} pbombframe {frame} {a}

Use "pbombframe" for players and "tossframe" for enemies.

If this command is present, the entity will throw it's 'bomb' once frame {frame} is reached.

The projectile will be spawned at altitude {a}.

The projectile is defined by putting 'load bomb' in the .txt file, or using the 'bomb', 'pbomb', 'custbomb', or 'custpbomb' command.

{a} defaults to 70.

jumpframe {frame} {height} {speedx} {speedz}

If this command is present, the entity will perform a jump once frame {frame} is reached.

{height} is jumping velocity, {speedx} is x axis velocity and {speedz} is z axis velocity. Positive {height} value moves entity up, positive {speedx} moves entity front while positive {speedz} moves entity down in z axis. Negative value works the opposite.

Only one jumpframe command counts- you can't jump more than once in an animation by putting more in, even if the entity lands before the next jump starts.

Now this command gives same effect to all entities. However there are default setting left behind for backwards compatibility. If {speedx} and {speedz} are not provided this is how the jump would be:

Height is 0:

Player: The jump is very low, but the character moves forward.

Enemy: The jump is high and vertical.

Height > 0:

Player: The jump is {height} high, and vertical.

Enemy: The jump is {height} high, and moves forward. If you don't want that effect, simply give the desired value for {speedx} or just 0.

Setting 'jumpframe' in any FALL animation will change the respective falling arc. Useful to make launchers and custom throws.

custpshot {name}

If present, for this animation only, the entity's default 'knife' entity will be replaced with this entity.

This command is outdated and supported only for the sake of modders who already were using it. Using "knife" is probably a better idea.

mpcost {int}

When the attack is performed, (int) will be subtracted from the player's MP.

This command is outdated and supported only for the sake of modders who already were using it. Using "energycost" is probably a better idea.

custfireb {name}

If present, for this animation only, the enemy's default 'fireb' entity was replaced with this entity.

This command is outdated and no longer used. Try 'knife's and 'throwframe's instead.

shootframe {frame} {a}

This command is similar to 'throwframe' but it shoots 'shot' instead.

{a} defaults to 0.

This command won't throw stars if entity is airborne so it's ideal for shooting knives while airborne.

flipframe {frame}

Used to make character turn around when frame+1 is played.

Management is not responsible for any damage caused of using this command in improper animation such as WALK.

followanim {value}

Determines which FOLLOW animation played when followup condition is met or when counter condition is met.

Possible values are 1, 2, 3 and 4.

Used together with 'followcond' or 'counterframe'.

followcond {value}

This command is to make the entity performs FOLLOW{#} if an attackbox in the animation hits.

value determines the condition requirements before FOLLOW{#} is played.

1, this animation will followup as long as it hits an entity.

2, this animation will followup as long as it hits an enemy (Or player if an enemy uses it).

3, this animation will followup as long as it hits an enemy and the target does not get killed or block the attack.

4, this animation will followup as long as it hits an enemy, and the target is not killed, does not block the attack, and is not set to be ungrabbable.

Which FOLLOW animation played is determined by 'followanim'.

counterframe {frame} {cond} {damaged}

This command is to make entity performs FOLLOW{#} if the entity is hit in set frame.

frame determines at which frame if entity is hit , FOLLOW{#} would be played.

cond determines the condition requirements before FOLLOW{#} is played.

1: The counter will always be used.

2: The counter will be used as long as the attacker was an enemy (Or a player if an enemy uses it).

3: The counter will be used as long as the attacker was an enemy, the attack was not unblockable, hits the user from the front, and was not a FREEZE attack.

damaged determines whether the entity will receive damage from the hit or not.

0, the damage won't be taken

1, the damage will be taken

spawnframe {frame} {x} {z} {a} {relative}

Used to make entity to spawn another entity. Normally it is used to spawn enemy. Spawning with this has no limit.

The spawned entity is determined by 'subentity' or 'custentity'.

{frame} determines at which frame the other entity is spawned.

{x} determines spawn range in x axis.

{z} determines spawn range in z axis.

{a} determines spawn range in y axis.

{relative} determines where the other entity is spawned.

0, count from the spawner. Spawned entity will face same direction with the spawner.

1, count from screen offset.

summonframe {frame} {x} {z} {a} {relative}

Used to make entity to spawn another entity. Normally it is used to spawn enemy. Spawning with this is limited to 1 entity.

The spawned entity is determined by 'subentity' or 'custentity'.

{frame} determines at which frame the other entity is spawned.

{x} determines spawn range in x axis.

{z} determines spawn range in z axis.

{a} determines spawn range in y axis.

{relative} determines where the other entity is spawned.

0, count from the spawner. Spawned entity will face same direction with the spawner.

1, count from screen offset.

Summoned entity can be killed with 'unsummonframe'.

unsummonframe {frame}

Used to kill summoned entity which was summoned by 'summonframe'. Obviously you need to use 'summonframe' before.

{frame} determines at which frame the other entity is spawned.

subentity {name} custentity {name}

{name} is the name of spawned entity declared in MODELS.txt. That means the entity must be loaded in MODELS.txt before you can use this.

This is used together with 'spawnframe' or 'summonframe'.

{name} determines what/which entity will be spawned or summoned with spawnframe or summonframe.

weaponframe {frame} {weapon}

This is used to switch weapon in an animation.

{frame} determines at which frame the weapon is switched.

{weapon} is weapon's number determines which weapon will be used to replace.

Obviously you need to provide weapon sets for the character first before using this.

attackone {bi}

This command sets attackboxes's ability in the animation to hit other opponent.

0, attackboxes can hit all opponents. This is default setting for all animations but grabattacks

1, attackboxes can only hit one opponent. This is default setting for all grabattacks.

grabin {type} {distance}

If this command is declared, next nonknockdown attackbox makes entity grab opponent in same manor as normal grab.

0, no effect (used to turn off grabin)

1, Opponent is pulled in while this entity doesn't move

2, Both entity and opponent are pulled each other splitting the distance

{distance} controls how far entity and opponent would be when grabbing starts.

Use this command with non knockdown attackbox of course.

forcedirection {dir}

If this command is declared, opponents hit by attackbox will face specific direction instead of facing entity.

0, no effect (used to turn off forcedirection).

-2, Left. It means always left no matter where opponent is hit.

-1, opposite of entity.

1, same direction of entity.

2, Right. It means always right no matter where opponent is hit.

Use this command with an attackbox of course.

damageonlanding {value} {type}

If this command is declared, opponents hit by knockdown attackboxes will get {value} extra damage when they land. {type} determines whether attackbox in opponent's FALL is activated or not.

0, attackboxes are not activated.

1, attackboxes are activated.

2, attackboxes are activated and opponents can perform land to safety.

Use this command with knockdown attackbox of course.

dropv {height} {speedx} {speedz}

This command controls opponent's flight path during his/her FALL animation.

{height} controls falling speed in y axis. It works the same with {height} in 'jumpframe'.

{speedx} controls falling speed in x axis. It works the same with {speedx} in 'jumpframe'. Bear in mind, that this setting is relative to this entity's facing direction not opponent's.

{speedz} controls falling speed in z axis. It works the same with {speedz} in 'jumpframe'.

Use this command with knockdown attackbox of course. However it must be declared AFTER that attackbox.

dropframe {frame}

This is used to make entity switch to set {frame} when flight apex is reached while in air.

landframe {frame}

If this is set, entity will be at frame {frame} when entity lands after jumping with 'jumpframe' or while falling.

In order to get this to work properly, give long delay to frame right before landing frame. The former frame will be played while 'waiting' to land.

counterattack {bi}

If set to 1, attackboxes in this animation will also hit opponent's attackbox. However, this only works if opponent has active bbox when he/she is attacking.

Like the name said, this is great for counter attacks.

fshadow {int}

This is used to set entity's shadow for the current frame.

Possible values are 0 to 6. The possible shadows for use are same with shadows for 'shadow' command (see 'shadow' above).

This consumes more memory so use with care.

shadowcoords {x} {y}

Adjust offset of entity's shadow for the current frame. Defaults to current frame's offset.

Obviously the entity must use 'shadow' before using this.

This consumes more memory so use with care.

itembox {x} {y} {right} {down}

An item box which can hit bboxes. This can only be used by 'item' entities.

{x}, {y}, {right}, and {down} work exactly like in a bbox.

If another entity touches this itembox, the item will be picked up by that entity.

The entity who can touch or pick this item is determined by 'candamage'. See 'candamage' above.

stun {int}

This command makes the attack freezes opponent for {int} seconds without remap change.

If there's no frozen remap at all, this command is not required cause 'freeze' can make same effect.

Use this command with non knockdown attackbox of course. However it must be declared AFTER that attackbox.

seal {int}

This command makes the attack disables opponent's freespecials and specials for {int} seconds. IOW the attack silences opponent.

Usually used with slams and throws to prevent opponent to break free with special.

Use this command with attackbox of course. However it must be declared AFTER that attackbox.

forcemap {map} {time}

This command makes the attack changes opponent's remap to {map} for {time} seconds.

Usually used with poison, fire or elemental attacks. Just for graphical effect.

Use this command with attackbox of course. However it must be declared AFTER that attackbox.

drain {time} {resource} {amount} {rate}

This command makes the attack trigger drain effect on opponent's resource over time.

Resource determines which resource is drained.

1 = HP is drained

2 = MP is drained

3 = Both HP and MP are drained.

Amount determines how much resource is drained per tick.

Rate determines delay time between tick in seconds.

Time determines how long drain effect occurs in seconds.

Use this command with attackbox of course. However it must be declared AFTER that attackbox.

noreflect {bi}

This command makes the attackbox only damages target entity without changing target's animation to PAIN or FALL if {bi} set to 1.

drawmethod {scalex} {scaley} {flipx} {flipy} {shiftx} {alpha} {remap} {fillcolor} {rotate} {fliprotate}

This command defines how current frame will be drawn.

{scalex} is integer value, when set to 256, the frame will be drawn in original width, use different values to scale it. Negative value will flip the frame.

{scaley} is integer value, when set to 256, the frame will be drawn in original height, use different values to scale it. Negative value will flip the frame.

{flipx} is integer value, when set to 1, the frame will be flipped leftright.

{flipy} is integer value, when set to 1, the frame will be flipped updown.

{shiftx} is integer value, use to lean the sprite. Might not be quite useful, it is used by gfxshadow, just add it.

{alpha} is integer value.

0 = No alpha effect.

1-6 = Alpha 1-6

-1 = Use entity's alpha.

{remap} is integer value. Will be overridden by {alpha}.

0 = No remap.

1-n = Like a map command in spawn entry, give the entity a colormap.

-1 = Use entity's colormap.

{fillcolor} is integer value, from 0 to 255, specify a color index in your palette. It can be used with alpha, fill current frame with this color.

{rotate} is integer value to specify rotation angle(clockwise), from 0 to 359. If you use a value out of the range, it will be changed automatically, for example, 370 will be changed to 10, -20 will be changed to 340.

{fliprotate} is binary value. When it is set to 1(should be only 0 or 1, not other values), the entity will change the rotate value when the direction is changed(entity's direction, if you use flipx for the frame, it is not affected), the rotate value will be 360-original, so

This command affect all frames starting from current frame. If you want to stop it, use 'nodrawmethod' below.

nodrawmethod

This command disables 'drawmethod'.

Use this with 'drawmethod' of course. See 'drawmethod' above.

bouncefactor {y}

This command determines how high entity would bounce after touching ground while playing any FALL animation. 'Jumpheight' (see above) also affect this but this command overrides it just for this animation.

{y} has exactly same effect with {y} in 'jumpframe'. For instance, max bounce height from 'bouncefactor 2' is same with max height from 'jumpframe 0 2'.

Use this in FALL animation of course.

Using Weapons

This section provides information about setting weapons for use in OpenBoR.

Warning:

Weapons require more memory! A new weapon is a new character, and it has to be loaded into memory at all times! That also means you should load the player with weapon models with load, not know, in MODELS.txt.

Limitations:

Weapons are dropped if you are hit while carrying them by default. You have to use 'weaploss' to change this.

Weapons are lost if you drop them more times than their 'counter' value or go to a new level (even if you don't go to a whole new stage).

Although you can change a player's max health when they pick up a weapon, doing so will not recover their current life.

Entities with a subtype "project" are similar to weapons. Consider both and decide which will work best for you!

Weapons require a few changes:

Original player file:

Add this line: weapons {name1} {name2} {name3} {name4} {name5} {original name}

{name#} is the name of the model loaded in MODELS.txt which this character becomes when they pick up weapon #.

{original name} is the name of the character when it doesn't have any weapons equipped.

Player with weapon model:

Create a normal player file with the weapon model's data, but do not include any fields or animations which are the same as the original's. Don't worry if it's normally required, only include altered fields. The original .txt is basically "upgraded" with the new weapon .txt- fields which are different are replaced, new fields get added, and fields which are not mentioned are not changed.

You do need a name, though. And it has to match the name used in the original player's {name#} field.

You also need to redefine freespecials which can still be used. If the animation hasn't changed, you only need to specify the input commands. This way, you can make players lose some freespecials while holding a bulky gun, whip, particle beam, etc.

This entity should have 'type none'. Do NOT give it 'type player', unless you want it to be selectable from the player select menu.

Item which gives you the weapon:

Set it up like a normal item, but give it

subtype weapon

and

weapnum {#}

where {#} is the number of the weapon which this item gives players (1-10).

Some other weapon-specific commands you may want in the weapon's file:

shootnum {int}

counter {int}

typeshot {bi}

System Files

This section describes some extra files which are used by OpenBoR.

flash.txt

A standard .txt file for an entity, but the only animation it needs is IDLE.

It should have type none. It doesn't behave any different with any other type, though.

This graphic plays when an attack box of any kind hits a bbox.

The offset is the point at which the flash will be centered.

I would strongly advise NOT setting this to loop, for reasons that will become obvious fairly fast if you do.

BoR doesn't have a default location for this, so it must be loaded in MODELS.txt.

This can be overridden on a per-entity basis with various commands.

data/SPRITES/font.gif

The most-often used font.

Characters are 9*9 boxes. There are repeated characters, some of which are used in specific situations, but I'm having trouble figuring out which is used where (If you know, tell me!).

OpenBoR fonts are not monospaced. That is, the space between two letters is determined by how wide the letter is. If your letters 'overlap', try placing a black outline around them, or moving them rightward a few pixels.

data/SPRITES/font2.gif

The font used when a selection is highlighted, and for newly-added scores on the high score screen.

Characters are 9*9 boxes. There are repeated characters, some of which are used in specific situations, but I'm having trouble figuring out which is used where (If you know, tell me!).

OpenBoR fonts are not monospaced. That is, the space between two letters is determined by how wide the letter is. If your letters 'overlap', try placing a black outline around them, or moving them rightward a few pixels.

data/SPRITES/font3.gif

This font is used as a 'header' for most options list. It appears at the top of the difficulty selection menu and the options menu, mostly.

Characters are 9*9 boxes. There are repeated characters, some of which are used in specific situations, but I'm having trouble figuring out which is used where (If you know, tell me!).

OpenBoR fonts are not monospaced. That is, the space between two letters is determined by how wide the letter is. If your letters 'overlap', try placing a black outline around them, or moving them rightward a few pixels.

data/SPRITES/font4.gif

The large font used for 'game over' and 'next' screens, the timer, and a few other places.

There is a copy of this font in the OpenBoR GUI folder. It's used there as the normal font.

Characters are 13*17 boxes. There are repeated characters, some of which are used in specific situations, but I'm having trouble figuring out which is used where (If you know, tell me!).

OpenBoR fonts are not monospaced. That is, the space between two letters is determined by how wide the letter is. If your letters 'overlap', try placing a black outline around them, or moving them rightward a few pixels.

data/SPRITES/shadow{#}.gif

{#} is a number from 1 to 6.

This graphic is used as a shadow with negative alpha transparency.

You can make the shadows larger or smaller, but the shadow will not be recentered if you do, so you must change the entity's offsets accordingly.

data/SPRITES/arrow.gif

Normally, an arrow pointing rightward.

When a player has the ability to continue moving in the level, but does not do so, this graphic will flash on the right side of the screen to tell them to move.

data/SPRITES/arrowl.gif

This works like the arrow.gif file, but it flashes on the left half in stages which scroll left.

data/bgs/hiscore.gif

This is a .gif file which will be displayed as the background of the high score screen.

Defaults to an inky black nothing.

data/scenes/gameover.txt

This is a cutscene file. If it exists, it will be played when all players lose all their lives and credits, or if a player chooses to quit during a game.

If this file isn't found, OpenBoR displays the default game over screen: the letters "GAME OVER" displayed in font 4.

data/bgs/complete.gif

This is a .gif file which will be displayed as the background of the stage complete screen.

If this file isn't found, OpenBoR displays the default stage complete screen: "STAGE # COMPLETE" displayed in font4; "Clear Bonus", "Lives Bonus" and "Total Score" with their respective score in font2.

In order for this to display, 'completebg' must be set to 1 in LEVELS.txt.

data/bgs/select.gif

Displays in the background of the player select screen.

select.gif must use the BOR palette. The interesting thing is that, just like the stages backgrounds, that image can use its own palette, by using more than 128 colours. It means that your image can contain up to 256 colours, where the 128 first colours must be the BOR palette, and the 1 to 128 next colours can be custom colours specific to that image.

data/bgs/select.txt

Cutscene file. Displays after selecting a difficulty but before reaching the player select screen.

THIS FEATURE DOESN'T WORK CURRENTLY' so don't bother implementing it.

data/bgs/unlockbg.gif

Displays in the background of the player select screen, once you've completed the game at least once.

data/bgs/hiscore.gif

A background for the high score screen.

In order for this to display, 'hiscorebg' must be set to 1 in LEVELS.txt.

Cutscene Files

This text is for setting animated .gif and music to play in a cutscene. Aside from between level cutscenes, it is also used for setting intro, gameover and howtoplay scene. It's optional but your mod looks better if you use it.

music {path} {loop}

{path} points to a .bor music file which will play.
{loop} determines if the music loops. 0 means no, 1 means yes.

animation {path} {x} {y} {skip} {noskip}

{path} points to an animated .gif file which will be played.
{x} and {y} are the x and y positions of the top left corner of the .gif.
{skip} is a flag that allows players to skip current animation. Set to 1 to enable it.
{noskip} is a flag that prohibit skipping. Set to 1 prevent skipping.
Max size is 320x240.

silence {int}

If {int} is 1, the current song will stop playing.

Select Screen Files:

This text is for setting custom select screen and allowed players. It's optional.

music {path} {loop}

{path} points to a .bor music file which will be played during this select screen.
{loop} determines if the music loops.

0 = no looping.

1 = looping.

background {path}

Set backgrounds for select screen. If it's not provided, default select.gif will be used instead.
{path} points to background graphic.
Background graphic must be paletted like select.gif. The 1st 128 colors must be same with pal.act your mod is using.

allowselect {playername1} {playername2} ....

Defines allowed players in this select screen just for current level set.
{playername#} is the name of player. You can define more than one but no need to repeat same one.
Make sure the allowed players are loaded otherwise they won't be available. OTOH if a player is loaded on a level, he/she is affected by this settings too.
The allowance or disallowance only works when playing the mod. If you load saved game, it defaults to old one.

Level Files - Level Design

This text is for setting levels and spawned objects in them. It's not mandatory but if there's no level where would players go to?. Due to many features, this part is divided into two parts. This part is for level design and the second part is for setting spawned objects.

type {type} {special} {inv}

Optional.

{type} is a binary value which determines if the stage is a normal stage (0) or a bonus stage (1).

Bonus stages end when all obstacles are destroyed, when there are no more items or when time runs out. Players won't lose a life if time runs out.

{special} is also a binary value. 0 means nothing, but if set to 1 then players will be unable to use their SPECIAL, SPECIAL2 and SPECIAL3/JUMPSPECIAL in this stage.

{inv} controls invincibility. 0 means players can be hurt by enemies. 1 means players can't be hurt by enemies (effects like knockdown or freeze still work though). It only prevents enemies from depleting players health though. Players can still lose health from 'energycost' even if this is set to 1.

music {path}

Optional.

{path} points to a .bor music file which will be played during the stage.

bossmusic {path}

Optional.

{path} points to a .bor music file which will be played when a boss appears.

spawn1 {x} {z} {a}

Optional.

{x} is relative to the starting edge of the screen. {z} is relative to the stage's minimum z value. {a} is relative to the ground.

{x} is measured from left for levels with direction right and both and it's measured from right for levels with direction left.

Although {x} could be any value, its maximum value is 320. Value more than 320 will be deducted by 320. For instance, setting x = 540 will put player in x = 220 instead (220 = 540 - 320).

{z} could be any value but it can't put player 1 beyond maximum z value.

Setting {a} > 0 makes player falls down on respawn. Default value for a is 300. NOTE: {a} only effect respawn not when level starts.

If there's a hole on player's spawn spot, the spawn spot will be shifted up or down to safe place temporary.

spawn2 {x} {z} {a}

Optional.

Works exactly like spawn1, except that it sets the respawn position for Player 2.

spawn3 {x} {z} {a}

Optional.

Works exactly like spawn1, except that it sets the respawn position for Player 3.

spawn4 {x} {z} {a}

Optional.

Works exactly like spawn1, except that it sets the respawn position for Player 4.

direction {dir}

Determines which direction the screen scrolls in.

{dir} can be right, left, both/rightleft, up, down, in, out, inout, outin, or leftright. Defaults to right if not declared.

up and down scroll background up and down respectively and automatically. You cannot scroll left or right in these stages. You must use groups to control enemy spawning. Wait doesn't work well here so that means you have to watch the time here. Put time item or simply set time to 0. Panels, neons and screens are not scrolled. left and right must be scrolled manually, like normal.

both or rightleft is pretty neat. It's like direction right but it allows you to freely scroll left or right. When you reach a wait, you won't be able to move back past the previous wait until all spawned enemies prior to wait are killed.

leftright is similar direction both but it's like direction left instead. in and out is new scrolling system in which player scrolls in or out respectively. In means up in z axis while out means down. Just like left and right, it must be scrolled manually. inout and outin is similar to direction both but they are like direction in and out respectively.

Screen, neon, water, etc don't work well in direction in, out, inout and outin.

bgspeed {speed} {dir}

Causes the background of the stage to scroll by automatically.

{value} should be a number from 0 to 30 or so. 0 means no movement, 1 means slow movement, and anything above that means faster movement.

{dir} controls the direction that the background moves in. 0 means right-to-left, 1 means left-to-right

settime {int}

This stage's time limit will be {int}.

If {int} is 0, the player will have unlimited time.

The timer resets every time a 'wait' group of enemies is cleared. Note that it doesn't reset in between groups, only waits!

Using 'settime 1' isn't funny. Okay, it's a little funny the first time.

Don't forget to use 'Time' items when needed!

notime {bi}

Determines whether or not the player can see the game timer.

noreset {int}

Determines when clock resets aside from clearing wait, clearing level and time out.

0 = (default) Clock resets when another player joins mid-stage and when player respawns.

1 = Clock only resets on time out.

2 = Clock resets when player respawns.

noslow {bi}

Determines whether or not the game slows down after beating a boss.

background {path}

{path} points to a graphic file which will be visible behind all the sprites and panels.

The image used must have a width which is a multiple of 4 (ex. 4, 200, 128, not 3, 202, 130).

The default height is anything from 1 to 240.

The graphic automatically repeats if the stage is longer than the background.

Using the transparent color in backgrounds can lead to an interesting visual effect. Afterimages will be left by any and all graphics which pass over transparent sections. This isn't what you normally want, though.

water {path} {warp}

Optional.

{path} points to a graphic file which will be used as a watery background.

the graphic appears at the {BGHeight}, which is defined with 'z' in LEVELS.txt. If no {BGHeight} is set, it will appear right under background.

If you use 'rock 0' or do not include the rock command, the water will be warped by a sine wave (It will slither back and forth). {warp} will determine how quickly the waving will occour.

If you use 'rock 1' in the same stage, the water will float past in parallax (The graphic gets larger as it approaches the playing area). {warp} will determine the speed.

rock {int}

Optional.

0 means nothing.

1 means the level floats up and down slightly.

2 will cause the stage to remain steady for a second or so, then quickly shake twice. Should resemble the steady rocking on a train ride.

3 will cause the stage to shake with a constant, steady rumbling, with occasional 'hiccups'. This one looks like what you might feel if you were riding in a moving van or on top of a moving eighteen wheeler.

mirror {bi}

Optional.

Determines whether or not there is a mirror in the background.

0 means no mirror effect.

1 means that sprites will have a "mirror" image drawn between the background and panels.

panel {norm} {neon} {scrn}

{norm}, {neon}, and {scrn} are paths which point to the normal, neon, and screen graphics for a panel. {neon} and {scrn} are optional fields. If you aren't using them, put the word 'none' in their place.

Panels are mostly used as the floor and walls of a screen.

Panels are normally 244 pixels high, but should be 256 if the stage is set to rock up and down. It may also need to be changed depending on the 'z' values set in LEVELS.txt

You can use whatever width you want, but it's a good idea to use simple values like 100, 150, or 360. It makes it much easier to add up the total length of the stage.

All panels in a stage should have the same length and height.

If you overlap part of the image used in one panel with another, the computer will still try to draw both. Be nice to computers. Don't overlap panel layers.

Normal mode panel layers are just plain images. They have no visual effects.

Neon mode panel layers use 'pallete cycling': certain colors slowly change to different colors. To be more specific, colors 128 through 135 in the pallete will be cycled by two steps three times each second.

Screen mode panel layers have alpha transparency. That means, they blend with the colors behind them, darker colors are more transparent, and brighter colors will blend less.

You can have up to 26 panels in a stage. They are labeled by OpenBoR from a to z. This is how OpenBoR thinks of them, don't actually put those letters in the panel declaration.

frontpanel {path}

{path} points to a panel layer which will be displayed on top of all other sprites and graphics except for the HUD. This can be used to make foregrounds.

frontpanels display in the order they are declared and repeat when they run out. You don't need to declare an order like with normal panels.

order {panel#}{panel#}{panel#}...

Determines the order of panels in a stage.

{panel#} is a letter a through z which corresponds to a panel. There should not be spaces between the panel declarations (ex. order abcabcada, not order a b c a b c a d a).

The same panel can be used more than once.

You can have up to 1000 panels ordered, but there's a catch: the engine can't read a line with 1000 characters in it (The max is somewhere around 100). To get around this, you can place the additional panels on another line with a separate order declaration, like this:

order abcdefghij order klabcd order eeabcdef

That '...' at the end doesn't mean you should put a ... at the end. It means the pattern repeats like it has been repeating so far.

If you use 'direction left', panels will be displayed from left to right, starting with the last order and working up. In other words, the previous declaration would become 'eeabcdefijklabcdabcdefgh' instead of 'abcdefghijklabcdeeabcdef'.

hole {xpos} {zpos} {upperleft} {lowerleft} {upperright} {lowerright} {depth}

A 4-sided hole will be created at the specified point.

This is a bit complicated, so listen up! {xpos} and {zpos} are the x and z positions at which the hole is spawned (how far from the start of the stage, and how far from the top of the screen, respectively).

{lowerleft}, {upperleft}, {lowerright}, and {upperright} determine the x position of the four corners of the hole. These numbers are how far from the {xpos} the corners are, not how far from the start of the stage.

{depth} is the z depth of the hole: how far it stretches from the {zpos} to the top of the screen.

As an example, if you wanted to create a 10x40 parrallelagram ( /_/ ) hole at the bottom of the screen (256) at scroll position 500, you might put

hole 500 256 0 10 10 20 40

If you create a hole which is not at the bottom of the screen, entities will be visible as they fall off the stage. Probably bad. So place an entity with type none right below the bottom of the hole which resembles the floor. This will cover up almost any entities which fall in the hole.

If used in a stage which scrolls left, the holes will start at the left edge of the starting screen and move right from there. So only holes which would appear in the first 320 or so pixels of the screen will actually be visible, and they'll be at the start of the stage.

The default values are 240, 12, 1, 200, 287, and 45, respectively.

wall {xpos} {zpos} {upperleft} {lowerleft} {upperright} {lowerright} {depth}{alt}

Creates a 4-sided wall or platform at the specified point.

All of the field except {alt} are the same as they are in holes.

{alt} is used to control the height of the platform. It's measured in pixels. So for a wall with 10 for it's {alt} value would be 10 pixels high, any entity on the platform would be displayed 10 pixels off the ground, and entities would need to jump at least 10 pixels off the ground to get on top of the wall.

If you want to make a wall which can't be jumped on, simply give it a {alt} value somewhere in the lower thousands. Very, very, VERY few entities should be able to jump on it.

In order for enemies to get on platforms higher than their current position, they need a JUMP animation with a range set for it, and/or an animation which lifts them off the ground.

endhole {bi}

Optional.

Determines if the rightmost edge of the stage is a pit.

1 means yes. 0 means no.

Don't use this if your stage scrolls left. Trust me on this one.

blocked {bi}

Optional.

Determines if the edge of the stage is a solid wall. 1 means yes. 0 means no.

Entities who hit the wall will stop moving.

This always appears on the right side of the screen, and if you choose 'scroll left' players will start inside the wall. They warp out when the player moves, but it still looks funny.

If you combine 'endhole' and 'blocked', you'll end up with a blocked exit with a pit behind it. You can only reach the pit by starting behind it with 'direction left' (Which is a very bad idea).

loadingbg {path} {set} {bx} {by} {bsize} {tx} {ty} {tf}

This command allows custom loading background to be displayed while the current level are being loaded.

{path} determines the location of used background.

{set} determines how loading screen would be.

-1 = default black screen with loading and status bar.

0 = no loading screen.

1 = loading screen background and status bar.

{bx} and {by} determines x and y coordinates of loading bar top left's location respectively.

{bsize} determines loading bar's length.

{tx} and {ty} determines x and y coordinates of "LOADING" text location respectively.

palette {path} {a1} {a2} {a3} {a4} {a5} {a6}

This command loads new palette to be used by script or by 'setpalette' command (see below).

{path} is the path to loaded palette in .act format. For instance: data/bgs/staage1/pal001.act}.

{a1}, {a2}, {a3}, {a4}, {a5} and {a6} are flags that determines usage of respective transparency. a1 means alpha 1 transparency, a2 means alpha 2 and so on.

This transparency feature costs 384kb memory when palette is loaded so use with care.

This command can be declared more than once if more palettes are required.

gravity {value}

This sets gravity or falling speed in the level.

It should use negative value. Defaults to -10

Setting -5 makes characters fall like in water.

maxfallspeed {value}

This sets maximum falling speed in the level.

It should use negative value. Defaults to -60

Setting -20 makes characters fall like in water.

maxtossspeed {value}

This sets maximum jumpheight in the level.

It should use positive value. Defaults to 1000

Level Files - Level Objects

spawn {name}

{name} is the name of an entity defined in a .txt file which was loaded in MODELS.txt.

{name} will be spawned (created). Where and with what attributes are determined by the next set of fields.

2pspawn {bi}

If {bi} is set to 1, the entity is only spawned if there are 2 players playing.

3pspawn {bi}

If {bi} is set to 1, the entity is only spawned if there are 3 players playing.

4pspawn {bi}

If {bi} is set to 1, the entity is only spawned if there are 4 players playing.

alias {name}

The spawned entity will appear to have the name {name} in-game. For instance, if you used

spawn Rugal

alias Hotdog_Man

then when you reached Rugal in the stage, his name would be displayed as 'Hotdog Man'.

The rules from an entity's .txt file concerning names apply here, too. So use '_' instead of spaces if you want to use spaces.

map {pal}

{pal} is a number from 0 to 14 which corresponds to an entity's 'remap' pallete. The entity will use that pallete.

health {int}

{int} is a health value which will be used instead of the entity's normal health.

2phealth {int}

{int} is a health value which will be used instead of the entity's normal health, but only if there are 2 players playing.

3phealth {int}

{int} is a health value which will be used instead of the entity's normal health, but only if there are 3 players playing.

4phealth {int}

{int} is a health value which will be used instead of the entity's normal health, but only if there are 4 players playing.

mp {int}

For items spawned in a stage.
When a player picks this item up, they'll regain {int} MP instead of it's normal value.

dying {remap} {health1} {health2}

If this entity's health drops to or below {health1}, they will flash between their normal pallete and the {remap} pallete.

If their health drops to or below {health2}, they flash even faster.

item {name}

Optional.

When this entity dies, a {name} will instantly be spawned in it's place.

You can't make an entity drop multiple items.

itemhealth {int}

Optional.

Changes the health of a dropped entity to {int}

itemmap {int}

Optional.

Changes the pallete of a dropped entity to {int}

itemalias {name}

Optional.

Changes the name of a dropped entity to {name}

itemhealth {int}

Optional.

Changes the health of a dropped item to {int}

2pitem {name}

Optional.

Works just like 'item', except that this will only be spawned if there are 2 people playing.

3pitem {name}

Optional.

Works just like 'item', except that this will only be spawned if there are 3 people playing.

4pitem {name}

Optional.

Works just like 'item', except that this will only be spawned if there are 4 people playing.

boss {bi}

Optional.

If set to 0, nothing. If set to 1, the character is a boss. When a boss appears, the music will change to the boss music (if it was defined). Killing all the boss characters in a level will kill all other entities and will also end a stage automatically.

flip {bi}

Optional.

If set to 0, nada. If set to 1, the entity will face the opposite direction. Used for obstacles and traps most of the time, but it can also be used to make enemies who spawn on the left side of the screen face towards players from the start.

Can also be used for entities with subtype arrow to make them fly from left to right.

coords {x} {z} {a}

Determines the x, z, and a positions on the screen where the entity will spawn.

{x} and {z} are relative to the screen's current position, NOT the actual position in terms of the level itself.

{a} is how high off the ground the entity will spawn.

If {x} is between 0 and 320, and the entity is an enemy, it will magically fall out of the sky. Unless it has a SPAWN animation, in which case it'll play that.

If {x} is between 0 and 320, and the entity is an obstacle or item, it will magically appear out of thin air. Unless it has a SPAWN animation, in which case it'll play that.

In case you're wondering, the BoR playing field is, in bbox format, 0 320 160 230. Unless, of course, you've changed the {min} and {max} values in LEVELS.txt with 'z'. You can also place enemies outside those ranges, but they'll try to return to the playing field if you do.

Most projectiles will automatically die if their offset is more than 80 pixels offscreen left or right (their x value must stay between -80 and 400). Knives are the only exception: they can go up to 180 either way (-180 to 500). Other entities will also die if they move too far, but they have more leeway (Around 1000 in either direction). Keep that in mind while spawning characters.

Bikers should normally be spawned further out than other enemies. You'll probably want around 400 or -80 (But not more than -200 or 520, or they'll die).

at {pos}

For an entity to be spawned, the player must have scrolled to {pos} in the level.

{pos} is scroll position in pixels measured from start of level. For direction both and right, it's measured from left edge. For direction left, it's from right edge.

This must be declared together with other level objects. Normally typed after the latter.

wait

This isn't part of an entity's spawn. It doesn't take any arguments either. It should be followed by an 'at', though.

Screen scrolling will be stopped at {pos} in the 'at' command following the wait until all current enemies are killed.

In direction up and down, background scrolling can be stopped also with 'wait' but there's no way to make it auto scroll again.

group {min} {max}

Also not an entity spawn, also should be followed by 'at'.

Causes entities to be spawned in groups. When the number of enemies goes below {min} (not equal to, below), entities will be spawned until there are {max} enemies onscreen or there aren't any more enemies to spawn in the group.

Group size declarations remain in effect until changed. So use a large group size like 'group 100 100' to "cancel" the grouping.

'wait' is also counted to 'group' so it's best to put 'wait' first to prevent it being limited by 'group'.

aggression {value}

For enemy spawns.

Spawned enemy's aggression will use this {value} instead of the enemy's normal aggression.

blockade {pos}

Optional. Used in direction both levels.

{pos} is scroll position and it's similar to the one for 'at'. {pos} for 'blockade' and 'at' can be different though.

This is to stop players scrolling backwards in levels with direction both at {pos}. If the level is long, you may want to use this since it could be weird being able to scroll back to beginning of level.

It must be followed by 'at'.

setpalette {palette}

Change palette in use to other palette which is loaded by 'palette' (see above).

{palette} correspond to the loaded palette number so if you want to use 2nd palette, set this to 2.

Like other level objects, this command must be followed by 'at' (see above) and also counted by 'group'.

shadowcolor {index}

This command changes gfxshadow's fill color to {index} at defined scrollpos. This is used together with 'gfxshadow' (see above).

{index} refers to current level palette's index.

Setting {index} to -1 turns gfxshadow off.

Setting {index} to -2 turns off fill color gfxshadow .

Must be followed by 'at'.

shadowalpha {index}

This command changes gfxshadow's from black shadow to mirrored image at defined scrollpos. This is used together with 'gfxshadow' (see above).

In case you don't understand, this is used to mirror image of entities appear on 'ground'. Useful if the 'ground' is actually water or mirror. Disable normal 'black shadow' 1st with 'shadowcolor' above before using this.

{index} refers to any alpha blending type i.e 1-6.

Setting {index} to -1 turns gfxshadow alpha off.

Must be followed by 'at'.

light {x} {z}

This command changes light direction to {x} {z} for gfxshadow's at defined scrollpos. This is used together with 'gfxshadow' (see above).

If {x} is not 0, the shadow will lean left or right (256 means 45 degree, try use some values and see what is the best value)

{z} can't be 0, because it is for the length of the shadow in z direction, 256 will make the shadow as long as its owner's sprite, and 128 will be half length. If it is negative value, the shadow will be flipped head-to-foot.

Must be followed by 'at'.

load {name}

Used to load a model in current level.

This command is for loading weapons models or other entities which shouldn't be loaded until this command is executed. It useful for memory usage control.

Like other level objects, this command must be followed by 'at' (see above) and also counted by 'group'.

Music Files

Recomendations:

Music files tend to be the largest portion of BoR mods, frequently larger than the rest of the mod combined. Some good ways to cut file size are to delete unneeded segments of the song, like silence at the start or end of the file or identical loops in video game tunes.

Chose some decent songs. If you've got different tastes in music, that's one thing, but just choosing random noise is something else. Make sure the music fits.

How to Convert:

You'll need a program called WAV2BOR.exe or CONVERT.exe, and some PCM 16-bit mono .wav files, preferably at 22 Khz. If you're having trouble understanding that last line, don't worry. Just open the .wav in Microsoft Sound Recorder and go to 'Save as...'. From there, find each of those options (PCM format, 16-bit mono at 22050 (22 Khz)) and select them.

Once you've got the files, place them all in a folder called W2B in your C: drive. This step wasn't necessary, but if you're having trouble it might fix some problems.

Create a new .txt file, and give it a name with the .bat extension. Add the following line for each .wav you want to convert, then double click on your .bat file to start the batch conversion of your .wav files to .bor music files:

wav2bor.exe {wav} {bor} {artist} {title}

{wav} is the name of the .wav file to be converted (make sure it has .wav on the end). {bor} is the file that will end up holding the .bor music. {artist} and {title} are optional fields which can be used for an artist name and song title. Or a dog's name and your favorite food. It doesn't really matter. If you do use them, remember that you must use underscores (_) instead of spaces ( ).

Sound Files

data/sounds/beat1.wav

Played when an attack hits an entity's bbox.

Normally, this sound will be played slower depending on how much damage the attack deals. If this is a problem, you can disable this with the 'noslowfx' command.

data/sounds/fall.wav

Played when an entity hits the floor after being knocked down.

data/sounds/get.wav

Played when a player picks up an item.

data/sounds/money.wav

Played when a player grabs a score item.

data/sounds/jump.wav

Played when someone jumps.

data/sounds/indirect.wav

Played when one character is flung into another with THROW.

data/sounds/punch.wav

Played when a player uses an attack in their attack chain (Pressing attack from a standing position). Normally only heard if the attack misses.

data/sounds/1up.wav

Played when the player gets a 1-up.

data/sounds/go.wav

Plays three times in a row when the player has beaten all enemies at a wait and can now move forward again.

data/sounds/timeover.wav

Played if the timer hits zero. Also played if all credits are lost.

data/sounds/beep.wav

Played in menus (not in game) when you move up or down.

data/sounds/beep2.wav

Played in menus (not in game) when you select an option.

data/sounds/bike.wav

Required if you have bikers. Plays for bikers, of course.

data/sounds/block.wav

Optional. Plays when an entity blocks an attack.

Warning: keep an eye on the file size of your .WAVs.

Troubleshooting

NONFATAL:

If your mod isn't crashing, but it's still acting funny, check this list:

After downloading a new version of OpenBoR, my HUD (life bar, time, etc.) appear at the bottom of the screen and my options and controls are messed up!

Sometimes, the format of the file SETTINGS.SAV will be changed. When this happens, you'll need to delete the SETTINGS.SAV file you currently have in the same folder as OpenBoR and re-open OpenBoR.

My entities are a discolored box/have the wrong colors!

OpenBoR uses a pallete system. Make sure the entities have the correct pallete.

My entities have tried to attack but nothing happens!

Are you sure you have given attackboxes in their attack animation?

FATAL:

If your mod is crashing, OpenBoR will store a little error message in "OpenBoRlog.txt" inside the Logs folder. That's for the Windows version, in DOS the log file is "OpenBoRl.txt". The last line is the error message.

Unable to open file '{path}'

Check the path, is the path typed correctly? If it is look for the file, is it placed in right folder or not?

Something is wrong with the file at {path}. Some possible known causes:

One of the file or folder names in the path is too long. BoR can only read from files and folders whose names are from one to eight letters long, not including the extension. For example, "BOB.txt", "12345678.gif", and "data/flip/flop.txt" are okay names. ".txt", "123456789.gif", and "data/nameistoolong/flop.txt" will all make the program spit out an error.

Another possible reason is the file is corrupted. Try remaking the file.

Failed to create colourmap from images '{path1}' and '{path2}'.

The game tried to make an alternate pallete (remap) of {path1} using the data in {path2}, but couldn't. Some possible known causes:

{path1} and/or {path2} do not exist. They may actually exist and just have the wrong name, so check your spelling if the files are there.

{path1} and {path2} are not based on the same image. They should be the exact same pictures EXCEPT that certain colors in one file have been replaced with another.

Command '{com}' not understood in file '{path}'

The line {com} is somewhere in {path}. However, OpenBoR does not have any code for handling {com}, and doesn't know what to do.

Check {com}'s spelling. For instance, it's colourselect, not colorselect.

Make sure you have the latest version of OpenBoR. New features won't work in older versions.

Unable to load file (may be out of memory)

This is a real sneaky error. It means that one of your .txt files which was just loaded doesn't end with a blank line.

To fix this, just go to the last line in the offending .txt file(s) and press enter once.

This will only crash OpenBoR when the problem file is actually loaded, not when it is 'known' while loading files at the start.

DOS/32A warning (9003): real mode interrupt vector had been modified: INT 43h

Roel (creator of the original BoR) finally found out some more about this. It's a Windows/DOS video mode emulation thing. Don't worry about it. It won't damage anything. We think.

Other Stuff

Outside the Box:

OpenBoR adds a lot to an already powerful, simple engine. But you can take things even further with a little thought.

Just because they're called SHOCK, FREEZE and BURN doesn't mean they need to be bolts, icicles and flares. They could be other elements, or not even elements at all- ever noticed that most fighting games have separate graphics for low, mid, and high-level attacks? Or ever wanted a character to just sit still for a second or two? Among other things...

Related to above, various attackboxes, SHOCK and BURN can be used to make custom slams and custom throws. There are many commands that also helps making them.

Text objects pause the game and can play an animation. You can use it for cutscenes which don't end the level. - Use them wisely as they have to be stored in RAM, while cutscenes are streamed in real-time.

Enemies can drop other enemies. That means you can create enemies with second forms.

An entity's offset, bbox, attack box, platform box, etc. don't need to overlap. Or even be close to one another.

Cutscenes:

There is a difference in the format for animated .gif files and not-animated .gif files. In other words, if you have a single-frame animated .gif, it would be read by OpenBoR differently than an identical non-animated .gif.

These scenes must have animated .gifs:

--> data/scenes/logo.txt

--> data/scenes/gameover.txt

These scenes must have non-animated .gifs:

--> data/scenes/title.txt

--> data/scenes/titleb.txt

Score:

When you hit an enemy, you get 5x the attack's damage in points.

THROWing an enemy will earn you the attack's damage in points (you don't get any multipliers).

You get 5x the attack's power in the player's .txt file, not the damage dealt. So an attack with 1000 power would always give 5000 points.

You get a one-up every 50,000 points.

Time:

Try to keep in mind how long it might take a player to beat a group of enemies or a boss. It feels kind of disappointing to last 99 seconds against a high-health boss or endless stream of enemies, only to die from time over.

To create an item which recovers a player's time, name it Time in it's .txt file and in MODELS.txt and give it a 'health' and 'score' value of 0.

Projectiles:

Knives fly straight forward. They can fly over pits unless they are on the ground.

Stars can only be thrown during jumps. Three fly out at downward angles.

Bombs fly in an arc. They can be thrown over pits.

Player Swapping:

'load'ing a player character in a level's .txt file will cause the player's character to become the loaded character. You can't bring the character select screen back up, though.

You can allow players to "unlock" characters in-game by only "know"ing the player in MODELS.txt, but putting an item which "load"s the entity in it's header. If a player grabs the item, they will be able to select the new character whenever they run out of lives or go to the select screen. This isn't saved when you close the game, though.

Other notes:

Both OpenBoR.exe and WAV2BOR.exe only work with short file names. If you put them in directories with a file or folder name longer than 8 characters, they won't work.

Fun:

Try to keep your mod interesting. The original BoR engine had a lot of neat tricks and fun potential which was never realized, and OpenBoR increases those possibilities exponentially. Think carefully about what you do with them.

The little things make a difference. The secret enemy in the original BoR's elevator, the wacky names, the entire hidden stage...

There are more fighting styles than just the standard Hadoken fireball/uppercut/spin kick. Try different attacks out. There are some interesting styles and attacks out there. Variety is the spice of life, right?

Limits (as of 2.0691):

Maximum number of:

sprite frames: NA**

animations: 1000

models: 200

entities: 150

panels per level: 52*

frames per animation: NA**

weapons per player: 10

remaps: 14

name length: 40

level spawns: 600

panel order length: 2000

hole spawns per level: 40

levels: 100

difficulty levels: 10

sound effects: 128

freespecials: 8

Although the source code has been changed to allow up to 52 panels per stage, a way of using panels past 26 has not yet been decided upon. There are only 26 letters in the alphabet, after all. So you can only use 26.

- NA means this particular caveat is no longer limited by source code. In other words, if you want to create an animation with 500,000 frames, that's your business. Keep in mind however that with great power comes great responsibility; it is up to you to properly manage hardware resources (in particular memory), especially if you intend for your module to play on consoles.

FAQ

What do you mean by "entity?"

It's anything you load in Models.txt. It's basically a .txt file which tells the game how to display and use a player, an enemy, a barrel, an apple, etc...

What's a "hud?"

HUD: Heads-Up Display. It's what shows you life, your score, your player, etc. It's a display which gives you a heads-up as to what's going on.

Can I enter my initials on the high score screen?

Nope, sorry.

Help! My settings are all wrong/My controls have randomly changed/My high scores were replaced by gibberish!

The settings file format may have changed. Try deleting or moving your settings.sav file in the same directory as OpenBoR and reopening OpenBoR.

My settings won't save on the Dreamcast version!

This is a known issue. It seems the Dreamcast VMU (which is the only way to save on the DC) doesn't get along very well with OpenBoR, and getting them to work together would require too many major changes to be possible.

Where is the DC/PS2/PSP/Windows/X-Box/Linux/GP32/GP2X/NDS version of OpenBoR?

Windows, DOS, Dreamcast, PSP, GP2X and X-Box binaries/executables are available in in the recent releases by SumolX. The PS2 and GP32 ports of the original BoR were all done by separate coders, none of whom have expressed interest in porting OpenBoR. Without skilled coders for those platforms, those ports will not be possible. As of this time, I don't think the NDS version by GPF is done yet.

What is this BoR/OpenBoR/DarkBoR/BoRHed/HoR/AotB thing I keep hearing about?

BoR is the original Beats of Rage. It is a free game made by Senile Team. It doesn't have most of the features found in OpenBoR, but it is the original.

OpenBoR was an upgraded version of BoR which has been worked on by many coders. DarkBoR was an alternate version of BoR which has several unique features such as an MP bar and enhanced weapons support. It was developed by Tails, but it is now merged with OpenBoR to make a single engine.

BoRHed is an edit of BoR with new features similar to OpenBoR. It is developed by Lord_Ball and hopefully will be merged soon with OpenBoR.

HoR is an edit of BoR designed to create shooting games. It is developed by Lord_Ball.

Age of the Beast (AotB) is a "sequel" of sorts to the original BoR. The storyline, characters and music are original work made from scratch, but some basic gameplay elements will be similar to the original BoR. It's being developed by Senile Team, creators of the original BoR.

Which version of BoR should I use?

OpenBoR is by far the best choice as of this moment. Each version has its advantage though:
The original BoR is the only version with certain ports (such as PS2 or GP32) so it has the greatest compatibility.
OpenBoR has many new features and backwards compatibility to the original BoR or DarkBoR. It also is the most optimized version.
BoRHed also adds new features, but an entirely different set.
HoR was designed for overhead/sideview shooters, so that's something of a different situation.
AotB isn't out yet. So, um, it's not really a choice at the moment.

You may be able to create multiple versions compatible with the different versions of BoR, like how game companies release cross-platform games. That's extra work, though.

I'm amazed to see 10 different attackboxes. Why would someone need that many?

You should be amazed on the effects you could make with them. With many attackboxes, modders can make an attack that push an opponent backwards, pull him/her, launchers and other cool effects.

When is AotB going to be released?

When it's done. Coding games is actually a difficult and annoying not-tons-of-fun task. Especially when you don't get paid. And even more so if people ask for demo versions or release dates. It's being worked on. It'll come when it's ready. Asking will at best do nothing and more often just slow things down.

I found an error in this guide.

Then please report it at LavaLit.com.

I found an error in OpenBoR.

Report bugs at the OpenBoR Sourceforge site to allow to track them easier.

http://sourceforge.net/projects/openbor/ (Select Tracker->Bugs)

Use the system in the following manner:

9 - Highest = System Crash / Fatal bug

5 - Medium = Something is just not working correctly and effects the engine in a strange way.

1 - Lowest = cosmetics, small things.

Lastly, Always upload a log file and enter each bug with your username and website (borgeneration/senileteam) and a where/how to be contacted if I don't know you personally.

I want something added to OpenBoR.

If you do want to ask for new features, think first. How many people besides you would use the feature? Would it be possible to program? Would it make problems with older versions? Has someone else asked for something similar? If you still want to ask, be sure to do so nicely. The people in the BoR scene are nice, and they are not getting paid for this, so they deserve some little thanks, right?

I want to HELP add something to OpenBoR.

Awesome! Head to LavaLit forums and let SamuraiX know. As a warning, even if your addition is really good, it may not be added. Backwards compatibility, speed, memory, and Dreamcast/PSP compatibility are all important factors in what gets added or not.

Can I make my own version of BoR/OpenBoR/DarkBoR?

Of course. If you're only making small, mod-specific changes (like changing the design of system menus), go ahead. If you're making larger changes (like new features or options), it would be nice if you mentioned it on the OpenBoR forums, but that's still not enforced or anything.

How do I make my own version of BoR/OpenBoR/DarkBoR?

Information on how to compile the code for PC, PSP, Dreamcast, GP2X and other platforms can be found at LavaLit.com.

Links

Credits

Beats of Rage:

Senile Team:

Original Beats of Rage game.

Roel (Opla):

Original BoR source code and engine, major improvements in OpenBoR code, some original BoR graphics.

Neill Corlett:

Dreamcast and PS2 Port.

OpenBoR:

L@Cible:

His BoR-DC-Toolchain made OpenBoR possible.

Kirby2000:

OpenBoR Maintainer 2004-2005, 4 player support.

CGRemakes:

OpenBoR Maintainer 2005-2006.

SumolX/SX:

OpenBoR Maintainer 2006-2007, PSP port.

uTunnels:

OpenBoR Coder

Tails:

DarkBoR, 4 player support.

Lord_Ball:

BoRHed, HoR.

Drikobruschi:

Contributed hi-score table code.

Kbandressen: