[Docs] Guide regarding how the state works, particularly session state and `StoryInit`.

[ChapelR]

I've seen a lot of questions about how StoryInit works, what the difference between the session storage state and the autosave is, and generally about what happens when you click refresh on the browser vs restart in the UI.

I think a guide for this could be wise. I'm willing to write a rough version and PR it if it's something you think would be worth including.

[tmedwards]

Sure. Give it a shot.

[ChapelR]

I'll write something up this week.

[ChapelR]

Here's my initial draft if you have any feedback, particularly on the accuracy and terminology. You can reply here if you want, or over on the fork.

[greyelf]

suggestions: In "Moments" the "and the state of all story variables" part of the "Each moment contains data regarding the active passage and the state of all story variables (that is, the ones you use the $ sigil to interact with)" statement should make it clear that "state" of the story variables being associated with that moment is as was before the active passage was processed. Otherwise people may thing the value changers done within the active Passage are contained within that moment, which is something people have assumed with the Save system.

In "Session Preservation" the "stores the current state" part of the "SugarCube automatically stores the current state to the..." statement needs the same clarity as the above, in that the "current state" stored is as it was before the current passage was processed. Etc... for the other references to "current state"

[ChapelR]

I do include an example showing that moment creation happens on passage navigation and the saving is done on the last moment.

A new moment is created whenever passage navigation occurs. …

Saving the game records the game's state up until the last moment that was created. This is not necessarily the same as the current state of the game. Consider the following: …

[example] …

In the above example, if you save the game after reaching the passage called another passage, the $var variable will be saved in the state as 1 as you would expect. If you click the link that sets the variable to 2, and then save the game, the $var variable will still be saved as 1, because a new moment has not yet been created.

I can call more attention to this, maybe.

[greyelf]

I just think attention to that fact needs to be as early as possible, while you have their first attention and before they can form an opinion that the stored state includes the current variable changes.

[ChapelR]

I just think attention to that fact needs to be as early as possible, while you have their first attention and before they can form an opinion that the stored state includes the current variable changes.

I'll see what I can do.

[tmedwards]

There are a few non-entirely-correct bits, which I can fix up later, but overall I like it. 👍

---

Notes

Under the What Happens When a Save is Loaded? section, the comments for the example don't match the examples themselves, which are both missing a variable—$y in the first, and $z in the second. Either the examples or the comments need adjusting.

Also. I think it would be nice if those and the example in the Refreshing and Restarting section matched, so if you drop the mention of $z from the comments in the former set, I'd drop setup.z in favor of setup.y in the latter. OTOH, if you add vars to the former, then you'd be good as-is in the latter.

[ChapelR]

I made some adjustments to the example, so I must've just messed that up. I'll fix all the examples according to your suggestions. I'll do another pass incorporating @greyelf's suggestions too then submit the PR.

[tmedwards]

Interested parties might want to give the guide a look over. I did make some changes.

[ChapelR]

Last sentence of the first paragraph under Autosave:

It can loaded manually by the player or automatically by the autoload feature...

Should be

It can be loaded manually by the player or automatically by the autoload feature...

Other than that typo I think it looks great. All smart and sensible edits.

[greyelf]

Unless a pun was intended the...

we'll cover that in a moment

...comment might be better written as...

we'll cover that shortly

[tmedwards]

Did a bit more tweaking/rewriting.