Skip to content

Creating A Scene Config

Jump to bottom
Logodaedalus edited this page Dec 17, 2018 · 26 revisions

Summary

The scene config file is where you put all the information that tells StoryAssembler the details of how to use your content file to tell a story. Characters, goals, content libraries, even how characters are displayed is all set here.

If you're trying this for the first time, your best bet is to open up the example.json file in js/StoryAssembler/data/scene-configs and see how it works, and even just duplicate it and change the values (but be careful you step through each one and update it for your scene, as forgetting to change one may result in strange bugs that are hard to trace).

Because we use HanSON to parse it, you can use // to comment the file (as in example.json).

File Components

id

This is the id your scene has in the game, and the value you'll put into Coordinator.js to hook it up

characters

A character is a collection of custom template values and avatar states, packaged together under an id

  • Id: The unique identifier for your character
  • AvatarStates: This tells StoryAssembler when to display a particular avatar for your character.
    • The easiest one is done by just putting default in the array, which tells StoryAssembler to use that picture as the default one for the character, if no other avatars are valid.
    • They use the same state format as conditions in fragments, i.e. tension gte 2, which means "the state variable tension is greater than or equal to 2".
    • They're in an array, so ["tension gte 2", "friendliness lt 5"] means that particular avatar will only display if both are true
    • the arrays are "anded" together (so if even one state condition isn't true in them, the avatar won't display)
  • Example:
  • {
    "id" : "protagonist",
    "avatarStates" : [
    { "state": ["default"], "img": "assets/avatars/char3/char3_20s_neutral.png"},
    { "state": ["tension gte 2"], "img": "assets/avatars/char3/char3_20s_disappointed.png"}
    ],
    "properties" : {
    "name": "Emma",
    "nickname" : "Em",
    "pronouns" : "she"
    }
    }

wishlist

A wishlist is a list of state conditions StoryAssembler will pick fragments to meet. Their basic format is [state variable] [comparison operator] [value] (for example, tension gt 4)

  • state variable: any word that doesn't contain special characters or spaces. Valid example: tension, char1Anger, possessesSecretPlotItem
  • comparison operator: gt (>) lt (<) gte (>=) lte (<=) eq (==)
  • value: any string or number

Advanced

  • You can add "persistent": true as a property, which means storyAssembler will constantly pick fragments to satisfy that. Keep in mind such wishlist items won't gate scenes from finishing, as they're never technically "satisfied".
    *Ex: { "condition": "friendly eq true", "persistent": true } (always prefer content with effects that set "friendly" to true)
  • You can force a wishlist item to be evaluated first or last using "order" : "first" or "order" : "last". Since wishlist items are evaluated in order (although it will satisfy out of order if, for example, item 1 2 and 3 aren't satisfiable but 4 is) you can use this as a bit of a cludge to make sure wishlist items that are towards the end of the scene don't get satisfied at the very beginning. *Ex: { "condition": "outro eq true", "order" : "last" } (_after checking to see if any other wishlist items are true, check to see if you can pick something that sets "outro" to true)

dataFiles

An array of files that can be used in your scene. Because you can use multiple files, this means you can split up authoring tasks by beats or other criteria into separate files, to make it easier to collaborate, or even re-use files between scenes to get more mileage out of certain content.
Files are listed as "text![filename alias]", where [filename alias] is the alias you gave the file in main.js when you added it in there.

  • Ex: "text!globalData"
  • Ex: "text!introSceneData"

startState

An array of commands that set up the state for your scene. These are run before the scene starts. They take the form set [variable name] [variable value] where [variable name] is any string and [variable value] is any string or number.

  • Ex: "set establishSetting true"
  • Ex: "set friendConfidence 5"
  • Ex: "set favoritePet caterpillar"

sceneBackground

The image that's displayed as the background in this scene. Path should be relative from the root folder of the project. By default the background is set to cover everything and sit on the bottom of the screen, but you can change that by editing css/styles.css

UIvars

These are the variables to display next to character avatars, RPG-style

introText

The HTML displayed at the beginning of your scene.

outroText

The HTML displayed at the end of your scene.

fallbackOutro

The HTML displayed if StoryAssembler has an error when set to "release" mode. This makes it so that your scene can gracefully end if the reader encounters an edge case that you haven't caught yet in debugging!

descriptionText

If timeline view is selected, the HTML to show for this scene.

Clone this wiki locally