"How do I mod this thing, anyway?!"

A Brief Guide to Basic Modding for Shadow of the Wyrm

- To edit game data, edit data/ShadowOfTheWyrm.xml.  Its structure is
  defined by data/ShadowOfTheWyrm.xsd, so if you use an editor like
  Notepad++, you can use Alt+Shift+Ctrl+M to validate the updated XML
  against the schema.  The various values for effects, damage types, etc.,
  are provided in the XSD, and will typically provide references back to
  where the details of those types can be found in the engine's C++
  code.

- If you want to add your own sound effects, open data/ShadowOfTheWyrm.xml,
  and navigate to the <Sounds><Effects> node. You'll see a list of Effect
  elements, with ids starting with underscores. These are the system sound
  effects, referenced in code. You can add your own sound effects to these:
  the game will try to match them to in-game messages.

  1. Add a new Effect element, and specify an id attribute.  This attribute
     needs to be unique among all the other Effects.

  2. Add a match attribute, and specify its value.  The value of this element
     is an ECMAscript regex the game will use to try to match whenever a
     message is send to the display in-game.  If it matches, the effect will
     be played.

  3. Specify the Location element under the effect.  This is the location of
     your sound effect.

- Adding sprites is a bit more effort, but not particularly hard.  You'll
  need Gimp.  Open up the appropriate file (creature_sprites.xcf,
  item_sprites.xcf, etc) in Gimp.

  - Go to Image -> Configure Grid
  
  - Click the chain link under "Spacing" so that it's broken

  - Ensure spacing is 16 for horizontal, 24 for vertical

  - Click OK

  - Now go to View -> Show Grid. You should set the grid neatly placed around
    the existing sprites.

  - Finally, add your new sprites.  Ensure the FG colour is white.  You'll
    likely need to magnify 6x so that each of the "checks" in the transparent
    background corresponds to a pixel.

  - Use the tools (pencil, etc) to make a new sprite.

  - Finally, when you're done, save the project, then do a File -> Export and 
    export to assets/sprites.

- If you want to add your own music:

  - The SotW engine uses SDL for playback, and can handle MP3, WAV, and most
    Ogg Vorbis (I say "most" because direct ogg export in my notation program,
    MuseScore, doesn't work, but exporting to .wav, and then converting .wav
    to .ogg in Audacity, works fine).

  - How to actually create music from an idea is far beyond the scope of this
    textfile (I obsessively listen to classical music for at least a few hours
    a day, and have for most of my life). But in terms of actually creating
    the music files, I use MuseScore for notation, and MuseSounds for
    soundfonts that actually sound like real instruments instead of cheap
    MIDI.  A DAW is probably more powerful and flexible, but for my purposes,
    MuseScore is good enough, easy, and quick.  I notate everything in
    MuseScore, tweak levels in the mixer, and when I'm happy, export to .wav.
    Then I use Audacity to convert this to a .ogg file.

  - Once you have a .ogg/.mp3 file, put it in assets/sound/music, and then
    update ShadowOfTheWyrm.xml, or one of the maps.

  - If the music is event-driven, or is meant to play on certain terrain (eg,
    the overworld map, all forests, all dungeons), put it in
    ShadowOfTheWyrm.xml.  If it's meant for a particular map, like Isen Dun
    or Carcassia, it should go in the respective map file.  There are
    examples in both of how to hook in music files.

  - If the music is event-driven:

    - If it's for the title screen, ShadowOfTheWyrm.xml

    - If something triggers it in-game, you'll need to update the Lua scripts.
      See scripts/quest/isen_dun/ead.lua for an example.
  
- Resource strings are defined in shadowofthewyrm_blank.ini, and also
  in each language-specific resource strings file.  So if you were
  wanting to edit a resource string, edit shadowofthewyrm_en.ini.  To
  add a new one, add it to the blank resource strings file, and then to
  your language-specific file, giving it its actual value there.

- To add a new map, create a new XML file in data/maps.  Your XML should
  validate against CustomMap.xsd.  To place that map somewhere on the
  world map, add a new entry to data/maps/world/WorldMapAreas.xml.  Make
  sure your map has a unique ID!

- The Guidebook is located in docs/src, and is written in LaTeX.  To
  generate the PDF, you'll need to run "generate_docs.sh" in the src
  folder.  You'll need to run it twice to updated the content as well as
  the table of contents, since LaTeX is single-pass.  You'll need an 
  environment with the Bourne shell (e.g., MinGW) to run the shell
  script properly.

- Lua scripts are located in the scripts folder.  If you're adding a new
  subfolder, be sure to edit scripts/env.lua so that the new folder is
  considered when the game starts up.  To see what functions are
  available, look at engine/scripting/include/LuaAPIFunctions.hpp (for
  the list) and engine/scripting/source/LuaAPIFunctions.cpp (to see
  what kinds of parameters are expected).  

  IMPORTANT NOTE: Some Lua scripts (typically, those run directly by the
  engine, rather than the scripts that register functions to be called from
  lookup tables), when run, will cause the game to crash if there is an 
  error in your Lua code.  I will look at improving this at some point in 
  the future, but for the moment, be careful with your Lua code!

