Howdy, Stranger!

It looks like you're new here. If you want to get involved, click one of these buttons!

Practical difference between SugarCube PassageReady and PassageDone?

edited June 2015 in Help! with 1.x
I'm trying to work out the difference between PassageReady and PassageDone in SugarCube. Is there any difference other than PassageDone happening marginally later than PassageReady?

In my story I use PassageDone for some things but wondering if PassageReady would be better. I use it to activate background image changes I want to happen 100ms after a passage is ready to be displayed, so it starts with a <<timedcontinue 100ms>> then the code. I find this makes it smoother than just plugging everything into the individual passages, and the browser seems more comfortable with the enforced order. It likes to work out what it's displaying in the passages before it implements my image display code.

Probably due to the timedcontinue there wouldn't be any practical difference, but just wondering how each work. I use PassageDone because I want the browser "done" with its passage display tasks before it starts looking at my other code.


  • @Claretta
    I'm so glad you asked this out in public.

    I know you could have asked TME (or even GreyElf) directly since this seems like such a high-level question.

    I can think of maybe 7 people on this site who could answer it, while most of us don't even know what it is.

    However, since you put it here, now I think I want to start coding it your way where before
    it had never even occurred to me.

    Thank you.
  • edited June 2015
    I suppose the main difference would be you could put:

    <<set $variable to 1>> in PassageReady and it would affect what's in the passage, whereas you'd put <<if $variable is 1>> in PassageDone and it would go off variables set in the passage?

    I'm struggling to think of why you'd want to use PassageReady like that, but then it didn't occur to me to use PassageDone until not long ago, either.
  • edited June 2015
    Claretta wrote: »
    I'm trying to work out the difference between PassageReady and PassageDone in SugarCube. Is there any difference other than PassageDone happening marginally later than PassageReady?
    They occur at different points during passage display, that's all.

    The exact differences are outlined in the Passage Names section of the Special Names docs. To reiterate:
    • PassageDone: Used for post-passage-display tasks, like redoing dynamic changes (happens after the rendering and display of each passage).
    • PassageReady: Used for pre-passage-display tasks, like redoing dynamic changes (happens before the rendering of each passage).
    This may make more sense with a bit of context, so let's expand on that a tad.

    The PassageReady/PassageDone special passages and the Task objects (prehistory, predisplay, prerender, postrender, and postdisplay) are similar in that they both allow you to do dynamic things around the display of a passage (by navigation, the <<display>> macro does not trigger any of these).

    The order of execution for passage display (again, via navigation) looks like this:
    1. prehistory tasks called
    2. State history updated for the incoming passage
    3. <body> element classes cleared, if not rendering "hidden"
    4. predisplay tasks called, if not rendering "hidden"
    5. PassageReady executed, if not rendering "hidden"
    6. Incoming passage is rendered, which consists of:
      1. Classes generated from passage tags added to both the .passage and <body> elements
      2. prerender tasks called
      3. Incoming passage content rendered into HTML objects (not yet part of the DOM/page)
      4. Rendered content transformed into more sane HTML, if configured (SugarCube 2.x only)
      5. postrender tasks called
    7. Transition from outgoing passage to incoming passage, if not rendering "hidden"
    8. PassageDone executed, if not rendering "hidden"
    9. postdisplay tasks called, if not rendering "hidden"
    10. Update UI "story" elements (i.e. those populated from StoryCaption, StoryMenu, etc), if not rendering "hidden"
    11. Post-processing for accessibility (SugarCube 2.x only)
    12. Autosave, if configured
    Now you know. And knowing is half the… wait, my '80s is showing.
  • GI Joe!!!
  • Thanks for that. Yeah, just knowing the exact order of stuff was helpful.

    I'll stick with PassageDone to keep my code in the proper order.
  • edited June 2015
    Reading this, there seems no reason that I should need that 100ms buffer.

    And indeed, after cleaning up my code so that the browser only has to process what's absolutely necessary on passage transitions, I don't need it anymore. PassageDone in itself provides the necessary ordering.
Sign In or Register to comment.