It is possible to crash the editor. You can successfully mess up the data files. General solution: Don't do the thing that makes it break. There's thousands of error checks already, but go easy on the editor~

That being said, if you're doing something that's clearly a feature, and something crashes, I really need to fix it so let me know.

I'll be referring to arts of the engine throughout this wiki, and it's important to explain, briefly, what they mean in the context of the programming, data, and conceptual organization. To see how the terms fit together, see Hierarchy in SLUDGE.

A file is an arbitrary collection of Scenes (see below). You can divide your dialog content into multiple files, or keep it all in one file. Some reasons to possibly use multiple files:

• Speed. Files load very fast, but if your game is hugemongous, you might split up some dialog.
• DLC. If your game will have downloadable extra content, you'll have files for that.
• Localization. You can use the game's language suffix to load different sets of files for different languages

The engine works seamlessly across files, so these are primarily used by you to keep things straight.

A Scene is a collection of Moments (see below) that must be played in order. Scenes can be used to arrange pieces of dialog and character movements and choices. Typically, a Scene ends when the player is faced with a set of choices: each choice then links to a new scene. Every scene contains the following:

• End Link: This is the name of a Scene, or it's a variable that contains a Scene name
  • After the final moment in a scene plays, the engine follows the End Link on to the next Scene
  • If there's no valid End Link, the dialog has ended. The Show Object will remove itself.
  • If Choices are used, a Scene might never reach the End Link due to redirection via choice links
• Entries: Internally tracked property to count entries (usually moments) within one Scene

A Moment represents one visual set of information presented on the screen. For example, several characters standing on the screen with a line of dialog might be a moment. In the next moment, those characters might move or a “next” line of dialog might appear. Moments have a set of properties associated with them:

• Sound: A sound to play when the moment starts. If the sound file is still playing when the moment ends, it continues unless another moment plays a sound.
• Background: A graphic to display behind all other dialog engine content
• Time: Moments can advance automatically if you wish.

There's 2 objects packed with the engine, and they are interchanged when you need swap between editing and playing back dialog.

Used while designing your game. It displays dialog moments in the given Scene, but adds a visual interface to the screen for setting all of the various things supported by the engine. Automatic “things” like animating between moments, advancing to another moment after a time, and applying typewriter text will not occur in the editor.

Used to play dialog without the editor. Your final game ought to use this object.

The objects do 4 simple things:

1. draw the background
2. draw the characters
3. draw the textboxes
4. draw the choices

The editor object and the show object use the same 4 function calls in their draw event. It's truly what-you-see-is-what-you-get.

• Specific JSON formatting is described in Formats.
• Data generated by the Engine, or to be fed into the Engine is described in The Register (Using Variables)
• Description of how Scene elements fit together is described in Hierarchy in SLUDGE

Several files are created automatically in your %localappdata% folder as you edit your game. These files should be add to your game as “Included Files” when you're ready to distribute. The format and purpose of each file has its own page:

Index - scenes - styles - characters

SLUDGE creates one global variable in Game Maker, called register. The register is a ds_map data structure, and it holds any information that you want to pass into or out of the engine.

Think of the Register as a big table of data accessible to both the SLUDGE engine and any other game code you might write. Any information that needs to be passed back and forth can be modified in the Register, and both your code and mine will be able to use it.

In short, a Map is a set of data entries in which each piece of data has a unique name, called a key. If, for example, you wanted to remember a player's Name, you might use the key “name” and set the value to be whatever the player inputs. Game Maker has built-in functions for adding data to a map and reading data from a map. The SLUDGE Engine also has a method for doing this.

Within SLUDGE, register values can be set whenever a player makes a choice. The format looks like this:

r[key]=value

It's also possible to modify numbers using + and -

r[key]+=1

You can also use Game Maker's functions to add data into the engine. For example, the results of a mini-game (which you program using Game Maker, outside of SLUDGE) might affect dialog options in the next SLUDGE Scene. Since Game Maker has several other data structures besides Maps, the formatting is a little different:

register[?"key"] = value

SLUDGE can display Register data as part of text, and it can also retrieve Register data to do comparisons. When you want SLUDGE to use Register data, you use the bracket tag format that's generally used throughout the engine:

Hello [r:key], it's nice to meet you.

So, if you used the key “name” to store a player's name, you'd type [r:name] into a dialog box in order to cause a substitution when the game is running.

You'll also be able to perform comparisons between register values, but don't worry about that for now!

Based upon the terminology section, here's how information is grouped inside the engine's data:

Conceptual structure of 1 scene containing 2 moments with text, characters and choices:

• File
  • Scene
    • Moment 0
      • Background
      • Textboxes
        • Specific Textbox
        • Specific Textbox
      • Characters
        • Specific Character
        • Specific Character
    • Moment 1
      • Background
      • Textboxes
        • Specific Textbox
        • Specific Textbox
      • Characters
        • Specific Character
        • Specific Character
      • Choices
        • Specific Choice
        • Specific Choice

SLUDGE stores information using the JSON format. This format can be loaded into Game Maker data structures, and it provides a hierarchical way of storing data. The structure makes adding new features very easy, and helps to ensure that future changes won't totally break existing projects.

If you've never used JSON before, it will be useful to learn the basics before using SLUDGE.

• Data in JSON comes in several forms:
  • Numbers: These are just..numbers
  • Strings: Text inside of “quotation marks”
  • Lists: A set of pieces of data, contained within [square brackets], listed in order, and separated by commas
  • Objects: A set of pieces of data, contained within {curly brackets}, paired with a key, and separated by commas. The key is like a label to help you find that data later.
• Notice that Lists and Objects contain pieces of data; these can include Lists and objects!
• All of this data can be looked up later by name or list number.

Here's a sample bit of JSON, with commentary added:

{                           <-Start of an object
   "name"   : "SLUDGE",     <-String of text paired with the key called "name"
   "number" : 1.0000,       <-Number paired with the key called "number"
   "list"   : [             <-Start of a List
               1,2,"A","B"  <-Several data in a List
              ]             <-End of a List
}                           <-End of an object

In JSON, new lines and extra spaces don't really do anything–I put each thing on a new line in order to make it readable and to give myself space to comment on it.

Hopefully, it's reasonably clear from the example above that there's an Object containing 3 pieces of data called “name”, “number”, and “list”.

The values assigned to “Name” and “Number” are just a name and a number, but “List” is where it gets interesting. “List” has a JSON List assigned to it, and there's multiple items inside. This is the key to achieving hierarchy.

Happily, Game Maker can grab a big, complex JSON string and turn it into data structures in memory automatically ( json_decode() ). Objects in JSON turn into ds_maps and Lists in JSON turn into ds_lists. Accessing data from these becomes trivial, once they are loaded in, and the engine handles almost every bit of it automatically. It's there if you need it though!

SLUDGE is designed to be able to provide easy and powerful dialog with your game. To that end, it's possible that you might want to program something that needs a bit of data from the Engine. It will be useful to know that some of the data for a scene is already “looked up” and separated in the dialog objects for you.

After a Scene Moment loads, the following arrays exist as instance variables within the dialog object:

• myChars: Each array element contains the reference number to a map containing info about a character displayed in this Scene Moment
• choices: Each array element contains the reference number to a map containing info about a choice displayed in this Scene Moment
• myText: Each array element contains the reference number to a map containing info about a text box displayed in this Scene Moment

Additionally, some other frequently-used information exists after a Scene Moment loads:

• fileMap: The entire JSON object retrieved from a file that contained the requested Scene
• convoMap: The ds_map containing data for this Scene and all of its Moments
• entryMap: The ds_map containing data for this specific moment
• maxEntry: The number of entries in this Scene
• background: The name of a background image
• sound: The name of a sound that should play
• playingSound: The numerical reference value for the exact sound buffer that is actually playing in the background right now
• momentTimer: The amount of time (in seconds) to show this moment before automatically advancing
• alarm[2]: The current count (in game steps) of the countdown timer to advance the dialog. If it's -1, the timer has expired or was never set. If it's zero, the engine is advancing. If it's higher, the engine continues counting down.

There are many more instance variables and settings available in the script called create_common_data().