README

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

http://eldritchgame.com/

The original source code is available from the bottom of this page:

http://eldritchgame.com/about.html

This build has been created by Gunnar Zötl (gz@tset.de). 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:

There is no “real” documentation yet, assorted notes follow.

Installation

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

Copy the 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 the Mods folder and add it to Mods/mods.cfg.

Start mEldritch(.exe) instead of Eldritch(.exe). Press Control+Shift+T 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.

MacOS X

First, open (not run, but “show contents” or whatever that is called in non-german) the Eldritch.app (or better yet, a copy of it). From the Archive, copy the folders MacOS and Frameworks into Eldritch.app/Contents, but 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 CFBundleExecutable with mEldritch (should be Eldritch before replacing). Otherwise you can just navigate to Eldritch.app/Contents/MacOS and start mEldritch from there.

The 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 Mods folder and add it to Mods/mods.cfg.

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:

Modding

a mod is stored in a directory beneath Mods, with a file named mod.config inside it. See the template mod in the Examples folder. Active mods are added to Mods/mods.cfg. A mod is only loaded if it is added there.

Config files are loaded like this:

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:

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.

Worlds

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

You can place rooms or restrict the placement of rooms with in the world by using the Slice[XYZ]* set of config variables.

Rooms

A room is stored in a directory and with a filename following this pattern:

Rooms/[world]/[theme]-([stuff]-)[exits](-[version]).eldritchroom

Only the format of the room is mandatory, everything else can be changed. Room themes and exits are determined from the room’s filename. [theme] is 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:

http://www.gdcvault.com/play/1022110/Level-Design-in-a-Day

or the slides here:

http://dphrygian.com/bin/dpittman-gdc-2015-procedural-level-design.pdf

Room editor

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.

Keys

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

Ingame keys

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

Config files

Syntax (from configparser.cpp):

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 bla0, bla1.

Counters are not bound to the arrays

New in mEldritch:

numbla=?

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 & and ^. 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:

[ThisCreatesAContext]

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

default.config :startup configuration.

worldgen.config
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.
spawners.config
defines the spawners for objects and AIs used in the game.
tools.config
settings for the editor, amongst other things makes those spawners defined in spawners.config available to the editor.
entities*.config
everything that lives or lies around in the world. If it’s not a voxel, you can find it here.
bt.config
the behaviour trees for AI entities.

There’s a lot more, explore and document your findings.

Objects

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.

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

mChecksum <file> [-s]

Computes a checksum for . append -s for short output.

mConfigCompiler

mConfigCompiler <infile.config> <outfile.ccf>

Compiles config file <infile.config> to a binary format and writes that to <outfile.ccf>.

mConfigDecompiler

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

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

mFilePacker <infile> <packfile.cpk> [-c]

appends the to the archive <packfile.cpk>. The complete path as specified for will be used in the packfile. The file will be appended uncompressed unless -c is specified.

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

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.

mMeshCompiler

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.

Troubleshooting

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.

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.