Differences

This shows you the differences between two versions of the page.

--- slidge:getting_started_-_information [2018/04/05 21:22]
journeyman [The Data]
+++ slidge:getting_started_-_information [2018/12/22 19:32] (current)
journeyman
@@ Line 1: / Line 1: @@
 ===== Things to know about the engine's workings =====
-==== Bugs ====
+SLIDGE has a whole bunch of parts to it, but it can be simplified into just 2 story-telling ideas and 3 major types of visual content.
-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~
+The storytelling ideas are **Scenes** and **Moments**.
+  * **Moment** : Any arrangement of text and other content on the screen. Moments are played in order, and can be used to create sequential dialog between several characters, or a short animated sequence.
+  * **Scene** : A set of moments. A scene may link to any other scene, so you can assemble parts of your game's dialog as you need.
-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.
+The major types of visual content that may be displayed during a moment are **textbox**, **choice**, and **character**
+  * **Textbox** : Text may be entered into one or several textboxes, and each can be set to reveal text like a typewriter or all at once. Textboxes can have a visual style assigned to them to customize appearance.
+  * **Choice** : Similar to textbox, but choices can link to other scenes or can compute and modify game data.
+  * **Character** : Portraits of characters (or other images) may be displayed. Characters may have multiple "expressions" defined, allowing you to choose between a character's appearances as you edit.
-==== Terminology ====
+Continue to [[slidge:getting_started_-_first_steps|First Steps]] to learn how to use this engine with GameMaker Studio 2.
-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]].
-=== File ===
-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.
-=== Scene ===
-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 has a set of properties:
-  *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
-=== Moment ===
-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.
-==== The objects ====
-There's 2 objects packed with the engine, and they are interchanged when you need swap between editing and playing back dialog.
-=== Edit object ===
-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.
-=== Show object ===
-Used to play dialog without the editor. Your final game ought to use this object.
-=== The functions ===
-The objects do 4 simple things:
-  -draw the background
-  -draw the characters
-  -draw the textboxes
-  -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.
-==== The Data ====
-Formats are at the links below. Description of how JSON and SLUDGE "work" follows
-Formats: [[:scenes]] - [[:styles]] - [[:characters]]
-=== Hierarchy in SLUDGE ===
-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
-=== JSON ===
-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.
-== JSON Overview ==
-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.
-== JSON Example ==
-Here's a sample bit of JSON, with commentary added:
-<code>
-{                           <-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
-,2,"A","B"  <-Several data in a List
-              ]             <-End of a List
-}                           <-End of an object
-</code>
-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.
-=== Maps and Lists ===
-Happily, Game Maker can grab a big, messy JSON string and turn it into data structures in memory automatically ( [[http://docs2.yoyogames.com/index.html?page=source/_build/3_scripting/4_gml_reference/file%20handling/json_decode.html|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!
-=== Arrays and Instance Variables ===
-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().
+For further explanation of the terms, check out [[slidge:glossary_of_terms]]