Sugarcube - Should I add to setup object via javascript or passages?

Sugarcube 2.31.1

I’ve read that it’s better to put objects on the setup object for storage reasons, but now I’m wondering if it would be better to do it in a passage or in the javascript section? I’ve seen examples of both and just wondering if one is particularly better…

In passage:

<<set setup.mushroom = {

    "name":     "mushroom",

    "size":     ["small","light"],

    "shape":    ["round","domed"],

    "age":      ["young"],

    "colour":   ["grey","brown","pale"],

    "origin":   ["comes from the ground","grows in damp places"],

    "material": ["spongy","soft","flexible","alive"],

    "special":  ["many different kinds"],

    "purpose":  ["edible","can be poisonous"]   


Or in the Javascript section?

setup.egg = {
	name: 	"egg",
	loc: 	["forest","swamp","mountain"],
	app: 	["amber","green","blue"],
	type: 	["chicken","stork","eagle","elemental","dragon"],
	cond: 	["chipped","cracked","pristine"]	

I’ll probably be making LOTS of these fyi.


I don’t think it matters? But you should only do it for constant data (objects that never change over the course of your story), and if you want to do it in a passage, it should be StoryInit (otherwise you’re not guaranteed that they’ll exist if a user stops playing and reloads the page to continue later). Or a passage that you <<include>> from StoryInit? I seem to remember that someone felt very strongly that that was a bad idea, but I looked at the source code for SugarCube and didn’t see an obvious technical reason for it, so I think it was just a personal stylistic opinion.

1 Like

The location where you put that code only matters if there’s some other code which needs that data during the Twine/SugarCube “startup sequence”.

When you first start a Twine/SugarCube game it loads things in the following sequence (see the “Refreshing and Restarting” documentation):

  1. CSS is loaded from the Stylesheet section(s)*.
  2. JavaScript in the JavaScript sections(s)* is run.
  3. Code in any “widget” tagged passages is run.
  4. The StoryInit passage is run.
  5. One of three things happens next:
    A. If an existing session exists (such as if the player hit the “Reload” button in their browser) the play session is restored and the current passage is run.
    B. Otherwise, if a save or an autosave is to be loaded, it will load that session and continue from there.
    C. Or, if neither of the above happen, then the starting passage will be run.

(*: Command line Twine compilers, such as Tweego, allow you to have multiple “stylesheet” and/or “script” sections.)

All that means is that, if any of those sections need your data on the setup object, you’ll need to create that data either earlier in that same section or a section which is run earlier. Otherwise, it doesn’t really matter where you put it, as long as it’s in one of the JavaScript, “widget”, or StoryInit passages.

Hope that helps clear things up! :slight_smile:


Thanks heaps Josh! Your answer with HiEv’s below is v. helpful.

Oh I didn’t realise <> in StoryInit was a bad idea! I do that all the time lol :confused:

Wanted to mark this as solution also. Thanks for the thorough reply! I always learn so much from your posts!

So combining Josh’s advice with yours, are you saying that if I just put these setup objects in a non-special passage that’s essentially bad because if someone has a save game in a passage beyond that passage, when they resume the autosave or whatever, those objects won’t exist?

I think I get it now… adding to the setup object has the advantage of conserving memory but the disadvantage of having to be setup in the…well…setup of the game (not wherever I like) lol. Is that a fair summary?

1 Like

Basically, yes. Since data on the setup object isn’t saved with the story variables when the player saves the game, it’s best to only use that setup object for static (unchanging) data and/or your own custom functions, since otherwise any changes would be lost when the player reloads a save and that setup data gets reset to the “default” values given in the “setup” sections.

Also, while using <<include>> in your StoryInit passage will work, I personally don’t like it because it can make debugging more difficult. That’s because the code would spread out over multiple passages, which makes it easy to overlook how one chunk of code might adversely affect another chunk of code and it makes it harder to debug. If you want to break your StoryInit into “chunks”, I’d recommend using comment blocks instead. So your code might look something like this:

/* Variable setup section - Start */
(code goes here)
/* Variable setup section - End */

/* Function setup section - Start */
(code goes here)
/* Function setup section - End */


There are a couple of ways to do comment block markup, but this particular markup /* ... */ works in all sections of your code (passages, the JavaScript section, and the Stylesheet section), so I’d recommend using that markup for your comments.

Also, using <<include>>s in the StoryInit passage means that you’re unnecessarily creating more passages, and that can eventually lead to slowing down the Twine editor if you have too many passages.

However, if you’re fine with all of that, then it’s OK to use <<include>>s in your StoryInit passage.

Hope that helps clear that all up! :slight_smile:

1 Like

Wow brilliant thanks this is very informative! After reading this I went and changed the whole structure of my story!

Luckily it was pretty straight-forward because I’ve just discovered how to split up Twee files now and compile them all together. I feel like I’ve entered some kind of golden land!