Guide to source files
This page attempts to document the many and confusing source files in the OHRRPGCE. This information is all subject to change, and will almost certainly change faster than this wiki page gets updated. If you spot anything that doesn't make sense, please mention it on the talk page. See Improving the engine for more help.
The OHRRPGCE is written mostly in FreeBasic, or the RELOADBasic domain specific language which is preprocessed to FB, with significant amounts of C and C++ (and some Objective-C) at low levels including backends. The HSpeak compiler is written in Euphoria. The build system uses SConscript (Python), and there's lots of other Python scripts, as well as shell scripts, Emacs Lisp, gdb scripts, and of course HamsterSpeak.
To understand how the OHRRPGCE continues to live and grow in spite of its remarkable level of chaos, read: BIG BALL OF MUD software architectures
Contents
Some History[edit]
Some of these source files are logically organized, for example the backends are pretty well organized, and so are many of the shared source files. Other files are completely arbitrary collections of subs and functions, for example, moresubs.bas, yetmore.bas, and yetmore2.bas are meaningless collections. These files hearken back to the bad old days when the OHRRPGCE was a DOS program written in QuickBasic, QuickBasic has a limit on the maximum size of a single source file. If any one file is too big, the compiler just freaks out and dies. To work around this problem, James created new files, and clumsily and messily converted GOSUB blocks into SUBs and FUNCTIONs so they could be moved to the other files. (The reasons why he was using GOSUB in the first place when he could have been using SUB all along hearken back to when he was 15, so cut him some slack ;)
Game Player[edit]
| source file | description | status |
|---|---|---|
| game.bas | main module, contains the main game loop and a lot of the map and walkabout logic. A lot of script command implementations (unnecessarily) live here. (Historically these commands needed to call toplevel GOSUBS in game.bas) | messy |
| bmod.rbas | main battle module | messy |
| bmodsubs.bas | additional battle related stuff such as attack damage | somewhat messy |
| menustuf.rbas | mostly stuff related to the built-in in-game menus | messy |
| moresubs.rbas | misc unsorted stuff including a number of built-in menus | messy |
| oldhsinterpreter.bas | contains the most of the old script interpreter. Mainly exists to ease the transition to the new script interpreter. See scripting.bas | messy |
| savegame.rbas | loading and saving games | still messy |
| scripting.bas | scripting related code mostly not specific to the old script interpreter (not completely encapsulated). Script commands are implemented in game.bas and yetmore.bas | quite messy |
| yetmore.bas | used to be misc unsorted, but now mostly contains plotscripting command implementations | slightly messy |
| yetmore2.bas | most of the rest of the map and walkabout logic and drawing code. Most of the implementation of live-previewing | messy |
| battle_udts.bi | defines types used by the battle system. | not too messy |
| game_udts.bi | defines types used by the game player (but most are actually in udts.bi). These types are good for code cleanup, but it would make more sense to keep them together with the code that uses them (after the code that uses them gets cleaned up). | not too messy |
| gglobals.bi | global variable declarations for the game player | not too messy |
Custom Editor[edit]
| source file | description | status |
|---|---|---|
| custom.bas | Main module for Custom (top level stuff), Shop editor, secret test menus | fairly messy |
| customsubs.rbas | misc editor subs and functions. Most of these are either new code or decently cleaned up code. | mildly messy |
| drawing.bas | contains the sprite editor, the maptile editor, and some other code. The graphics editors are some of the oldest code in the whole project. Some of it has been partially cleaned up. | messy |
| editedit.bas | code for the Editor Editor (hidden in Custom) | not very messy |
| editrunner.bas | interpreter for the RELOAD documents produced by the Editor Editor | sparsely messy |
| flexmenu.bas | Attack editor and Menu editor. Contains an attempt at a generic editor menu system which is used by the attack editor and the enemy editor. Better than some other editor menus, but mostly a bad idea | pretty messy |
| mapsubs.bas | Map editor and related code. | messy |
| menus.bas | Customisable menus and other generic menu code (used mostly in Custom) | somewhat messy |
| reloadedit.bas | contains the RELOAD editor (hidden in Custom) | not very messy |
| subs.rbas | includes the enemy editor, hero editor, item editor, and stuff | messy |
| subs2.bas | text box editor and HSI exporter | messy |
| subs4.bas | misc stuff, including some sound effect editor code and the general game data menu | somewhat messy |
| custom_udts.bi | defines types used by various editors. They types themselves are pretty good, but really belong together with the editors that use them (after those editors get cleaned up) | not too messy |
| cglobals.bi | global variable declarations for the game editor | not too messy |
[edit]
| source file | description | status |
|---|---|---|
| allmodex.bas | Core graphics, sound, input. In practice, this is a library on which the rest of the engine is built. Also an abstraction layer on top of the graphics and music backends APIs. This module gets its name from Brian Fisher's Allmodex Assembly library for QuickBasic, but it has evolved so much that it is a whole new animal now. | mostly not messy |
| array.c | C implementation of vectors; resizable arrays as an alternative to FreeBASIC arrays | not very messy |
| backends.bas | handles loading of the graphics backend (no similar dynamic loading capability for the music backend) | barely messy at all |
| blit.c | this contains the most CPU-intensive drawing code, written in C | barely messy |
| browse.bas | The file-browser used for picking the RPG file to play, or for importing stuff into editors. Although messy and complicated, it is pretty well modular. | messy |
| bam2mid.bas | tool to convert bam files into midi files (can also be compiled a s a standalone tool) | not too messy |
| common.rbas | An eclectic collection of code that is shared between game and custom, including lots of loading and saving code. In spite of the eclecticness, most of the code is pretty decent. | not too messy |
| common_base.bas | Alternative non-graphical implementations of some common.bas functions, this is linked into utilities OTHER than Game and Custom | not messy at all |
| filelayer.cpp | Low-level hook for every file OPEN call from FB, this adds an abstraction layer which is used to send file update messages from Custom to Game while live-previewing | somewhat messy and hacky |
| loading.rbas | code for reading and writing various data files. | slightly messy |
| lumpfile.bas | code for reading and writing lumpfiles. Most of this is not used yet | not very messy |
| misc.bas | Originally contained code to ease the transition from QuickBasic to FreeBasic, now also includes command-line processing and a few Linux/Windows compatibility things | somewhat messy |
| os_*.* | most of the completely OS-specific code is here (exception: Windows-only private heap code in reload.bas). os_unix.bas is used by all supported platforms except Windows (and is currently just a bunch of stubs anyway). Both os_windows.bas and os_windows2.c are used on Windows (some things are easier in one language than the other) | barely messy at all |
| reload.bas | code for reading and writing and manipulating files in RELOAD format | barely messy at all |
| reloadext.bas | more functions for RELOAD documents which don't depend on reload.bas internals | barely messy at all |
| sliceedit.bas | contains the slice collection editor | not very messy |
| slices.bas | code for displaying, saving, loading, manipulating slice trees | not very messy |
| util.bas | misc utility functions, data structures, string manipulation. Everything here is non-interactive code with minimal side-effects. | not very messy |
| config.bi | not a normal header file; secret location of several important macros. Included in every .bas file. | fairly messy |
| udts.bi | location of most Types/User Defined Class definitions, many of which are only used by the game player so should probably be in game_udts.bi | fairly messy |
| util.bi | as well as function declarations for util.bas, contains macros for template emulation (which you probably don't want to touch) and linked lists | #MACRO mess |
| vector.bas | Some additional vectors support functions and type information tables which are best written in FB | not very messay |
Backend Modules[edit]
| source file | description | status |
|---|---|---|
| gfx_*.bas | graphics backends. All share the same api. (But see below for gfx_directx, gfx_sdl++, and gfx_sdl on Mac OS X) | varying messiness |
| music_*.bas | music backends. All share the same api | varying messiness |
| sdl_lumprwops.bas | A wrapper between SDL and lumpfile.bas, to be used by the music_sdl backend for direct lump access. Not used yet | barely messy |
| android\* | A couple files related to Android. In fact most Android-specific code lives in our fork of libsdl-android; see Compiling for Android | |
| audwrap\* | C++ wrapper around the Audiere sound and music library. Needed by music_native/native2, which can't interface with C++ classes | barely messy at all |
| gfx_common\* | C++ code common to gfx_directx and gfx_sdl++ | not too messy |
| gfx_directx\* | C++ DirectX backend. Supports both old and new apis | not too messy |
| gfx_sdl\* | completely new C++ SDL graphics backend, referred to by gfx_sdl++. Supports both old and new apis. Experimental | not too messy |
| mac\SDLmain.m | Objective-C portion of gfx_sdl, used on Mac OS X only. Derived from the standard SDL template. Cocoa code lives here. | somewhat messy |
| gfx.bi | current graphics backend api | messy |
| gfx_new.* | new graphics backend api proposal | less messy |
| gfx_newRenderPlan.* | As-yet mostly unused routines for 24-bit colour depth support (replacing parts of allmodex.bas) | less messy |
| music.bi | music backend api | barely messy |
| rasterizer.cpp | Unused software rasterization (3D) routines | slightly messy |
Separate utilities, tools and tests[edit]
| source file | description | status |
|---|---|---|
| autotest.py | Tool to checkout and compile the source at multiple svn/git revisions, test an RPG, and compare differences | barely messy at all |
| fixqb.bas | A tool for removing certain QuickBasic-isms from source files. Not used in years | not too messy |
| hspeak.exw | HSpeak compiler | somewhat messy |
| hsspiffy.e | Euphoria routines used by HSpeak | barely messy |
| miditest.bas | A tool for testing midi output on Windows (do we still need this one?) | not too messy |
| misc/gosub.el | Emacs Lisp script to detect a type of GOSUB usage bug | barely messy |
| misc/with.el | Emacs Lisp script to detect a type of mixed WITH and GOSUB usage bug | barely messy |
| misc/lumpfix.ex | Euphoria program to attempt to fix damaged lumpfiles (dead code?) | barely messy |
| misc/sl_lookup.py | Python script to update hardcoded slice lookup codes throughout the source | barely messy at all |
| ohrbuild.py | Python rewrite of verprint, used by SCons script | barely messy at all |
| rbtest.bas | ReloadBASIC tests | hardly messy |
| reloadbasic/reloadbasic.py | The ReloadBasic to FreeBASIC preprocessor | pretty messy |
| reloadbasic/pyPEG.py | A fork of pyPEG version 1.4 which adds several features and improvements. pyPEG 2.x has since been released, with diverging changes | slightly messy |
| reloadbasic/xmlast.py | pyPEG-related debugging functions | slightly messy |
| reloadtest.bas | a battery of tests for reload.bas | barely messy at all |
| reloadutil.bas | RELOAD load/save benchmark, and file compare | barely messy at all |
| reload2xml.bas | dump RELOAD to XML | barely messy at all |
| relump.bas | a standalone tool for extracting lumpfiles | not terribly messy |
| Sconscript | SCons script for compiling the engine | a fair mess |
| unlump.bas | a standalone tool for packaging lumpfiles | not terribly messy |
| vectortest.bas | a battery of tests for vectors | barely messy at all |
| verprint.bas | Obsolete, used as part of the pre-SCons build system for updating version numbers. | messyish |
| xml2reload.bas | tool for converting an XML file (especially as produced by reload2xml) into a RELOAD document | not too messy |
Style Inconsistencies[edit]
Different files use different styles. This is mostly okay, and we try to just keep new code consistent with the style of other code in the same module. Some modules break this rule worse than others do.
Some code uses tab indentation. Some code uses single-space indentation, and some uses double-space indentation. Adapting one's indentation style to the match the current file is not much work, and seems like less work than fighting the holy war of deciding which style to standardize on.
Some code puts all FreeBasic commands IN BLOCK CAPS. This is mostly James's fault because the QuickBasic editor drilled it into his brain so hard by automatically enforcing this style. Builtin type names (eg. integer, string) are always lowercase.
Some code uses CamelCaseCaps for sub and function names. Some code uses lower_case_words_with_underscores. James thinks this is probably not a big deal.
There is just one style that is used consistently throughout the source - even the C++ source! - non-builtin type/class names are in CamelCase. Please don't take away all we have!
As a general rule, just try to match the style of surrounding code. For larger style cleanups, discuss first with the other Developers.
