The Scene List Panel

The Scene List Panel, in the upper left, is a list of your project's scenes, loaded from either your browser's localStorage or a scenes.json file. Click on a scene's name to select it, making it visible for editing. Click the + symbol to add a new scene to the list. The button will show a pop-up window asking you to name the scene. The name cannot be blank or contain spaces.

The Scene View Panel

The Scene View Panel, on the right, shows the script for the currently selected scene. The first 3 lines are mandatory for the file, however, only the Name line must be filled out to work. You can rename the scene, but be careful not to leave it blank or give it the name of an existing scene, as that may cause problems. The images line is where you list the first background image for the scene, followed by all the image filenames for that scene, separated by commas. This is so jStory can preload all the images, preventing the player from seeing them load on use. On the music line, simply include the filename for the first or only track of the scene. You can delete the scene by clicking the red trashcan in the upper right of the panel.

The rest of the script's lines are grouped by indexes, which are just individual screens in your game. To interact with an index, you can click the tab, the upper left part where the index number is shown, and drag to move it within the script. If you click anywhere else in the box, you will select it for editing. A selected index will expand, take on a brighter background, and show the 5 edit buttons (Insert Index, Add Change, Add Choice, Quick Ref, and Delete Index).

The Scene Menu Panel

The Scene Menu Panel, bottom left, contains buttons for interacting with your script/s.

The Load button is a toggle switch that shows either 'Load file' or 'Load Local', the opposite of the current load state. By default, your scene list is loaded from your browser's localStorage. Clicking "Load File" will cause jStory to look for a scenes.json file in your scenes folder, and load the scenes listed there. While viewing scenes loaded from a file, you will be unable to edit them, but you can copy them to your local list by pressing the yellow button in the upper right corner of the Scene View.

The Download button will pop up a window giving you the option to download the current scene (sceneName.json) or the scene list (scenes.json). These should be saved to the scenes folder. If you want to work on a new scene while you're on a mobile device, you can do so at http://ramifygames.com/jstory/editor, and then email yourself the scene data using this window. To use the data, create a new text file inside the scenes folder with the extension .json and paste that text inside. It will then function as a normal scene file.

The Run button will pop up a window where you can test your game from the current scene. It will play from the currently selected index. You can also press enter/return to run the game. By default, the screen size is set to iPhone 5 dimensions for the sample game. You can use the input boxes above the test window to enter a custom size on the fly.

The Help button, which you've already clicked to get here, can be clicked again to hide it.

Responsive Layout

jStory's editor is responsive, meaning it adapts to the current screen size. For devices smaller than a computer, the layout will change so that the Scene Menu is at the top, followed by the Scene List, and then the Scene View at the bottom. On mobile devices, the header section of the editor becomes fixed at the top of the page. When working with long scenes, click the jStory logo to jump to the top where the Scene List is. Click the white menu icon to toggle the 4 Scene Menu buttons.

Text lines are the backbone of an index and, being a required line for each, it is added automatically upon adding or inserting a new index. These lines will contain the bulk of your game's content and might be used for narration, dialogue, etc... A text line may be left blank, but you must set a timer for that index (see Timers section below). Choice lines offer the player options for choosing what to say, what to buy, where to go, etc... They can also be used as a submit button when using an input box.

Text and Choice lines also accept any valid HTML code, if you wish to add classes to any particular text (for web developers), use line breaks, bold, italic, etc...Add a line return with '<br>', bold text by highlighting and pressing command/ctrl + b (will auto-create html tags), and italicize text by pressing command/ctrl + i.

Conditions

Conditional statements are what make dynamic gameplay possible. In programming, you typically say 'if something is true/false, then do a particular thing.' In jStory it is functionally the same, but looks a little different.

If you begin a text or choice line with |variableName operator(=,!,<,>) value|, the engine will only display that line if the condition is true. For instsance, you may only display an item for sale if the player has enough money, and use something like |money > 50| on a choice line. If a text condition is false, it will skip that entire index, including any changes listed. If a choice condition is false, it will simply omit that choice from the set. You can also check for multiple conditions using a single comma between them, such as |variableName = value, variableName > value| . In this case, all statements will have to be true to show the index/choice.

Linking

Without links (or using the Change line to be discussed next), the player will just advance to the next index upon clicking the text box or a choice. Just like we do on the internet, links are how the player navigates your game.

On a text line, you can wrap a word in number signs like #this# to link it to a scene. The word you make into a link must by indentical to the scene name. In the example above, clicking that link would take the player to a scene called 'this'. You can additionally link a word to a specific index in the current scene with something like #later, 15#. This would show the word 'later', which would link to Index 15.

On a choice line, you can wrap a scene's name or an index in number signs to set the destination for that choice, like #store# or #5#. These will be invisible links, however, and can be placed anywhere on the choice line.

Inserting variables

You can plug in a variable's value anywhere on a text or choice line by wrapping the variable's name in curly braces. For instance, if the variable 'money' equals 50, then {money} will insert '50' in its place when running the game.

Reserved Characters

The characters used in the above operations, the | (vertical bar), # (number sign), and {} (curly braces), are considered reserved characters (sort of) in jStory and have restricted use. The | can be used as regular text anywhere except the beginning of a line, which will trigger the condition function. The # can be used once per line as text, but more will trigger the linking function. Curly braces should not be used as regular text at all.

An index's Change line is where the magic happens. It allows you to set/change one or more variables in your game, including the scene, index, images, music, volume, and any variable you set for your game, such as money. It also allows you to perform a handful of special actions or effects that are explained below. A Change operation's syntax is the same regardless of the variable or action you're performing, and is similar to the condition function mentioned above: variableName operator(=,+,-,*,/) value (always without quotes).

Examples

You can change scenes with 'scene = sceneName' and go to a different index in a scene with something like 'sceneIndex = 4'. Change the background image with 'image = fileName.jpg' and the music with 'music = fileName.m4a'. Music/sound volume with 'volume = .7'. Note that the volume value is between 0 and 1. Other built in variables are: character and overlay (see image layers section), video, speaker (the name of the current speaking character), and sound (effect or V.O).

You can change mulitiple variables using a single comma between them, such as 'variableName = value, variableName + value'. Variable names and values must not contain spaces or dashes. If you need to assign a text value with spaces to a variable, use underscores and those will be converted to spaces when displayed. It's also important that file names do not contain spaces.

Screen Size

By default, when your game is played outside of the editor, it takes up the entire width and height of the browser window. This is typically not going to be ideal for larger screens. You can set the width and height (in pixels) of your game window by setting the variables 'screenWidth' and 'screenHeight' to the desired values. You might use 'screenWidth = 800' and 'screenHeight = 600'. jStory will then automatically center your game's window within the browser. I recommend you set these variables on the very first index of your game, along with any other variables to be used through the entire game.

Image layer variables

There are 3 image layers in jStory: image, character, and overlay. The 'image' layer is the background image for a scene. This is the primary layer that should typically always be there, and is the one you list first on the images line. As mentioned above, switch to a new background from the Change line with 'image = fileName.jpg'. The character image is on top of that, and is used for the characters in your game, 'character = fileName.png'. The overlay layer is on top and can be used for anything you want, such as showing an acquired item. Character and overlay files should be .png to support transparent backgrounds.

Adding video

Add videos to your game 1 of 2 ways. For self-hosted videos, create a folder named 'videos' and add an .mp4 file. Then, on the change line, use 'video = fileName.mp4'. To display a YouTube video, use 'youtube = videoId'. The video id is the string of letters and numbers found after 'youtube.com/watch?v=' in the url. Self-hosted videos are highly recommended in most cases. They can be muted and don't have the YouTube logo. Also make sure your videos are the same size/aspect ratio as your game.

When changes occur

One important thing to note with variables in jStory is that all changes occur BEFORE the text for a line is displayed, so if you change a variable on that index and also display it, you will see the new value. If you use the Change line to go to a new scene or index, the variable will change when all the other ones do, but the result occurs after that index. Also, any scene/index linking will override changes to the 'scene' or 'sceneIndex' variables on the Change line.

Collections

You can use collections, a container of multiple items, for things like the player's inventory. On a change line, you can set an empty collection by typing something like 'inventory = []' or you can set initial items by using 'inventory = [gun&ammo&flashlight]'. You can add or subtract items from a collection with something like 'inventory + dagger'. These items are text only, and do not contain values within themselves. But, you can store a separate value for them outside of the collection, in its own variable, money = 50 or dagger = 1.

You can check if a collection has an item or not with conditionals, '|inventory = dagger|' (true if it has) or '|inventory ! fruit|' (true if it doesn't have). When displaying a collection, it displays as a comma-separated list by default. You have the option to display each item and its corresponding value on separate lines using 'collectionDisplay = values' on a Change line. 'collectionDisplay = list' will set it back to the default.

Working with 2 variables

Variables can be assigned, added to, and subtracted from the value of other existing variables, with the exception of collections. For instance, let's say you're depositing money in a bank. You might have a variable for cash on hand called 'cash' which equals 100, and another for your bank called 'bank' which also equals 100. If a character makes a deposit, you could use 'bank + cash' to handle that, and bank would then equal 200. The result of the operation is always stored in the first variable listed. It also works with text. If name = John and lastName = Smith, then name + lastName would result in 'name' having the value 'JohnSmith'. To add a space, use an underscore. Make name = John_ or lastName = _Smith and the previous operation would result in 'name' having the value 'John Smith'.

Player Input

To provide the player with a text input box for inputting something like his/her name, use 'input = varName' on the change line. This will store the player's inputted value to the variable name specified. There's no built-in validation for user input, but you can check the value using a conditional line and send the player back by changing the sceneIndex if need be. You must also use a link or choice as a 'submit' button so the player doesn't advance to the next screen without clicking that.

End of Game

At all endpoints for your game, use 'endOfGame = true' to prevent the player from clicking further, forcing them to leave or begin a new story.

Timers

Set a timer for an index to advance the player to the next index automatically when the timer expires. Timers can be used to create automated sequences, such as the intro to your game. They can also be used to create an added sense of reality or urgency to a moment in your story. To set a timer, set the variable equal to a number in milliseconds on the change line, 'timer = 5000' for a 5 second timer. You can also take the player to a specific index or scene if the timer expires and no choice or link has been clicked. To do this, set the timerDef (timer default) value to the desired index/scene, 'timerDef = 17' or 'timerDef = room'.

Show/Hide

You can show and hide visual elements from the Change line by using the variable 'show' or 'hide' and setting it equal to the variable name of an element. For example, 'show = options' will display the box at the bottom of the screen that allows players to begin a new story or toggle the sound. By default it's hidden. Other elements that can be shown or hidden are: image, character, overlay, speaker, and video/youtube. To show something that's been hidden, use 'show' if the value of that variable hasn't changed or just assign the variable a new value, which will automatically show it.

Random Events

Random events add replay value and unpredictability to a game. You can generate a random number by setting the 'rand' variable to a value, which represents the max random number. For instance, if you want to generate a random number between 1 and 10, do 'rand = 10'. The engine will auto-pick a number between 1 and the specified value, and assign it to the variable randPick. Then, use conditional text or choice lines to check for the randPick value, and only display an index or a choice if a certain random number was picked.

Typewriter Effect

jStory text uses a typewriter effect. To turn it off, use 'type = false'. You can additionally set the speed using the typeSpeed variable. By default, it's set to 30, meaning a 30 millisecond pause between each letter. This is pretty fast, but still a little slower than someone can read, which is ideal for slowing down the pace of your story. The higher the number, the slower the typing.

Transitions

Transitions in jStory are all fades, and at the moment, that cannot be changed without knowledge of Javascript. You can change the length of those transitions though. Maybe you want a slow background image fade for the intro or an emotional moment in your story. You might use 'imageTrans = 3000'. Below are the transition time variables for various elements and their default values (in milliseconds):

Assets

jStory does not allow you to position graphics from within the editor. I currently do not see a need for this and believe it adds unnecessary complexity for the majority of users. Just export all images at the same size, whatever your desired project size is. With character and overlay images that have a transparent background, position the visible content on the canvas of your graphics editor, and that's where they will appear in the game. While this is slightly less flexible, it is significantly faster.

While you can technically use whatever file types you decide, each asset type has one that is strongly recommended. Background images should be .jpg, character and overlay should be .png (transparency), audio should be .m4a, and video should .mp4 - Most editors will allow you to export these types. Note: Use of mp3 files in commercial applications requires a license, but you can convert them to .m4a in iTunes or use an online converter. Google for more info.

Browsers and Local Storage

I haven't done extensive browser testing, but jStory should at least work with the last few versions of Chrome, Safari, Firefox, and Opera. If you're using IE, stop and rethink your life. Older browsers may have limited support.

Also, be aware that mobile devices, such as phones and tablets, may have limited support for audio and video. For instance, you may not get autoplay capabilities, which will require the user to press a button to start a music or video track, or you may not get multiple audio files to play simultaneously. These are functions of the web and not jStory bugs. For these reasons, it is recommended that you use audio and video to supplement your game, but not make it dependent on them.

Do not clear your browser's cookies (Safari calls it 'All website data'). This will also clear all of jStory's localStorage data for your game. You should be safe to clear your browser's cache, but test your version to be sure. I recommend regularly downloading your localStorage scenes to .json files for backup.

Licensing

You are free to make games with jStory and sell them or give them away. You are also free to modify any of the code to suit your game. But, you are not free to sell jStory or a modified version as a standalone product.

Errors

Most errors are going to be simple typos that cause the engine to perform in an unintended way. The current version of jStory is less error-prone, and will auto-correct many of the common syntax errors you might encounter, but not all. When an error or unexpected game output occurs, take note of the current index and check that index for typos. In most cases, this is where the problem lies. In other cases, where you might change a variable to the wrong value, and try to use it later on in the game, it can be more difficult to find.

If you've gone through all the available help resources and are still having issues, please contact me, and I will help you sort it out. If there is in fact a bug, I will be sure to fix it in the next update. Also contact me with any feature suggestions. I have many in mind already, but I will definitely consider new good ideas.