Documente Academic
Documente Profesional
Documente Cultură
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 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)
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).
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"
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