This is a build of the Eldritch source code released by David Pittman that has been modified to support modding more easily. Thanks, David, for releasing the source code to your game, and for being very helpful with this project! You need the original game to use this, which you can get from
The original source code is available from the bottom of this page:
This build has been created by Gunnar Zötl (email@example.com). Everything I made is covered by the same license as the original Eldritch source code.
This version of Eldritch has been tested with the humble version of Eldritch on Windows 7, Linux (XUbuntu 16.04 and 17.10) and MacOSX Yosemite. It has also been tested with the windows steam version of Eldritch on Windows 7.
Major changes to the original Eldritch source are:
- unified build system (Makefiles & gcc) on all 3 platforms
- ported editor and all tools (except for the ContentSyncer) to Mac and Linux
- revised loader for game assets, for easy overriding of game assets in mods
- revised config file loader, with a similar purpose
- changed a few editor key bindings from the original, since they clashed with stuff on Linux or Mac. Also, made a few other keys available in the game, like Quicksave/load (using the latter will leave a mark on your game screen, though ;) )
- screenshots working on all platforms
- made all spawners that make sense available in the editor
- made a subtool to choose the theme for your room from within the editor
- an entry point to mods having new worlds within the game
- added PNG loading for textures
- a preview mode for the editor
- limited scripting using the lua scripting language
- and a load of smaller things to facilitate the above
- provided example mods, and something resembling the beginnings of a documentation
- added support for steam content. Thanks go to David for providing the source code for some missing components and allowing me to distribute them with mEldritch under the same license as the rest of the Eldritch source code!
There is no “real” documentation yet, assorted notes follow.
You may want to install mEldritch into a copy of the original Eldritch game folder, as save files and stuff may not be interchangeable between Eldritch and mEldritch.
Linux / Windows
mEldritch binary and the
Mods folder from the archive into your
Eldritch game folder. The
Examples Folder contains a few sample mods. You
can install any of those, if you like. They all have a readme inside that
explains what each mod does. In order to install a mod, just copy it into
Mods folder and add it to
mEldritch(.exe) instead of
or resurrect to generate a new, mEldritch compatible world.
A Note for the steam version
mEldritch works with the steam version of Eldritch, and provides support for the steam exclusive content (Halloween and Asylum). However, there is no support for steam itself.
First, open (not run, but “show contents” or whatever that is called in
Eldritch.app (or better yet, a copy of it). From the Archive,
copy the folders
be sure to merge them with the existing folders!
If you want to open mEldritch on starting Eldritch.app, do this: open
Eldritch.app/Contents/Info.plist in a text editor and replace the string
for the key
mEldritch (should be
replacing). Otherwise you can just navigate to
and start mEldritch from there.
Mods folder must be copied from the archive to
~/Library/Application Support/Eldritch. The
Examples Folder contains a
few sample mods. In order to install a mod, just copy it into the
folder and add it to
The Extras Folder
The tool executables (see below) are in the Extras folder. They don’t need to be in a special place. The tools.cfg is for the mMeshCompiler, you will probably want to put it into your project. Also in the Extras folder is:
ExamplesFolder, which currently only has a template mod and a few examples.
Raw/Roomsfolder which has some of the original Eldritch room files that have been modified for mEldritch
Raw/Configfolder, which has some of the original Eldritch Config files that have been modified for mEldritch
Raw/Fontsfolder, which has the freesans10 truetype font and description needed to make the replacement font for the level editor
Toolsfolder, which is the original Tools folder as distributed with Eldritch’s source code. In here, you’ll also find xmlmeshexport.py, which is Davids plugin for Blender 2.4x to export data in a format mMeshCompiler can understand, and EldritchXMLMeshExporter.py, which is my port of Davids plugin to Blender 2.6x and probably later.
a mod is stored in a directory beneath
Mods, with a file named
inside it. See the template mod in the
Examples folder. Active mods are
Mods/mods.cfg. A mod is only loaded if it is added there.
Config files are loaded like this:
- first load the compiled config file from the cpk file in
- then load the uncompiled file from there
- then load the compiled config file from the Config dir in
- then load the uncompiled file from there
- then for the first mod
Mods/mods.cfgload mod.config, and for all config files listed therein do the above steps in the mods' dir
- for the second and all following mods listed in
Mods/mods.cfgdo the same
all config files found with this method are loaded, not just the first one found. This allows for easy modifications of config files without having to copy the whole thing. But note: in mods only the config files listed in mod.config are loaded!
Resources are loaded like this:
- first check whether the resource filename begins with a ‘&’ char, and if so, evaluate the rest of the name as a lua function that returns a stream from which the resource will be loaded.
- then try the filesystem in the last mod listed in
- then try the cpk files fromn the last mod listed in
- then the same for the second-but-last file, and so on backwards until the first mod.
- then try the filesystem in
- finally try the cpk files in
The first resource file found for a given filename is loaded. This allows to easily override resources without having to create an entire config structure just to change a font or whatever. But it also means that you will have to choose unique names for your module specific resource files, because later mods might override them.
Beware: the Eldritch engine is very picky with errors in config files. Things like files that are not available on load or other stuff are more often than not the cause of a crash!
mEldritch also supports limited scripting capabilities using the lua scripting language. Details about this are available in the separate readme_lua.txt file.
A world is what you see as a level in Eldritch. It is made up of 4x4x3 rooms. The rooms are placed along an X, Y and Z axis where
- X runs from 0 to 3 where 0 is west and 3 is east
- Y runs from 0 to 3 where 0 is south and 3 is north
- Z runs from 0 to 2 where 0 is bottom and 2 is top
You can place rooms or restrict the placement of rooms with in the world by using the Slice[XYZ]* set of config variables.
A room is stored in a directory and with a filename following this pattern:
Only the format of the room is mandatory, everything else can be changed.
Room themes and exits are determined from the room’s filename.
the rooms' theme,
[exits] holds the exits, which are any combination of n,
s, w, e, d and u, and an optional version number for multiple rooms with the
same combination of exits.
[stuff] may be anything, it is not parsed. It
could for example be your mod name and/or a special room name. The mod name
would help to make the level names unique. [version] is just a number, so
that if you have multiple rooms with a specific combination of themes and
exits that the world generator can choose from, they can all have the same
name and distinguish them by their version number.
A theme is not the same as the world the room was created in. It is a theme within that world, like, all rooms in Dagon world that have ruins in them. The world generator uses this information to generate more rooms of one theme adjacent to another one. For more details on this see David’s talk about procedural level generation in Eldritch, here:
or the slides here:
You can enter the room editor from within the game by using the Tab key. The transparent box in the middle of the screen is the brush. It can be used to fill areas. Use the keys listed below to manipulate the brush. The green line in the brush points north.
The room editor has a preview mode for created rooms. Upon entering the preview mode, the previewed room (the one currently being edited) is saved to a temporary file to disc. If it has not been saved before, a save file dialog will pop up, because for the preview to work we need the level’s filename. It is important that you provide a proper name for the room, including exits, as this is what the preview mode uses to place the player spawn point. See section Rooms above for details on the file name pattern for rooms.
You will spawn into preview mode facing one of the previewed rooms' exits. The horizontal exits (n, s, w, e) are preferred, if available, but if the room only has vertical exits, you will spawn so that you can access them.
When entering the preview mode, all entities (including any AIs) are spawned there. You can die in preview mode, and if you do, the game resurrects you in the library. You will then have to reopen the room editor to continue working on your room. This also works if the room editor crashes upon entering preview mode. Upon restarting the game, when opening the room editor, you will be back to your edited room.
You can leave the preview mode and return to the room editor by using the Tab key. Pressing Tab in the room editor brings you back to where you were in the game.
Prefix S- means left shift, C- left control and A- left alt key, this is on a US keyboard. ML, MM and MR are the left, middle and right mouse buttons respectively, MW is the mouse wheel.
F1: next sub tool S-F1: prev sub tool F2: toggle sub tool Voxelset F3: toggle sub tool Palette F4: toggle sub tool Spawners W/A/S/D move camera Q/E move camera up/down S-move fast move Tab leave editor / return from preview mode C-S quicksave F5 save F6 load C-P preview F7 clear A-F7 clear with floor F8 fill A-F8 clear with shell ML place C-ML replace MR delete S-MR pick voxel from room for drawing C-MR add voxel from room to drawing palette MM move brush S-MM expand brush C-MM move brush to contain voxel C-S-MM expand brush to contain voxel R place spawner S-R remove spawner C-R rotate spawner C-A maximize brush C-D reset brush F/Enter fill brush S-F/Enter erase brush K move brush west S-K expand brush west C-K shrink brush west L move brush east S-L expand brush east C-L shrink brush east I move brush north S-I expand brush north C-I shrink brush north O move brush south S-O expand brush south C-O shrink brush south , move brush down S-, expand brush down C-, shrink brush down . move brush up S-. expand brush up C-. shrink brush up C-S-S screenshot H toggle help
In the Palette tool:
ML select voxel for drawing S-ML add voxel to drawing palette
In the Voxelset and Spawner tools:
ML select spawner
many of these also work in the normal game
W/A/S/D move Q/E lean left/right C toggle crouch Space jump / climb lShift run F use / pick up Z drop X switch weapons MW switch weapons ML attack MR use power Escape pause A-F4 exit F5 quicksave F6 quickload (using this will mark you as a cheater) A-Enter toggle fullscreen C-T proxy return to hub (new worlds, same hub), like Return to Library. C-S-T full restart (new hub), like Resurrect. Tab enter room editor C-S-S screenshot C-H hide HUD C-S-H hide HUD and hands. Note that if you save while this is in effect, the hands will be invisible after loading. If that happens, press S-H to show them. S-H show HUD and hands Backspace generate world creation stats. This simulates the generation of the current world 10000 times and generates a file named worldgen-stats.txt which lists every room used in those 10000 runs along with the nuber of times it was generated. This can be used to determine the number of rooms for each configuration that should be created in order to achieve some variety.
In menus or dialogs:
Enter accept Escape cancel ML select Left, Right, Up, Down what the name suggests
Syntax (from configparser.cpp):
#begins a comment
!#indicate the start and end of block comments
@declares a new macro
@@inserts the current macro in the name
&declares a counter (for RHS value) or preincrements and inserts the counter (for LHS name)
^inserts the counter (for LHS name) without incrementing
?retrieves the previous value for a counter (for RHS value) (new in mEldritch, does not work in compiled config files!)
A Macro basically serves as an array. This:
numbla=& @bla @@&=... @@&=...
creates and fills an array.
numbla will contain number if items later.
@bla declares a macro,
@@ later retrieves the value of the current macro.
numbla=& declares a counter, initializing it to 0.
@@& retrieves the value
of the curremt macro, and preincrements and retrieves the current counter,
so the above example declares variables
Counters are not bound to the arrays
New in mEldritch:
retrieves the current value for
numbla from the environment (a.k.a previous
config files or a previous use in the same config file) and makes it the
current value for subsequent references to
^. Also writes back the
final value of this counter to numbla. This is intended to append things
to “arrays”. Beware: Only works in uncompiled config files!
Config vars may be grouped into contexts, a context is created by a word in brackets:
All vars after that are created in that context, until the next context
definition appears. You can go back to the root context by using
Contexts don’t nest, there is only one level of contexts. The root context
is also a context (with the name “”), so things defined there don’t clash
with context names.
config vars are parsed into a hash structure, vars with same name in the same context override each other. This is also true if they are defined in separate config files.
Beware: You should always end your config files in a newline, otherwise the last value (if it consists of just a single char) might not be read.
In a mod, you should not replace an entire config file with your own stuff, unless there is good reason to do so. Otherwise you might break things for other mods loaded after yours.
Some important config files
- lists of rooms for the world generator. Rooms for a specific world have to be appended to the rooms list for a specific context. Check here for context names.
- defines the spawners for objects and AIs used in the game.
- settings for the editor, amongst other things makes those spawners defined in spawners.config available to the editor.
- everything that lives or lies around in the world. If it’s not a voxel, you can find it here.
- the behaviour trees for AI entities.
There’s a lot more, explore and document your findings.
You can create new objects in blender, an example mod that does that comes with mEldritch. See the section on mMeshCompiler below for the necessary tools.
The tools are mostly just the original versions, some with minor changes to get them running cross-platform. The only tool that has received more work is the FontCompiler, which was completely dependent on windows font rendering, and David’s monitor size…
the m prefix is just there to not clash with David’s original versions of the FontGenerator and ConfigCompiler, which are present in the original source archive. And also because the moddable Eldritch build is called mEldritch.
mChecksum <file> [-s]
Computes a checksum for
mConfigCompiler <infile.config> <outfile.ccf>
Compiles config file <infile.config> to a binary format and writes that to <outfile.ccf>.
mConfigDecompiler [-n names] [-s sequences] <infile.ccf> <outfile.config>
Decompiles a compiled config file back to its text form and writes that to <outfile.config>. names is a list of names to read before beginning decompilation, default is names.txt in the current directory. sequences is a list of sequence patterns, default is sequences.txt in the current directory.
Note that if a name can not be decompiled, a name of the form XXXXXXXX will be used, with the X-es being hex digits.
mEldritchLua [-i] file.lua ...
runs a lua interpreter that has some support for eldritch features, such as support for mEldritch’s configuration, textures, rooms, streams. Check readme_lua.txt for more information.
mFilePacker <infile> <packfile.cpk> [-c]
mFilePacker -u <packfile.cpk>
unpacks the entire contents of <packfile.cpk>
mFilePacker -l <packfile>
lists the contents of <packfile.cpk>
For an example of how to use this, you can look at Projects/Eldritch/Makefile in the mEldritch source archive, which uses mFilePacker to build meldritch.cpk.
mFontGenerator <infile.font> <outfontfile.fnp> <outimagefile.tga> [<runtimeimagepath>]
generates a fnp file and an image file from a font description in <infile.font> and a TrueType font file (which is specified in <infile.font>). You can optionally specify the runtime image path for the font, which is relative to the Mod or Eldritch dir, normally “Textures/Fonts”. If you don’t specify it, the path of <outimagefile.tga> will be used for the runtime path. Note that the <outimagefile.tga> is basically a pattern which will be modified with the locale name and stuff.
Currently the FontGenerator can only generate anti-aliased fonts.
For an example of how to use this, you can look at Projects/Eldritch/Makefile which uses mFontGenerator to create the room editor font.
MeshCompiler [-c tools.cfg] [-l] <inmesh.xml> <outmesh.cms>
compiles a mesh in xml format to a mesh in cms format that the Eldritch engine can use. -l specifies long indices, else shorts are used. -c specifies the tools.cfg file to use, default is tools.cg in the current directory. The mesh in xml format is created by an exporter for blender that can be found in the Extras/Tools directory. David used blender 2.49b, so his exporter was written for that. I have made a port of the exporter to Blender 2.6x. David’s exporter for Blender 2.4x is called xmlmeshexport.py, the new exporter for Blender 2.6x is called EldritchXMLMeshExporter.py.
That’s a tough one. The engine does not like it when stuff that is referenced in the config files or the save files is not actually there. So if mEldritch crashes, it is usually something to do with that.
- If you just upgraded mEldritch, and it crashes upon startup, try deleting your main.meldritchmastersave file.
- If you removed a mod, and mEldritch crashes, try deleting your main.meldritchmastersave file. Most likely the mod defined some resources that are not presend any more, but are still referenced in the save file.
- If you are making a mod, and mEldritch crashes when it is loaded, chances are, you have a typo somewhere. For example, your spawner references an entity that is not defined, or an external asset like a texture is not found. I am slowly adding code to indicate what went wrong, check meldritch_log.txt for hints.
A lot of the third category of crashes will present a dialog box explaining (or in some cases hinting at) what is wrong before terminating mEldritch.