When starting up, one of the first things the Driftwood 2D engine does is read the configuration file. This file is written in JSON and contains the engine's default settings. In order to change these settings, you will have to edit this file. However, some settings may be changed temporarily at runtime using command line options. Command line options are discussed in the next section, Command Line Options.

JSON is a simple language for describing sets of data. You won't need to know very much about it here, since the file is already mostly written for you.

Structure of the Configuration File

The engine will not make assumptions about configuration; all options must be present or it will not run.

Here is the configuration file that comes with this version of the engine:

{
  "database": {
    "root": "db/",
    "name": "test.db"
  },
  "cache": {
    "ttl": 300
  },
  "input": {
    "keybindings": {
      "up": "SDLK_UP",
      "down": "SDLK_DOWN",
      "left": "SDLK_LEFT",
      "right": "SDLK_RIGHT",
      "interact": "SDLK_SPACE",
      "console": "SDLK_BACKQUOTE"
    },
    "debug": true
  },
  "audio": {
    "support": ["ogg"],
    "frequency": 22050,
    "chunksize": 4096,
    "music_volume": 128,
    "sfx_volume": 128
  },
  "log": {
    "verbose": true,
    "halt": true,
    "file": "driftwood.log",
    "suppress": [
      ["Tick"]
    ],
    "suppress_halt": [
      ["WARNING"]
    ]
  },
  "path": {
    "root": "data/",
    "path": [
      "test/"
    ]
  },
  "tick": {
    "tps": 60
  },
  "window": {
    "title": "Driftwood 2D",
    "width": 480,
    "height": 480,
    "fullscreen": false,
    "zoom": 4,
    "maxfps": 60
  }
}

You can see that there are several sections. Let's take a look over each section and the settings it contains.

database

The "database" section contains settings related to the database. The database is where variables are stored between engine runs; think of it as a save file. The database will be explained more in depth in the Database section later in this chapter.

root

The value of "root" is a string. It contains the relative (to the top level engine directory) path to the folder where the database is stored. Normally this is set to "db", but it doesn't really matter what you set it to as long as the folder exists.

name

The value of "name" is a string. It contains the filename of the database that will be used when running the engine. The file is looked for in the directory set in the "root" setting. Each database is like a save file, so you would change this if you wanted to start over or play a different game, or load a "save" from earlier.

cache

The "cache" section contains settings related to resource caching. When a resource is requested by the engine, it will be kept in memory in case it is needed again for a specified amount of time.

ttl

The value of "ttl" is a number of seconds. This is the "time to live" for the cache -- the amount of time that a resource is held in memory after the most recent time it was used before dropping out of the cache. Decreasing this number will lower RAM usage, but may also increase load times if your computer has very slow storage. 300 (or 5 minutes) is generally a sensible value.

input

The "input" section contains input handling settings. Keybindings and debug mode are set in this section.

keybindings

This subsection contains the names of several input actions, and each of them contains a string value which references an SDL Keycode.

  • "up": Move up.
  • "down": Move down.
  • "left": Move left.
  • "right": Move right.
  • "interact": Interact with an object.
  • "console": Drop to debug console if enabled.

debug

The value of debug is a boolean. If true, pressing tilde (or your configured key) will drop to a debug console which can be used to enter event scripting code while the engine is running. Otherwise the feature is disabled.

audio

The "audio" section contains sound and music settings. Some of these are unlikely to need modification. Volumes are set in this section.

support

The value of "support" is a comma-separated list of strings, denoting which kinds of audio files to support. Valid options are "ogg", "mp3", and/or "flac".

frequency

The value of "frequency" is the sampling frequency at which the audio subsystem will run. It is unlikely you will ever need to change this unless you have a very weak sound card or are some kind of audiophile.

chunksize

The value of "chunksize" is the chunk size of the audio subsystem. This should be a power of two. It's unlikely, but tweak this number if you encounter audio stuttering.

music_volume

The value of "music_volume" is the numeric volume at which music is played by default. It is a number between 0 and 128, 128 being highest and 0 being off.

sfx_volume

The value of "sfx_volume" is the numeric volume at which sound effects are played by default. It is a number between 0 and 128, 128 being highest and 0 being off.

log

The "log" section contains settings for the engine log, which outputs to the console (if run in the console.) The settings here control what sorts of information to output, and can also silence specified messages and errors. The engine log is expanded upon in the Engine Log section later in this chapter.

verbose

The value of "verbose" is a boolean (true or false.) If this is set to false, the log will not output messages that are not warnings or errors. If true, all messages will be output.

halt

The value of "halt" is a boolean (true or false.) If this is set to false, the engine will not stop when encountering warnings or errors. Otherwise it will.

file

The value of "file" is a string. It contains the relative (to the working directory) path to a file to which log messages should be written, in addition to being written to the console.

suppress

The value of suppress is a comma separated list of lists of strings. Each item in the outer list is a suppression rule, and those rules are lists where each item in the list is a successive item in the log chain to be matched. Items in a log chain are matched to the rules chain until the end of the rules chain. If all items match, the message is not outputted. You can see that ["Tick"] is suppressed by default; if this were not the case, the log would be flooded with callbacks, which is sometimes desirable for debugging purposes. Log chains and suppression rules are discussed in the Engine Log section later in this chapter.

suppress_halt

The "suppress_halt" option is just like "suppress", except that instead of preventing output, it prevents halting. If a suppress_halt rule matches a message, that message will not cause the engine to stop running even if the "halt" setting is true. You can see that ["WARNING"] is suppressed by default; this prevents the engine from stopping on warnings. Again, these rules are discussed in the Engine Log section later in this chapter.

path

The "path" section contains settings for the virtual filesystem. Settings here tell the engine where to look for data. The virtual filesystem is discussed in-depth in the Data Path and Patching section later in this chapter.

root

The value of "root" is a string. It contains the relative path (from the top directory) to the root of the virtual filesystem. This is the directory where the engine will look for world packages and patches -- game data. The Data Path and Patching section later in this chapter discusses the virtual filesystem.

path

The value of "path" (the subsection, not the section) is a comma-separated list of paths to packages, relative to the "root" directory. These packages are directories or zip files, and they are loaded on top of each other into the virtual filesystem in the order they are listed, replacing conflicting files from the ones preceding. This allows hotpatching. The "path" list must contain, at the very least, the relative path to the world package you are trying to load. See the Data Path and Patching section later in this chapter for more information.

tick

The "tick" section contains settings regarding engine ticks. Each tick is a cycle of the engine in which things can happen.

tps

The value of "tps" is the number of ticks per second the engine runs at. This is the engine's speed limit for processing data. Low numbers will greatly reduce CPU usage but cause stuttering, while high numbers will increase CPU usage and are probably not useful above the frames per second your eye can detect.

window

The "window" section contains settings relating to the game window and graphics. You might also call these the video settings.

title

The value of "title" is a string. It contains the title that will show on the game window at first when the engine starts.

width

The value of "width" is the width in pixels of the game window, and also the maximum width of the view in in-game pixels. The actual width may be stretched in fullscreen mode.

height

The value of "height" is the height in pixels of the game window, and also the maximum height of the view in in-game pixels. The actual height may be stretched in fullscreen mode.

fullscreen

The value of "fullscreen" is a boolean (true or false.) If this setting is true, the engine is run in fullscreen. Otherwise it is run in a window.

zoom

The value of "zoom" is the number of times to multiply the width of a pixel in-game. This can give a retro look. The view will actually zoom in without changing the width or height in real pixels, so if you zoom too far there won't be much on screen at a time.

maxfps

The value of "maxfps" is the maximum frames per second the engine will display at. Setting this number higher than the ticks per second ("tps" in the "tick" section) is meaningless.