[Tutorial] OpenBOR - the complete guide

[cyperghost]

This is version 3400 - for advanced versions go to thread OpenBOR - OpenBETA

---

Hello dear fellows,

first of all I want to tell you about the OpenBOR engine, that is installable through RetroPie Extras section. BOR mean Beats of Rage. You are right, it's an opensource gaming engine for beat'em ups in the style of Streets of Rage or Double Dragon.
Don't ask me now, how many mods (or expansions) are availiable ... but some of them are really good made and it's really lots of fun to get into teamplay.

Good list of working OpenBOR mods

List of fine working games @fredcobain
List of games @BiZzAr721
Also here a second list of working games (WIP!!) @hansolo77 - Thx to him

For ex: Nightslashers X

HiStory

Round about 1 year, @darknior was able to slightly change the source code to add the feature of a command line input. So it is now able to start a game just by calling it via it's filename, like every emulator here works. So with this change you can create your own OpenBOR system inside ES. You can take a look to this thread to see how to install a new OpenBOR entry in ES
For about 1 month I took action and changed the call of ROM files. Every mod is now started like an usual emulator used to be - through runcommand. This gots the advantage of full access to log files and usual calls of runcommand-onstart.sh and it's counterpart runcommand-onend.sh. Moreover the runcommand config menu is available if you press a button during the grey loading box appears. I think this engine is really worth a try so I created a bunch of scripts to give you best help for easy setup.

Part 1: Installation

I would recommend you to do following. Install OpenBOR via the scriptmodul.

0. Login with SSH
1. Use scriptmodul from me, install it with wget http://raw.githubusercontent.com/crcerror/RetroPie-OpenBOR-scripts/master/openbor.sh -O /home/pi/RetroPie-Setup/scriptmodules/ports/openbor.sh
2. Go to ES and select Configuration (the RetroJoy), select RetroPie Setup or just type sudo ./RetroPie-Setup/retropie_setup.sh in your homedir
3. On blue dialog, navigate to P Manage packages
4. Select exp Manage experimental packages
5. Run down the list, there select 342 openbor
6. Select S Install from source

Maybe the first step will be obsolute if the slight changes will be merged to RetroPie-Setup branch. This script just adds the %ROM% parameter to emulators config and uses @darkniors branch to get command line input of OpenBOR mods.

Part 2: Scripts setup (2 routes, choose one)

Route 1: OpenBOR - Selections menu via PORTS section (recommended for a slick setup)

I created some scripts to give you guidance through the configuration process.
At first I created the OpenBOR - Beats of Rage Engine selection script. This script enables a menu like interface for easy startup of downloaded mods. You can take a look here to see it in working action. I recommand you to download the script just to ports section in ES.

Just type wget "http://raw.githubusercontent.com/crcerror/RetroPie-OpenBOR-scripts/master/OpenBOR - Beats of Rage Engine Selection.sh" -O "/home/pi/RetroPie/roms/ports/OpenBOR - Beats of Rage Engine Selection.sh"

Route 2: OpenBOR - Selection via ES menu (nice looking to ES)

I recommend @darknior's starting thread here.
He made also an excellent instruction set of how to setup ES

Edit /opt/retropie/configs/all/emulationstation/es_systems.cfg to add this new system entry with

<name>openbor</name>
    <fullname>OpenBOR</fullname>
    <path>/home/pi/RetroPie/roms/ports/openbor</path>
    <extension>.bor .BOR</extension>
    <command>/opt/retropie/supplementary/runcommand/runcommand.sh 0 _PORT_ openbor %ROM%</command>
    <platform>pc</platform>
    <theme>openbor</theme>

Special thanks and my biggest respect to @darknior for this and the modifications he has done to C-code!

::: Extra Tipp - Carrefour Route 1 & Route 2 :::
::: ADD GAMES AUTO CONFIG AND LAUNCH MENU :::

• We add a new file "Access Selection Menu" with touch "/home/pi/RetroPie/roms/ports/openbor/Access Selection Menu.bor"
• Type nano /opt/retropie/configs/all/runcommand-onstart.sh and add text from codebox below ;)

### Access to Selection Menu
## 
# $1 = systemname > openbor
# $3 = full path of ROM-file
 
if [[ "$1" == "openbor" && "${3##*/}" == "Access Selection Menu.bor" ]]; then
    # pkill runcommand.sh # Maybe needed to prevent first runcommand from being messed up
    bash "/home/pi/RetroPie/roms/ports/OpenBOR - Beats of Rage Engine Selection.sh"
fi
 
##
### Access to Selection Menu

Part 3: JoyPad Setup

Now the seconds script is intended to make JoyPad configuration as easy as possible. It will not setup a gamepad, it downloads ready configurated settings directly to your Pie or gives you control over the files itself as you can set a configuration file as master. The Selection menu script will look for that master file and will automatically use this as current game config. So you don't have to mess around to configurate new mods again and again.

@BiZzAr721 and me definated a standard for OpenBOR input controls. This seems to fit best in various game modules and is the standard layout for all configurations we both have uploaded.

Click here to show controller config layout! Thx to @BiZzAr721 for the graphics

This part lives from your engagement! You can add your configuation to any server with direct file access. And post a link and a small description to the thread here and I might add these to the setup files. **Post with JoyPad setups is here

First create runcommand-menu folder with mkdir /opt/retropie/configs/all/runcommand-menu (it's possible the folder already excists).
Next: Just type wget "http://raw.githubusercontent.com/crcerror/RetroPie-OpenBOR-scripts/master/OpenBOR - Ultimate GamePad Setup.sh" -O "/opt/retropie/configs/all/runcommand-menu/OpenBOR - Ultimate GamePad Setup.sh"

Part 4: Game Setup

1. First we need to extract game data from PAK files.
2. Take care of naming convention the folders are named gamename.bor
3. Inside gamename.bor is a directory data ... here the whole gameset is located!

Windows method

You can download your .pak files and extract them with Windows Toolsset - it is named Openbor Makepak & Extractor.

1. Extract the archive
2. Place the .pakfile and rename it bor.pak
3. Run Batchfile extract.bat
4. PAK file will be extracted in directory data ...
5. Now move that subfolder to \home\pi\retropie\roms\ports\openbor\gamename.bor\
   5.1 gamename.bor can be choosen free
   5.2 place data directory inside gamename.bor

Linux method

I did a complete rewrite of the extraction script. The original was awful to use and failed on FAT32 and NTFS devices (because of file access rights!)
So here it is... The extraction script for RetroPie! Please report errors and issues!

1. Place your bare PAK files to /home/pi/RetroPie/roms/ports/openbor/pak
2. Run the script from any place with user PI (recommended to avoid file access issues)
3. The script extracts all pak-files (even with mixed characters) to openbor directory. Extracted data will be stored to ./openbor/gamename.bor/data
4. The script backups the old PAK files automatically gamename.pak will be gamename.pak.original

Part 5: Start Game

Restart ES! (only once needed to make script file in ports visible for ES)

1. Go back to ES and go to PORTS section
2. Select there Beats of Rage Engine Selection
3. You will see a kind of menu that will lists all games in /home/pi/RetroPie/roms/ports/openbor
4. Start the selelcted game ....
5. You will see a grey box, now press a button on your controller
6. Go to UserMenu
7. Select OpenBOR - Ultimate GamePad Setup
8. Configurate your CONTROLLER!!

Instead of using the Menu you can also add individual setted sh files to ports section @BiZzAr721 created some... you may change some pathes

OpenBOR Selection Menu

Install JoyPads via runcommand >> User Menu >> JoyPad script

1. AddOn not configurated: Select Github Controlle list --> Master config

2. I used the setup several times, so an old joypadconfig.txt is found, overwrite if you want

3. Downloaded new joypadconfig.txt with a set of controllers, select one you own

4. Last warning if you want this really to do

5. Success! We have a new masterfile now

6. We are going back to menu, and select Set Masterfile to Gameconfig

7. We see the thing operating with success!

8. Finally we can launch the game - ready to BRAWL

---

Tags:
@mediamogul Do you think now a PR for the scriptmodul is usefull?

[cyperghost]

JoyPad setup

On my github account is a file named joypadlist.txt
It can be viewed here ....

So help us to improve OpenBOR a lot buy uploading your config settings!

[jozzy1]

@cyperghost nice one with the easy to follow instructions. I did manage to get it installed a while ago but love your way with the menu... thanks!

[hiulit]

@cyperghost Great work! I'll try it out!

[cyperghost]

@hiulit said in [Tutorial] OpenBOR - the complete guide:

@cyperghost Great work! I'll try it out!

Hello my friend, nice to see you again. Yes give this a try ... OpenBOR gives good gaming experience. About the unpacking of the .pak files - I just tried on Windows ... never on Unix. So I would appreciate a nice feedback about the way you setted the game up.

Maybe @darknior and @BiZzAr721 can upload their joypad configs so I can integrate into this. Biggest respects fly out to darknior - he made the CLI work.

[BiZzAr721]

@cyperghost said in [Tutorial] OpenBOR - the complete guide:

Maybe @darknior and @BiZzAr721 can upload their joypad configs so I can integrate into this. Biggest respects fly out to darknior - he made the CLI work.

Hopefully by tonight I can get to my pc and create some configs.

Do you happen to know, for a windows batch file, the the variable that would mean "folder name" for folders in the directory the batch was executed from? I want do something like
copy master.bor.cfg to "folder name.cfg (maybe %%f, but haven't tried it yet)

[cyperghost]

@bizzar721 afaik echo %~dp0 puts out path where batch file is located. I rarely used BATCH... it's so really awfull, nearly no flow control! In your case I would use a higher language. Python for ex.... or script languages like autoit. BASIC is also very "powerfull" in that case.

EDIT: Updated controller config script ... more robust flow control and file detection

[darknior]

@cyperghost said in [Tutorial] OpenBOR - the complete guide:

Maybe @darknior and @BiZzAr721 can upload their joypad configs

Hi, yes i will make them for all my joypad and send them to you in some days ;)

[cyperghost]

@son_link Do you think you can take action and repair the OpenBOR C-code? All builds are unable to save gamestates and highscore data. It's hard to finish games or to unlock extra games by level progress :(

[BiZzAr721]

Here are 3 controller configs

PS3
Xbox 360
SNES Clone (tata)

I mapped them according to how I have my controller mapped (D-pad), and Player 2 using what is normally Player 1 keyboard default keys.

Let me know what layout is prefered and I will create new configs to keep them all to the same standard.

[cyperghost]

@bizzar721 I'm using a different layout - more like the Genesis "Bare Knuckle" or "Streets of Rage"

Y = Special
B = Attack 1
A = Jump
X = Attack 2
L = Attack 3
R = Attack 4
DPAD=DPAD ;)

But I will upload your configuartion. I think the main purpose should be that dedicated controllers can be used in a quick way. Thanks for your contribution ;) You can also upload them to your github account. So I can just link to them, that makes updates a bit easier as long the filenames do not change ;)

Edit: I tried all your controller configs with my Snakebyte PS3 clone... Only the PS3 worked but the moving axis are swapped. So I think the contribution of ready configurated cfg files is essential for easy setup. Because every controller gots different mappings.
If someone can contribute the 8-bit-do's then the community will appreciate this ;)

Edit 2:
Did you map the DPAD to analog input on your PS3 and XBOX? Because only the PS3 analog input (left stick) worked on my Snakebyte (it's a kind of XBOX360 clone)? I would always prefer DPAD instead of analog input but I can't verify the settings (lack of controllers)
Again thank you very much

[BiZzAr721]

@cyperghost said in [Tutorial] OpenBOR - the complete guide:

Thanks for your contribution ;)

No, thank you

@cyperghost said in [Tutorial] OpenBOR - the complete guide:

If someone can contribute the 8-bit-do's then the community will appreciate this ;)
::cough:: @darknior ::cough::

I use d-pad for all - I like it much better to double tap for run

I'll give your controller setup a try and see how I like it

[cyperghost]

@bizzar721 said in [Tutorial] OpenBOR - the complete guide:

I use d-pad for all - I like it much better to double tap for run

Perfect!
I tested also a cheap SNES clone pad (brand: 2tech) - worked flawless with your SNES settings.

[ppuspfc]

What a nice idea, congrats on everyone

[GreenHawk84]

Can you tell me how to fully uninstall OpenBOR? I went into manage packages and uninstalled but I still have an entry in Ports.

[cyperghost]

@greenhawk84 The same way you add or remove roms. Just delete that entry via ES, SSH or SAMBA fromhome/pi/RetroPie/roms/ports

[hansolo77]

I'm lost. Trying to follow the OP instructions... Getting hung up on the very first part. Executing the command wget http://raw.githubusercontent.com/crcerror/RetroPie-OpenBOR-scripts/master/openbor.sh -O /home/pi/RetroPie-Setup/scriptmodules/ports/openbor.sh does something, but not sure what to do next. You say to go through "Select Configuration", etc.. but there is nothing here. After executing the first command, it just sits at the terminal. I'm a little better at this than I used to be, but I'm being ignorant on purpose to help others...

The command appears to basically download a modified openbor.sh file and replace it with the one located in the RetroPie-Setup script path. At this point, am I supposed to run the command sudo ./RetroPie-Setup/retropie_setup.sh?

---

EDIT
I tested my theory and it looks like the modification worked. However, I got a lot of warnings during the compiling. Can somebody take a look at my log and see if it's something bad? Do I need to do something?
https://pastebin.com/wKi4jc7p

---

EDIT 2
I went ahead and tried to figure it out on my own. I've got 2 games (modules) downloaded. I unpacked them and have them located in the ~/RetroPie/roms/ports/openbor/**gamename**.bor path. With only 1 game, running the Port from the EmulationStation "ports" menu just launches the game. With 0 or 2 (or more) games, launching the Port will provide an "ingame" launching window. I can make both games I've downloaded RUN, but I can't get the control to work. I can navigate with the keyboard, and can go into Options -> Control Options... -> Setup Player 1..., but I can't get it to change any of the options to my controller. I made sure "GamePads Enabled" is set. Any ideas? I'm using a wireless Xbox360 controller and official dongle. Also.. I've not installed the "Part 3: JoyPad Setup" script yet.. should I do that? It seems like I should be able to create a config without it, just for testing purposes. I'll experiment further...

---

EDIT 3
From SSH, running the command:
wget "http://raw.githubusercontent.com/crcerror/RetroPie-OpenBOR-scripts/master/OpenBOR - Ultimate GamePad Setup.sh" -O "/opt/retropie/configs/all/runcommand-menu/OpenBOR - Ultimate GamePad Setup.sh"
Results in this error:

/opt/retropie/configs/all/runcommand-menu/OpenBOR - Ultimate GamePad Setup.sh: No such file or directory

I checked, and there is not directory called runcommand-menu on my system.

Should this be downloaded to /opt/retropie/supplementary/runcommand by chance?

---

EDIT 4
I created the folder using sudo mkdir /opt/retropie/configs/all/runcommand-menuand then ran the wget and got the script. The script won't execute unless you're running an OpenBOR "ROM". I tried to get the script to launch from the Ports menu but it wouldn't work. I have the script running now from a ROM listing, and I chose to download the XBox360 controller config. I guess it was successful in that it said it was. But I still can't get it to work inside a game. What am I doing wrong?

---

EDIT 5
I finally figured out what my problem was. I had to take my console apart to get at the plugs. Apparently I'm still having the same issue I've always been having. Assignment of what controls are being used. For some damned reason, the system boots up with my Raphnet NES controllers as the primary input, and not my Xbox controller. I've gotten around this because EmulationStation works with ALL controllers, not caring who P1, P2, etc is. RetroArch does the same thing, but assumes P1 is the person who enters the game. I dunno why, it just works that way. The way I've built my system, I wanted to have the option to use original controllers (NES for NES games, Sega for Sega, Atari for Atari). Xbox360 is my primary "always use" controller. But if I want to play with originals, I have a modified runcommmand-onstart that checks if the system being loaded matches a pre-determined system, then executes the loading of the XBOXDRV driver to map controls for them. It works great. But whenever I go and try to add something new, OpenBOR in this case, the controls get all f*ed up. I couldn't figure out why the controller wouldn't work, even after going through all the trouble to figure out how to get the script to run to download a premade config. So I unplugged everything from the Pi except the Xbox dongle, and it worked. I then plugged in the Sega (MayFlash) adapter, and it still worked. But once I plugged in the NES (Raphnet) adapter, everything stopped working. So I'm going to have to go back and figure out what's causing this. In the mean time, it looks like I got it figured out.

** I think the OP of this thread should be made a little more clear. It's very easy to get lost in all the stuff needing to happen.

[cyperghost]

@hansolo77 Hey man... everything all right? You've done a real stresstest to this guide and revealed some issues, too.

EDIT 0 und 1

The command appears to basically download a modified openbor.sh file and replace it with the one located in the RetroPie-Setup script path. At this point, am I supposed to run the command sudo ./RetroPie-Setup/retropie_setup.sh?

Also doable but I ment the graphical approach, go to ES select CONFIGURATION (the RetroJoy graphic) and then select RetroPie-Setup ;)

But I add your SSH approach, too

Yes you are right the first wget just overwrites the scriptmodule to add the tweaks. I wanted an automated process.... Because it's much better than

1. Now edit emulator config and add %ROM%
2. Exchange OpenBOR binary
3. Make the binary executable ;)

Yes ... the compiling errors are okay. It's sadly an old unsupported port (and the only one that runs on ARM Pie). We need the help of advanced C coders here.

Edit 2 and 3

Also.. I've not installed the "Part 3: JoyPad Setup" script yet.. should I do that? It seems like I should be able to create a config without it, just for testing purposes. I'll experiment further...

Not needed but it will make things easier!

Should this be downloaded to /opt/retropie/supplementary/runcommand by chance?

No it's /opt/retropie/configs/all/runcommand-menu, the runcommand-menu was introduces for more than one year. So I'm kind of shocked that in your installation the directory isn't available. Will change this in instructions...

Edit 4

I created the folder using sudo mkdir /opt/retropie/configs/all/runcommand-menuand then ran the wget and got the script.

It is intended to run only out of runcommand. So you don't have provided any argument to the script the script denies to work with the message "Only openbor supported". It's a fail safe feature.

Edit 5

I finally figured out what my problem was. I had to take my console apart to get at the plugs. Apparently I'm still having the same issue I've always been having. Assignment of what controls are being used. For some damned reason, the system boots up with my Raphnet NES controllers as the primary input, and not my Xbox controller.

Your setup seems very complex. So it's a good test. We assumed the main controller is always assigned to Player 1.

[hansolo77]

@cyperghost - Thanks. :) I've been sick and when it comes to things like this I get very critical and upset when things don't work as they should. I'm super happy with myself though that I've come as far as I have in figuring out most of this stuff on my own. I remember just starting out, not even knowing what SSH is, now here I am making my own directories, using sudo, creating my own systems, etc. That reminds me, I think @darknior needs to update his walkthrough to include some <system> and </system> tags in that part. I'm building this as a System, rather than using your launching script to pick a game. I wanted to be able to have screenshots/videos for each game. But overall, this is the stuff I love to do, tamper with things to figure out how to make them work. I just wish I could code or write scripts. Then I'd REALLY be helping the community!

[cyperghost]

@hansolo77 No problem pal. Hope you are well again ;)
I prefer the launching script because this offers automate setup of master controllers so far. But I recommend the JoyPad script ... Maybe you can help us to generate an ultimate controller setup.

I never come to action to install openBOR because I don't like to tinker with controller configs. But as this was done and I saw it can be launched by runcommand, it was much easy to implent working scripts ;)

BTW: I included also a JoyPad setup link in the launching menu script. It will now warn you if no configuration was found. I believe to get the best of OpenBOR use

1. The ES integrated way for showcase
2. The script part for quick setup

I just wish I could code or write scripts. Then I'd REALLY be helping the community!

There is a thread Shell Scripting Topic - there you can ask questions about bash scripts....