OPL2 source code

This document is for programmers who wish to modify the OPL2 sourcecode, not for those who want to write Python or C++ mods.

OPL2 uses the Panda3D library. Panda3D is an open-source game engine with full Python support. http://www.panda3d.org/
Panda3D has official wrappers for many 3rd party libraries like OpenAL, FMOD, ODE, Bullet, PhysX, libRocket, etc.

OPL2 is completely written in Python. There are C++ versions of some performance-critical functions, which are only used when available (running on the same CPU architecture, same OS the module was compiled for). So you should be able to run OPL2 on any platform which Panda3D runs on, even though you might experience slowdowns because the pure Python versions of the functions are used, if we haven't compiled the module for that platform.

OPL2's sourcecode is pretty small: it consists of 12 Python modules and 2 “faster version” C++ modules.

main.py

Main script. Runs the GUI Launcher or directly starts the game (by importing “opl2.py”) depending if the launcher is enabled or not in the configuration file (“opl2_data/config.txt”).

Launcher.py

Creates a launcher where you can configure some settings like window resolution and then starts the game (imports “opl2.py”).

opl2.py

Creates the Panda3D window and some default Panda objects (imports “DirectStart” module, which creates an instance of “ShowBase”), creates default PL2 stuff (instance of PL2Base, assigns functions from “PL2Functions.py” to the PL2 *.txt script commands) and starts the interpreter by telling it to run “script.txt” from the archives.

cRand.py

cRand is a reimplementation of C's random number generator, which is used by the game to encrypt and decrypt *.dat files, which are used for saving characters and game progress.

pyparsing.py

A 3rd party open source parser library-module, used for parsing PL2's *.txt scripts.

AddonListGenerator.py

Provides functions for scanning the game's “add-ons” folder for add-ons, extracting the “attribute” files from the add-ons, parsing them and generating Python dictionaries which are used in the game by PL2 scripts and the “ClothingSelectionScreen” class.
Used by the PL2Base class.

PL2Loader.py

A class for loading PL2's native file formats (PL2, TMB, TSB, TCM, BIN, PSD). Similar to Panda3D's Loader class. The functions accept file paths or data strings.
An instance is created in the PL2Base class (like an instance of “Loader” is created when you make an instance of Panda3D's “Loader” class, for example by importing “DirectStart”),

PL2Interpreter.py

A parser/interpreter for PL2's TXT scripts. Parser uses the “pyparsing.py” library-module. Interpreter implemented as a Panda3D “Task” object.

PL2Functions.py

A module containing all the Python functions which correspond to PL2 TXT commands.
Can be called directly from Python code or assigned to the PL2 *.txt script commands by using the “commandsDict” dictionary of the PL2Interpreter class.

PL2Base.py

Similar to Panda3D's ShowBase. Sets up some default objects and functions used by other modules (creates instances of PL2Loader, PL2Interpreter, CameraManager and cRand).

ClothingSelectionScreen.py

The Clothing Selection Screen from PL2 which is usually accessed with the “%Z” command.

CameraManager.py

Provides camera controls very similar to the original game.
An instance is created in the PL2Base class.

cDecompressPL2.pyd

Contains faster C++ version of the function “_decompressPL2” from the PL2loader class. Used for decompressing LZSS compressed *.pl2 files.

cPsd.pyd

Contains faster C++ versions of the functions “_mold” and “_decompressRLE” from the “PL2Loader” class. Used for decompressing RLE compressed *.psd image layers and rearranging pixel data.

(note: wanted to create a table, but Sourceforge sucks at rendering tables)

There is an automatically generated html documentation of the sourcecode, generated with Doxygen, which can be found in the folder “engine/src/doc” (or “src/doc” for the sourcecode distribution).

Notes for people working with the source:

• If you want to add C++ features to the game, please make sure it's not something you could contribute to the Panda3D engine's code instead. Like if you want to add a new popular format like Collada to the game with C++, consider adding them to Panda3D's Loader class, code contributions to the engine are always welcome. And by adding it to the engine, you do not need to recompile your own version of the engine every time a new version is out.
• If you want to port some functions or whole modules to C++ to improve speed, do it like the C++ modules which come with OPL2: write code in the appropriate place to try to import the C++ version of the module and if failed, try to import the Python version, this way you won't break the cross-platform nature of OPL2.
• If you want to add new features, note that we will likely not add it to the official release, because the official release is meant to look and feel identical to the original game. You have two options: either make an add-on/mod for the official OPL2 releases, or distribute your own version of OPL2 if your feature is not possible to be implemented as an add-on/mod.

Folder structure

Binary version of OPL2 comes as an archive. The archive contains the following folders:

engine/
add-ons/
opl2_data/

add-ons folder is empty, copy your files from the original game here.
engine folder contains these subfolders:

/panda3d/
/game/

panda3d contains the Panda3D engine (which includes a full copy of Python).
game contains OPL2's sourcecode and html docs.

“opl2_data” contains the game's configuration file, cache folder and add-ons folder where your Python/C++ add-ons/mods are placed.

panda3d contains the following subfolders:

/bin/
/etc/
/direct/    
/pandac/
/python/

All these folders should be known to you as a Pana3D user.
If you want to use your own version of Panda3D, you'll need to copy the folders from the SDK like this.

Please use the Panda3D docs and forum for Panda3D questions. Same goes to general Python/C++ questions, use Google.