BPPlayer Software Manual

For version 1.06

Index
- What is BPPlayer ........................................................................................page 03
- Terminology ............................................................................................... page 03
- Requirements .............................................................................................. page 04
- Features ...................................................................................................... page 04
- How to convert *.blend files into *.block files .......................................... page 05
- for Windows ................................................................................... page 05
- for Linux ......................................................................................... page 06
- for Mac OSX .................................................................................. page 07
- Custom Players ........................................................................................... page 08
- Config file structure and details ................................................................. page 09
- Encrypting multiple source (Blend) files ................................................... page 15
- BPPlayer license ........................................................................................ page 16
- Release history ........................................................................................... page 16

What is BPPlayer?
The BPPlayer is a stand alone application that allows developers to release content
without the need to release source file(s). The BPPlayer encrypts source files into a new
format known as block files. Basically, BPPlayer acts as middle-ware between the
(encrypted) release content and the application that executes that content. This means
that a secondary application is required to actually run the content. This document will
focus on (and assume) that the secondary application is the BlenderPlayer
(www.blender.org) (although, any application can technically be used).

Terminology
Blend files: source files used by Blender 3D (www.blender.org).
Block files: the native format used by BPPlayer. They are binary files which contain
encrypted game content. At the time of this writing, only BPPlayer is compatible of
reading these files.
Player: in the scope of this document, refers to the application that executes the actual
game content at runtime (and is usually separate from BPPlayer). Usually, this is the
BlenderPlayer (www.blender.org). However, it may also refer to the Gamekit
(http://code.google.com/p/gamekit/), or any application capable of reading blend/source
files. In this document, Player may also be referred to as secondary application.
Static Block/Blend files: These are encrypted (blend) files where the encryption key
does not change. The key is stored inside the block file format. Any program can read
these files assuming that the encryption key is available. Traditionally, these files are
used in cases were a game may have multiple blend files and need to be dynamically
loaded into the player at runtime.
Dynamic Block/Blend files: These are encrypted (blend) files where the encryption key
changes at runtime (the key is determined by BPPlayer). Any program can read these
files assuming that the encryption key is available. Traditionally, these files are used in
cases were a game may have multiple blend files and need to be dynamically loaded into
the player at runtime.
BPPlayerGUI: This is the graphical user interface application that is distributed with
BPPlayer. Its used to convert (encrypt) source content (usually blend files) into block
files. Its located in the ./ blendblockConverter folder.
OS: Stands for Operating System.

Requirements
Windows:
- Requires .NET framework 3.5 or higher to be installed.

Features
The latest version of the BPPlayer supports the following features:
- Secure content (reduces cracking and hacking from static and dynamic analysis).
- Static and dynamic encrypted blend files (encrypt more than one blend file at a time).
- Load any player (devs can choose a custom player when he/she converts a source file).
- BPPlayer supports +256 bit encryption keys (users can change the size of the static
encryption key as long as it's a multiple of 64 bits).
- Mac OSX supported.
- Convert source (blend) files using a GUI.
- Convert source (blend) files using a config file.
- Blend file linking and asset loading (linking/loading external blend files).
- Load ogg and mp3 files in Blender 2.49b games.
- Blend files can be loaded at runtime (optional).
- File Browser available.
- Command line support (run ./BPPlayer -h for more details).
- Linux supported.
- Live CD support (Windows Only).
- Block files support an Internal File System.
- Pack files (block, blend, dll, py, etc) into either block files or a single executable.
- Hide the Blenderplayer Console Window.

How to convert *.blend files into *.block files (for Windows)

Method 1 (recommended):
1) Open the BPPlayerGUI.exe located in the blendblockConverter folder.
2) Open a blend file by going to the bottom right and clicking the Import Main Blend
File button.
3) Select a blend file and click ok.
4) Click the Export Block Name button.
5) Create a new name for the block file and click ok (recommended name is
data.block).
6) Save the config file by going to the top right and clicking Files->Save(Config File).
7) Click the Export button.
8) If you exported the game as a block file, move the block file to the same folder as the
BPPlayer and secondary player (usually blenderplayer).
9) Delete the existing "data.block" file (if it exist).
10) Rename the new block file to "data.block" or "<name of executable>.block" (if you
havent already).
11) If you prefer, you can rename the BPPlayer executable to anything (and BPPlayer
will still be able find the block file as long as it's named "data.block" or "<name of
executable>.block").
Method 2 (requires config file):
1) First, this method requires a config file. Config files can be generated by using the
BPPlayerGUI application.
2) Once you have set the desired setting in the BPPlayerGUI.exe, save a config file by
going to the top left and selecting Files->Save As (Config File)
3) Next, run the config file in the BPPlayer.exe. This can be done by clicking and
dragging the config file onto the BPPlayer executable or by running the command:
./BPPlayer.exe <myConfigFile.txt>
where <myConfigFile.txt> is the name of the config file.
4) BPPlayer will automatically follow the instructions (and setting) in the config file
and generate all the necessary output files (including block files).
Method 3 (limited features, for single blend file only):
This is considered the quick and dirty way to generate block files. To use this method,
open a command prompt and cd into the directory where BPPlayer is located. Then run:
./BPPlayer.exe convert

How to convert *.blend files into *.block files (for Linux)

Method 1 (requires config file):
1) First, this method requires a config file. Config files can be generated by using the
BPPlayerGUI application. If you already have a config file, jump to step 5.
2) To run the BPPlayerGUI application, use Windows or install Wine by running:
1 A) sudo apt-get install wine
2 B) wget http://kegel.com/wine/winetricks
C) sh winetricks corefonts dotnet35
D) sudo apt-get install cabextract
E) winetricks vcrun2005sp1
3) Follow the BPPlayerGUI instruction (method 1) on page 5.
4) Once you have set the desired setting in the BPPlayerGUI.exe, save a config file by
going to the top left and selecting Files->Save As (Config File). From this point
onward, you will not need Windows or Wine.
5) Next, run the config file in the BPPlayer (Linux version). This can be done by
running the command:
./BPPlayer <myConfigFile.txt>
where <myConfigFile.txt> is the name of the config file.
6) BPPlayer will automatically follow the instructions (and setting) in the config file and
generate all the necessary output files (including block files).
Method 2 (limited features, for single blend file only):
This is considered the quick and dirty way to generate block files. To use this method,
open a command prompt and cd into the directory where BPPlayer is located. Then run:
./BPPlayer -convert
for additional help, see the man pages by running:
./BPPlayer -h

How to convert *.blend files into *.block files (for Mac OSX)
Method 1 (requires config file):
1) First, this method requires a config file. Config files can be generated by using the
BPPlayerGUI application. If you already have a config file, jump to step 7.
2) To run the BPPlayerGUI application, use Windows or install Wine.
3) Follow the BPPlayerGUI instruction (method 1) on page 5.
4) Once you have set the desired setting in the BPPlayerGUI.exe, save a config file by
going to the top left and selecting Files->Save As (Config File). From this point
onward, you will not need Windows or Wine.
5) At the time of this writing, BPPlayer releases do not provide patched Blenderplayers
for Mac OSX. This means you will need to patch and compile a Mac OSX
Blenderplayer yourself. The patch file is provided in the root directory of this release
and has the file extension *.patch.
6) Once you have compiled a patched Blenderplayer, open the config file in any text
editor. Replace line
#CustomPlayer = "blenderplayer"
with
CustomPlayer = "<blenderplayer_file_path>"
where <blenderplayer_file_path> is the full file path to the patched Blenderplayer
executable. For more details, see the Custom Player section on page 8.
7) Copy the patched Blenderplayer executable into the ./kdd directory of the BPPlayer
(same directory where the BPPlayer executable is located). Name the patched player
blenderplayer so that the BPPlayer will know where to look for it. If you build a
PowerPC version of the Blenderplayer, name it either blenderplayer or
blenderplayerPPC.
8) Next, run the config file in the BPPlayer (Mac OSX version). This can be done by
running the command:
./BPPlayer <myConfigFile.txt>
where <myConfigFile.txt> is the name of the config file.
9) BPPlayer will automatically follow the instructions (and setting) in the config file and
generate all the necessary output files (including block files).

Custom Players
As mentioned earlier in this document, the BPPlayer usually requires a secondary
application to execute release content (in this case, its usually the Blenderplayer).
During runtime, the BPPlayer will check these applications for modifications. If they
have been modified, the BPPlayer will throw an error and stop. This feature exist to
ensure that the player has not been modified or swapped with a fake player (which
could then be used to extract source content).
By default, BPPlayer contains a library of valid players. However, some projects
may require a specific player which may not be considered valid by BPPlayer. In these
cases, developers should use the Custom Player functionality supported in BPPlayer.
Developers can authorize any player they wish when they generate the main block file as
specified below:
1)
2)
3)
4)
5)

Open a config file in BPPlayerGUI application.

Click the button labeled Custom Player.
Select an executable.
Save the config file and click the Export button.
Dont forget to copy the executable youve selected in the GUI to same directory as
the BPPlayer (and it should be name blenderplayer).

An alternative method is described below:

1) Open a config file in any text editor.
2) Add the line:
CustomPlayer = "<blenderplayer_file_path>"
where <blenderplayer_file_path> is the full file path to the patched Blenderplayer
executable.
3) Next, save the config file and run it in the BPPlayer. This can be done by running the
command:
./BPPlayer <myConfigFile.txt>
where <myConfigFile.txt> is the name of the config file.
4) Dont forget to copy the executable youve selected to same directory as the BPPlayer
(and it should be name blenderplayer).

Config file structure and details

Config files contain setting and information on how to build and encrypt source files.
Usually, they are modified and maintained by the BPPlayerGUI. However, they can also
be modified manually by using any text editor. The syntax of config files are as follows:
<variable> = <value>
<variable> is an object which stores information. <value> is the data that is being
assigned to the object. A real example can be seen below:
BlendFile = "myblend.blend"
In addition, the #CONFIGTAG string must the first line in the config file. Without it,
BPPlayer will not recognize the file as a config file. Comments can be added by putting
an # at the beginning of a new line.

A full list of variables that are recognize by BPPlayer are listed below:
BlendFile
Name of the main blend file to encrypt. Once converted into a block file, this will
be the first file that is executed in the BPPlayer.
Input: any string containing the file path to the main blend file.
Example:
BlendFile = "myblend.blend"
BlockFile
Name of the main block file that will be generated. This is the first file that is
executed in the BPPlayer. This option is ignored if the variable Export_Block is
FALSE.
Input: any string containing the file path to a block file that will be generated.
Example:
BlockFile = "data.block"
RuntimeFile
Name of the executable file that will be generated. All packed content will be
stored in this executable. This option is ignored if the variable Export_Block is
TRUE.
Input: any string containing the file path to an executable that will be generated.

Example:
RuntimeFile = "myGame.exe"
Export_Block
Variable that determines if BPPlayer should generated either a block file or a self
contained executable.
Input: TRUE or FALSE
Example:
Export_Block = TRUE
Export_Runtime_For
BPPlayer supports locking block files to one specific OS platform. If this
feature is enabled, the block file will only run on the OS that is specified. If no
OS is specified, BPPlayer will not restrict block file to any particular OS. By
default, all OSs are supported.
Input: ALL or Windows or Linux or Mac
Example:
Export_Runtime_For = ALL
Processing_Priority
Changes the execution priority during runtime. The default is Normal. Some
versions of BPPlayer will ignore this variable during runtime. (For Windows
only).
Input: Low|Below_Normal|Normal|Above_Normal|High|Real_Time
Example:
Processing_Priority = Normal
Allow_Unpatched_Blenderplayers
The BPPlayer will allow unpatched Blenderplayers to be executed if this is set to
TRUE. Can be used to allow older versions of the Blenderplayer (such as 2.25,
2.42a, 2.48, etc). This is a Windows only feature. The default is FALSE. This
feature is deprecated and should not be enabled.
Input: TRUE or FALSE
Example:
Allow_Unpatched_Blenderplayers = FALSE

StaticEncryptionKey
This is the encryption key that is used to generate static encrypted block files.
The input string must contain only hex values. The string length must be at least
16 characters long. In addition, the string size must be a multiple of 16 characters
(so 16, 32, 64, 128, 256, 512, etc. are valid). If the example below is used, make
sure that value of the key is changed.
Input: Hex string containing the characters 0,1,2,3,4,5,6,7,8,9,A,B,C,D,E,F
Example:
StaticEncryptionKey = 93894AB380FE29C0
Show_Frame_Rate
Input parameter that is specific for the Blenderplayer (at runtime).
Input: TRUE or FALSE
Example:
Show_Frame_Rate = FALSE
Show_Debug_Data
Input parameter that is specific for the Blenderplayer (at runtime).
Input: TRUE or FALSE
Example:
Show_Debug_Data = FALSE
Show_Game_Properties
Input parameter that is specific for the Blenderplayer (at runtime).
Input: TRUE or FALSE
Example:
Show_Game_Properties = FALSE
Enable_Blender_Materials
Input parameter that is specific for the Blenderplayer (at runtime).
Input: TRUE or FALSE
Example:
Enable_Blender_Materials = FALSE
Disable_Mipmaps
Input parameter that is specific for the Blenderplayer (at runtime).

Input: TRUE or FALSE

Example:
Disable_Mipmaps = FALSE
Disable_Audio
Input parameter that is specific for the Blenderplayer (at runtime).
Input: TRUE or FALSE
Example:
Disable_Audio = FALSE
Show_Console_Window
If this is set to FALSE, the BPPlayer will hide the Blenderplayer console
window during runtime. The default is FALSE.
Input: TRUE or FALSE
Example:
Show_Console_Window = FALSE
Retain_Path_When_Unpacked
When the BPPlayer unpacks content to a storage device (during runtime), if this
value is set to TRUE, the BPPlayer will unpack the corresponding files to their
respected (relative) file directories. The relative file paths are determined upon
the location of the BPPlayer executable. If a directory does not exist, BPPlayer
will create it. The default is FALSE. This feature only applies if files are
packed with BPPlayer.
Input: TRUE or FALSE
Example:
Retain_Path_When_Unpacked = TRUE
Keep_Unpacked_Files
Files (that are unpacked at runtime) will not be removed after execution if this
value is set to TRUE. This is useful in cases where one would like to use
BPPlayer as an installer. This features also decreases loading times. The default
is FALSE. This feature only applies if files are packed with BPPlayer.
Input: TRUE or FALSE
Example:
Keep_Unpacked_Files = FALSE

OverWrite_StaticEncrypted_Blends
If this value is set to TRUE, BPPlayer will not add the *.000 extension to
encrypted static blend files. Instead, source files will be overwritten with the
encrypted file. This will destroy the original source files. Do not enable this
feature unless you have made backups of all source files. The default is
FALSE. This feature only applies if you are using static encrypted blend files.
Input: TRUE or FALSE
Example:
OverWrite_StaticEncrypted_Blends = FALSE
CustomPlayer
Add a patched custom player. BPPlayer will allow execution of the executable
that is specified in the file path and record its checksum. For more details see
page 8.
Input: String containing the file path to the patched player
Example:
CustomPlayer = "blenderplayer.exe"
PackFile
Used to pack files into either a block file or an executable. To pack multiple files,
duplicate the example below for each file.
Input: String containing the file path to a file that will be packed.
Example:
PackFile = "PackBlend.txt"
Example (for multiple files):
PackFile = "PackBlendA.txt"
PackFile = "PackBlendB.txt"
EncryptPackFile
Used to encrypt and pack files into either a block file or an executable. These
files can only be read by using the dynamic encryption key. To handle multiple
files, duplicate the example below for each file. This feature is used for
Dynamic Encrypted Block files.
Input: String containing the file path to a file that will be encrypted and packed.
Example:
EncryptPackFile = "packedEncryptedBlend.blend"

EncryptedStaticFile
Used to encrypt files that are not packed. These files can only be read by using
the static encryption key. To handle multiple files, duplicate the example below
for each file. This feature is used for Static Encrypted Block files.
Input: String containing the file path to a file that will be encrypted
Example:
EncryptedStaticFile = "encryptedExternalBlend.blend"

Encrypting Multiple Source (Blend) Files

As of version 1.05, BPPlayer supports encrypting multiple blend files by converting
them into either Static encrypted blend files or Dynamic encrypted blend files. One
difference between these two formats is that dynamic files are packed into the main block
file or executable. Static files are not packed. Generating these formats can be done by:
Static encrypted file using GUI method (recommended)
1) Make a backup copy of all your source (blend) files before continuing (just in-case).
2) Open the BPPlayerGUI application
3) Load a config file (or create a new config file)
4) Click the Encrypt External (Static) Blend File button
5) Select a blend file and click ok
6) You can only select one blend file at a time. Therefore, repeat step 4 until all of the
blend files have been selected. Note: its not necessary to encrypt the main blend file
a second time.
7) Save the config file
8) Click the Export button
9) The BPPlayerGUI will convert each *.blend file selected into *.blend.000 files (in the
same directory as the source files). The files with the *.000 extension are encrypted
and will need to be renamed before they can be used.
10) Move all the .000 files to a new directory (while retaining the file hierarchy) and
remove the *.000 extension.
11) Copy the BPPlayer, the main block file, and all Blenderplayer components to the
same directory.
If done correctly, BPPlayer will be able to load the encrypted blend files at runtime.
Caution: after you rename the *.blend.000 files to *.blend, they will contain the same
names as the source content. Make sure that you do not forget which files are
encrypted and which ones are your source content!
Caution: the static encryption key is stored inside the config file. Make sure you
follow step 7 and store the config file in a safe place. Do not release your encryption
key publicly!
Dynamic encrypted file using GUI method (simpler, but longer loading times)
1) Open the BPPlayerGUI application
2) Load a config file (or create a new config file)
3) Click the Pack and Encrypt (Dynamic) Blend File button
4) Select a blend file and click ok
5) You can only select one blend file at a time. Therefore, repeat step 4 until all of the
blend files have been selected. Note: its not necessary to encrypt the main blend file
a second time.
6) If the source blend files require a file hierarchy, enable the Retain file paths when
unpacked option at the far left of the GUI.

7) Save the config file.

8) Click the Export button.
9) Copy the new block file to the BPPlayer directory.
If done correctly, BPPlayer will be able to load multiple encrypted blend files at runtime.
Note: BPPlayer supports the usage of both static and dynamic encryption running
simultaneously on the same project.

BPPlayer License
The full BPPlayer license can be viewed by running ./BPPlayer -license in a
command prompt. Basically, the license only stresses two points:
1) Do not reverse engineer the BPPlayer
2) You (the developer) keep all rights to the source and output files.
BPPlayer can be used commercially. Giving credit is optional (and is not required).
The software is provided as is, without warranty of any kind, express or implied,
including but not limited to the warranties of merchantability, fitness for a particular
purpose and non infringement. In no event shall the authors or copyright holders be
liable for any claim, damages or other liability, whether in an action of contract, tort or
otherwise, arising from, out of or in connection with the software or the use or other
dealings in the software.

Release History
Version 1.06 improvements and features:
- Includes documentation and manual
- fixed memory leak in blenderplayer
- fixed lib dependency issue(s) with patched Linux blenderplayer
- fixed booting bug on Mac OSX 10.7 and 10.8
- fixed file path bug on Mac OSX.
- More options when converting/generating block files.
- Heavily improved block converter (easier to convert large projects with many blend
files).
- You may now pack entire folder hierarchies.
- Files will retain their file hierarchy when they are unpacked.
Version 1.05 improvements and features:

- static and dynamic encrypted blend files (encrypt more than one blend file at a time).
- load any blenderplayer (the user can choose a game player when he/she converts a
blend file)
- BPPlayer now supports +256 bit encryption (users can change the size of the static
encryption key as long as it's a multiple of 64 bits).
- optimization with the internal file system.
- heavily updated blenderplayer patch.
- Mac OSX support.
Version 1.04 improvements and features:
- convert blend files using a GUI
- convert blend files using a config file
- improved security
- asset loading (linking/loading external blend files) is fixed
- load ogg and mp3 files in 2.49b games.
- improved Linux port
- bug fixes
Version 1.03 improvements and features:
- Block and Blend files can be loaded at runtime.
- File Browser available
- New command lines
- Admin rights are no longer required (new boot method)
- Optimized encryption format for 10X faster loading (load 1 GB block files in 10
seconds).
- Live CD support (Windows Only)
- New Internal File System Feature
- Pack any file you want (block, blend, dll, py, etc).
- Files can be packed into the exe file, an external file, or the block file itself.
- Linux Port
- Converting blend files to block files is a bit easier.
- Source code has been rewritten.
- Blend file linking (with special patched blenderplayers only)
Version 1.02 improvements and features:
- First Stable release.
- Game Protection = this feature allows you release your Blender games without having
to release the blend file. Basically, this feature locks (encrypts) your blend files into a
new format known as a block file. It provides heavy protection but is still efficient at
running games.
- DLL Packing = this feature packs all the dll's into one nice file.
- Block Packing = this works similar to how blender packs a blend file with the
BlenderPlayer. Except, this packs the block file with the BPPlayer. You may still keep
block file separate from the BPPlayer if you want. It's up to you.

- Set the Processing Priority = this allows you to decrease (or increase) the overhead by
adjusting the processing priority (Windows only).
- Hide Console Window = this hides the console window while the game runs.
Version 1.01 improvements and features:
- Alpha build
- Bug fixes
Version 1.00 improvements and features:
- Alpha build
- First Public release