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

Some History

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

source file	description	status
game.bas	main module, contains the main game loop and a lot of the on-map player/hero control and NPC logic & AI including collision checks (except wall-checking) and activation (usenpc), doors, textboxes, user menus (MenuDef menus), top-level drawing code (displayall), Debug Menu and some debug menus, initialisation and cleanup including the slice tree, utility routines.	messy, needs splitting
achievements.rbas	General code for achievements, especially loading defintions. Closely related to achievements_runtime.rbas. Linked into Custom but not actually used by it currently.	not messy
achievements_runtime.rbas	Progress and rewarding of achievements, and saving/loading state.	not messy
bmod.rbas	main battle module	messy
bmodsubs.bas	additional battle related stuff such as attack damage. See also bcommon.bas. Also contains some non-battle code for hero levelling/stat growth	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" (still current) script interpreter, including the script debugger. Mainly exists to ease the transition to the new script interpreter. See scripting.bas	messy
pathfinding.bas	Pathfinding. Calls out to game.bas routines to do collision checks	not messy
savegame.rbas	loading and saving games	still messy
scriptcommands.bas	All script commands, including a bunch of functions for error-checking or decoding script arguments, and text embed codes (embedtext)	slightly messy
scripting.bas	Scripting related code mostly not specific to the "old" script interpreter (not completely encapsulated), such as loading/triggering scripts and displaying errors. Script commands are implemented in scriptcommands.bas	quite messy
steam.bas	Code to interface with SteamWorks, the library shipped with Steam games which in turn interfaces with Steam itself	C-interfacing messiness
walkabouts.bas	Most code related to walkabout slices, walkabout slice layers, wall checking, and vehicles. However the hero and NPC collision checking and most other hero/NPC logic is in game.bas	messy
yetmore2.bas	Implementation of live-previewing (Test Game), including communicating with Custom, reloading various data files (also covers map state saving/loading) and the F5 Reloading menu, plus a few other misc things thrown in	somewhat 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

source file	description	status
attackedit.bas	Attack editor. Also contains "flexmenu" implementation, an attempt at a generic editor menu system which is used by the attack and enemy editors. Better than some other editor menus, but mostly a bad idea. Note: attack_chain_browser is in customsubs.rbas instead for some reason	organised chaos
audioedit.bas	The Import Music and Import Sound Effects and Global Music/Sounds menus	somewhat messy
custom.bas	Main module for Custom. Initialisation, main menu, F9 global editor settings menu, many secret test menus	fairly messy
customsubs.rbas	misc editor subs and functions and some editors that should be moved to separate files. Most of this is either new code or decently cleaned up code.	mildly messy mixture
drawing.bas	Contains the sprite editor, the maptile editor, the new spriteset browser and unfinished spriteset and animations editors and some other code. The sprite and maptile editors (together with map editor) are the oldest code in the whole project. Some of it has been partially cleaned up.	messy
editedit.bas	(Not used.) Code for the unfinished Editor Editor (hidden in Custom)	not very messy
editorkit.bas	New system for creating menus and editors with less code	fugue-like complexity
editrunner.bas	(Not used.) Unfinished interpreter for the RELOAD documents produced by the Editor Editor	sparsely messy
enemyedit.bas	Enemy editor. Uses flexmenu. Enemy Usage and Foemap Stats (part of map editor) menus	messy
generaledit.bas	General game data menu (general_data_editor) and most of its submenus. Also vehicle and Master palette editors.	somewhat messy
heroedit.rbas	Hero editor	not very messy
itemedit.bas	Item editor and common_elementals_editor (also used in Hero editor)	somewhat messy
mapsubs.bas	Map editor and related code.	messy and complex
menuedit.bas	"Edit Menus..." menu	not very messy
reloadedit.bas	Contains the RELOAD editor (hidden in Custom)	not very messy
scriptedit.bas	Script Management menu and all submenus including script importing and HSI exporting, and Special Plotscripts menu	somewhat messy
shopedit.bas	Shop editor	somewhat messy
textboxedit.bas	Text box editor	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
custom_udts.bi	Most UDTs used for editor state, like MapEditState. Some like SliceEditState are in better places	potpourri

Shared files

source file	description	status
allmodex.bas	Core graphics, text drawing, BMP reading/writing, animations, sound, and input code. In particular implementation of Frame and Palette16, including drawing routines for boxes, ellipses, dissolve animations, etc (except for what's in blit.c). Includes input-recording-and-playback and handling of some universal controls like F12 for screenshots or Ctrl-F11 for macros. In practice, this is a library on which the rest of the engine is built. Also is 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
audiofile.bas	Utility routines for examining MIDI/MP3/OGG/WAV files or picking the file to play. Mostly used only by Custom	slightly messy
backends.bas	handles loading of the graphics backend (no similar dynamic loading capability for the music backend)	barely messy at all
bcommon.bas	A few battle related functions that are needed by both Custom and Game, such as merging elemental resists.	a bit messy
blit.c	This contains the most CPU-intensive drawing code (for blitting with optional scaling and smoothing), written in C, for 8-bit images only. All the 32-bit blitting code is in surface.cpp	pretty 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
build/globals.bas	Autogenerated by scons. Do not edit.	autogenerated
cmdline.bas	Some of the shared command-line argument processing for Game and Custom (but more exists in many other places)	not very messy
common.rbas	An enormous collection of code that is shared between game and custom, including lots of loading and saving code which ought to be in loading.rbas, helper functions for displaying messages or prompting for input (including simple "multichoice" menus), F1 help menus, and the huge SUB upgrade() for upgrading an .rpg file. This file kind of acts like a higher-level library that sits above allmodex and below Game and Custom. 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.rbas functions, this is linked into utilities OTHER than Game and Custom such as unlump	not messy at all
common_menus.bas	Data editor menus which are shared between Game and Custom, which is currently just bitset menus.	not messy at all
filelayer.cpp	Low-level code implementing OPENFILE, etc, this is an abstraction layer which is used to send file update messages from Custom to Game while live-previewing	not very messy
loading.rbas	code for reading and writing various data files, but a lot of loading/saving code is NOT in here. Often you'll find support for old and new file formats next to each other. Also implementation of a few UDTs, mainly TileMaps and ZoneMaps (because they are intertwined with their loading/saving code)	slightly messy
lumpfile.bas	Code for lumping and unlumping, and the loadrecord/storerecord routines. Also a whole lot of unused unfinished pseudo-OO code for FileLump and LumpedLump which was written before FB had OO and before filelayer.cpp; was intended for run-without-unlumping	fairly messy
menus.bas	Customisable menus (MenuDef), generic menu code (standardmenu, usemenu, etc) used mostly in Custom, and new ModularMenu system	confusing
os_*.*	most of the completely OS-specific code is here (exception: Windows-only private heap code in reload.bas). Both os_unix.c and os_unix2.bas are used by all supported platforms except Windows, and 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
os_unix_wm.c	Unix- and Mac-specific code needed by Game and Custom but not linked into commandline utilities. (The equivalent Windows routines are in os_windows.bas)	not 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	A low-level library of utility functions, mainly for maths, data structures, string manipulation, filename manipulation, and file IO. Contains alternatives to most FB file IO routines, with better error checking (see Developer Notes#File functions). 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 and libraries

source file	description	status
gfx_*.bas	graphics backends. All share the same API. (But see below for gfx_directx, gfx_sdlpp, and gfx_sdl on Mac OS X)	varying messiness
gfx_sdl_common.bas	Code shared between gfx_sdl and gfx_sdl2	not messy
music_*.bas	music backends. All share the same API	varying messiness
music_sdl.bas	Compiles to both music_sdl and music_sdl2, depending on compiler defines!	slighty messy
music_audiere.bas	Audiere-based sound effects implementation shared by music_native and music_native2	somewhat messy
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 a completely different code repository, in our fork of libsdl-android; see Compiling for Android
audwrap\*	C wrapper around the C++ 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_sdlpp	not too messy
gfx_directx\*	C++ DirectX backend. Supports both old and new apis	not too messy
gfx_sdlpp\*	Completely new C++ SDL 1.2 graphics backend, referred to by gfx_sdlpp. Supports both old and new apis. Unfinished; does not work. No plans to finish it, but maybe we'll turn it into an SDL 2 backend instead.	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.bi	"new" graphics backend api proposal. Almost entirely unused, except gfx_Initialize	less messy
lib/gif.h	GIF writing code, including dithering and k-d tree used for nearest-colour matching	barely messy
lib/gif.cpp	Some code which wraps gif.h routines to provide an API for eg quantising (24->8bit) and dithering images	not messy
lib/SDL/*	OS Clipboard read/write routines for each OS. Adapted from SDL2.
lib/*	Other code which is not OHRRPGCE specific, mostly third-party and under other licenses. Such as LodePNG and ujpeg. Some of this is modified/maintained by us, most isn't	someone else's mess
music.bi	music backend api	barely messy
rasterizer.cpp	Unused software polygon rasterization (3D) routines. Not compiled except by "scons raster=1"	a three-dimensional templated mess
surface.cpp	Implements Surfaces, which is both 24/32-bit colour depth support (blitting) and an abstraction layer to eventually allow hardware-accelerated graphics renderin. Also some duplicate 8-bit blitting code, but most of the 8-bit stuff is in blit.c. Frames and Surfaces ought to be merged, with the blitting code going to blit.c	less messy

Other utilities, tools and tests

HamsterSpeak utilities

source file	description	status
hspeak.exw	HSpeak compiler	fractal messiness
hsspiffy.e	Euphoria routines used by HSpeak	barely messy
hspeaktest.py	Runs testgame/parser_tests.hss, checking HSpeak correctly generates errors and warnings. Run with "scons hspeaktest"	not really messy
euphoria/*.e	Routines taken from an unreleased 'unicode' branch of Euphoria, needed for unicode support in HSpeak	not my mess
node_hsint.js	Commandline tool to run HamsterSpeak scripts, based on zzo38's hspeakrt library. Written in node.js.	barely messy at all
physpeak/*	New HamsterSpeak compiler written in Python. Not yet used or complete	somewhat messy

Build system

source file	description	status
bundle-apps.sh	Creates OHRRPGCE-Game.app and OHRRPGCE-Custom.app for Mac OSX	straightforward
codename.txt	The OHRRGPCE version name	couldn't be simpler
distrib*.[sh/bat]	Scripts to package up stable and nightly builds of the OHRRPGCE. Several of these are redundant to each (e.g. to create the same zip from Windows or Unix)	a messy web
linux/*.py	Scripts to generate .deb packages of the engine	barely messy at all
misc/sl_lookup.py	Python script to update hardcoded slice lookup codes throughout the source. You have to run this yourself when necessary.	barely messy at all
ohrbuild.py	Routines used by SCons script for generating ver.txt and that sort of thing	a bit 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
Sconscript	SCons script for compiling the engine. Secretly reimplements all the linking logic of fbc!	a right fair mess
sourceslices/update.sh	Script to regenerate sourceslices.bi. You need to manually run this if you modify sourceslices/*.slice	couldn't be simpler

Other tools and tests

source file	description	status
autotest.py	Tool to checkout and compile the source at multiple svn/git revisions, test an RPG, and compare differences in screenshots	barely messy at all
filetest.bas	Tests for OPENFILE and some of the file handling stuff in util.bas	not too messy
fixqb.bas	A tool for removing certain QuickBasic-isms from source files. Not used in years. (obsolete)	not too 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 (obsolete)	barely messy
misc/with.el	Emacs Lisp script to detect a type of mixed WITH and GOSUB usage bug (obsolete)	barely messy
misc/lumpfix.ex	LUMPFIX (or a reimplementation?), an Euphoria program to attempt to fix damaged lumpfiles. No longer in use (but maybe it's useful?)	barely messy
misc/process_crashreports.py	Utility for analyzing submitted crashrpt crash/bug reports	a little messy
misc/minidump_tools.py	Used by process_crashreports.py. Non-OHRRPGCE-specific routines for producing stacktraces from Windows minidump files	a little messy
rbtest.bas	ReloadBASIC tests	hardly 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
unlump.bas	a standalone tool for packaging lumpfiles	not terribly messy
vectortest.bas	a battery of tests for vectors	barely messy at all
xml2reload.bas	tool for converting an XML file (especially as produced by reload2xml) into a RELOAD document	not too messy

Data files

file	description
data/*	Data files such as images and the ohrrpgce.new template for new .rpg files, packaged with and used by Custom. None of these are used by Game
import/*	Any file here is packaged into complete distributions of the engine
ohrhelp/*.txt	F1 help pages. Ones prefixed with game_, share_ or slice are also used by Game.
sourceslices/*.slice	Slice collections for builtin menus like Status. Directly embedded into Game and Custom. However there are quite a lot of simple slices that are created directly by code, eg textbox slices.
plotscr.hsd, scancode.hsi, whatsnew.txt	Also included in packaged engine builds
vikings/*	Game:Vikings of Midgard included with complete distributions of the engine

Style Inconsistencies

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.

See Also

• Source
• Improving the engine
• Category: OHRRPGCE Development
• Plan for source file cleanup
• Developer Notes