OpenBOR Manual

From Beats Of Rage

Revision as of 13:59, 19 August 2013 by 46.161.41.7 (Talk)

(diff) ←Older revision | view current revision (diff) | Newer revision→ (diff)

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.

9zrMIi Thanks so much for the blog.Thanks Again. Keep writing.

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:

OpenBoR Coder

Fugue:

Contributed many features, original author of this manual.

Bloodbane:

Manual updater.

OpenBoR Manual contributions:

bWWd, Zamuel, Christuserloeser, Damon Caskey

Sega:

Original Streets of Rage design, concept, etc.

SNK:

Original BoR graphics.

Sega, Capcom, SNK, Konami, Tecmo, Treasure, Sammy, etc.:

For all the brawler games!

The entire BoR and OpenBoR community:

Keep making those games!

OpenBOR Manual

From Beats Of Rage

Contents

Using Weapons

Warning:

Limitations:

Weapons require a few changes:

Original player file:

Player with weapon model:

Item which gives you the weapon:

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

System Files

flash.txt

data/SPRITES/font.gif

data/SPRITES/font2.gif

data/SPRITES/font3.gif

data/SPRITES/font4.gif

data/SPRITES/shadow{#}.gif

data/SPRITES/arrow.gif

data/SPRITES/arrowl.gif

data/bgs/hiscore.gif

data/scenes/gameover.txt

data/bgs/complete.gif

data/bgs/select.gif

data/bgs/select.txt

data/bgs/unlockbg.gif

data/bgs/hiscore.gif

Cutscene Files

music {path} {loop}

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

silence {int}

Select Screen Files:

music {path} {loop}

background {path}

allowselect {playername1} {playername2} ....

Level Files - Level Design

type {type} {special} {inv}

music {path}

bossmusic {path}

spawn1 {x} {z} {a}

spawn2 {x} {z} {a}

spawn3 {x} {z} {a}

spawn4 {x} {z} {a}

direction {dir}

bgspeed {speed} {dir}

settime {int}

notime {bi}

noreset {int}

noslow {bi}

background {path}

water {path} {warp}

rock {int}

mirror {bi}

panel {norm} {neon} {scrn}

frontpanel {path}

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

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

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

endhole {bi}

blocked {bi}

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

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

gravity {value}

maxfallspeed {value}

maxtossspeed {value}

Level Files - Level Objects

spawn {name}

2pspawn {bi}

3pspawn {bi}

4pspawn {bi}

alias {name}

map {pal}

health {int}

2phealth {int}

3phealth {int}

4phealth {int}

mp {int}

dying {remap} {health1} {health2}

item {name}

itemhealth {int}