Advanced Chapbook Authoring

Authoring Twine
1

Twine : 2.6.2
Chapbook : 1.2.3

1.) Just curious if people know of any other moderate to advanced guides or reference materials for the Chapbook story format. Like, is there an API document?

So far, I’ve found:

➤ Twine Cookbook

➤ Chapbook Guide / Home Page

➤ Marion Sparkles’ Example

2.) Are there any known issues or bugs that I should be aware of with Chapbook?

3.) Are there any technically advanced Chapbook stories that people can recommend?

4.) Any words of advice with using Chapbook?

I was writing up my dream story format language over the course of a week (pretty common thing, I know ← sarcasm!) and came to the realization that I wanted less. I wanted as little as possible from the story format and for it to work with JavaScript/HTML/CSS as seamlessly as possible. Harlowe has been great for me, but Chapbook seems to be made for those who are familiar with web page development. Just providing a little context for my questions.

2 Likes
2

I am just starting with Chapbook myself. I’m finding it pretty stable, and there’s a lot of utility in the “backstage” CSS guides where you can change the formatting and get a block of code to paste in so when the game is exported it looks different. I know it’s not a big deal but I’m notoriously clumsy at these things, but I was able to import and display a Google font.

I’m starting to wrap my head around “every passage has a variables section and that’s the only place where variables get calculated.” Sort of like every page does the math pre-display. And if you can grok it more as a QBN style engine with “rules” on every card, it’s good. Multimedia is easy and useful.

I appreciate that it seems like Chapbook streamlines a lot of stuff. Potentially at the line of the total customization other flavors of Twine offer, but if you’re a writer moreso than a stylist and want to write choice IF without need for text-effect customization of Harlowe or wading through the staggering amount of options Sugarcube offers, Chapbook can produce a very nice story game without having to memorize a phonebook of documentation.

2 Likes
3

Much appreciated, Hanon. I really like how simple the CSS customization is. The default selectors (#page, #backdrop, etc.) are so nicely labelled and there isn’t much bloat to the existing styles (very easy to customize). The fact that it has built in headers and footers with left, center, right columns in each. *chef’s kiss*

I like the idea that Chapbook can be as complex or as simple as you need it. I really like that it forces you to simplify things… or construct them in steps before displaying them (like how you mentioned the variables being set at the beginning of the passage – that’s just reinforcing good practice).

I think I’m at an intermediate level, but without much to compare my understanding to, I don’t know. Like, can I easily check if the current passage contains any tags? I think so (I should be able to), but I can’t find that code for the life of me. Thus, I need someone to point me where to look… or how I can do it in JavaScript the way Chapbook’s creator intended.

I can’t be the only one trying to learn Chapbook… *crickets chirping*

1 Like
4

One common issue I’ve seen those moving to Chapbook from either Harlowe or SugarCube have is that (by default) variable assignments can only done in the Variables Section of a Passage, and that section is only processed during a Passage Transition.

eg. there is no official Chapbook equivalent of using a non-transitioning ‘setter’ link to dynamically update a variable…

:: Harlowe based Passage
Blah Blah
(link-repeat: 'Increase Counter')[
	(set: $counter to it + 1)
]

:: SugarCube based Passage
Blah Blah
<<link 'Increase Counter'>>
	<<set $counter += 1>>
<</link>>

…which can be a problem if the Author tries to make a Chapbook based project behave like a Harlowe or SugarCube based one.

note: It may be technically possible to implementing the equivalent of a ‘setter’ link, and I think at least one Author has done so.

2 Likes
5

Ah, yes. I appreciate you bringing that to my attention. I’m still playing with Chapbook, obviously, but I like how it’s setup to be extended. It is possible to change a variable mid-passage so what your saying is true:

test1: "Goodbye grey sky"
--
{test1}

[JavaScript]
engine.state.set( "test1", "Hello blue" );
write( engine.state.get( "test1" ) );
engine.state.set( "test2", "'Cause nothing can hold me" );
test1 = "When I hold you";
[continued]

{test2}

{test1}

…and there’s no reason not to be able to add this into a clickable link. I can see this as necessary for character creation passages where you have to assign skill points, like you mentioned.

So now I’ve got JavaScript that reads, modifies, and creates ( see test2 ) Chapbook variables. I’ve tested that they exist properly across passages so it’s working like it should and gets saved automatically when restarting a story. It’s a start, but it’s probably the most fundamental aspect of extending Chapbook so I’m pretty happy with that. Eat your heart out, Harlowe!

I also found out that Chapbook variables exist as regular global root JavaScript variables ( see test1 = "When I hold you"; ) so I have to be careful not to name any of my own functions and variables to that of my Chapbook story variables or hilarity ensues. It’s easily avoidable, but was unexpected nonetheless.

Another thing I’ll have to wrap my brain around is that, in Harlowe, I could refresh an entire section ( |hook> ) of a passage to reflect new variable data along with the nested conditions and such. I don’t think anything I want to do is reliant on that, but it was handy. Now I’m beginning to understand the sentiment of Harlowe encouraging the “nesting” of code logic.

I’m still on the hunt for more Chapbook documentation/resources, if anyone has any hot leads. Thanks!

6

I can’t believe I missed this, but the…

➤ Chapbook GitHub Repository

…contains all the source code for Chapbook.

I can see some low-level function calls within the built-in [modifiers] and {inserts} so it’s at least more than what I had before. It’s interesting to see how things are constructed (like how a link insert is rendered down to the HTML level). It’s not as caveman as I like it, but it’s understandable at least.

If I make any headway, I’ll be sure to share my findings in another topic. There’s so little out there for Chapbook, but I like the foundation of it quite a lot. Plus, I figure that if the author of Twine is behind it, there’s a good chance that it ain’t going away anytime soon.

Less is more, is my mantra.

7

Please do! I’ve been just dabbling and experimenting, but I’d love to see Chapbook in practice. I think it needs a good showpiece game to show it off well.

8

Me too! :wink:

9

What functionality should such a “good showpiece game” contain?

Chapbook’s main page and its GitHub repository’s main page both link to a Chapbook based implementation of the Cloak of Darkness specification.

1 Like
10

I only interject because I agree with Hanon. I also played Cloak of Darkness and reviewed the code.

No offense to those who like the game, but it’s not a showpiece. A showpiece is something that is outstanding. The Chapbook implementation of Cloak of Darkness is a good example of using Chapbook, but not something that creates a buzz to attract authors to the story format… which is how I interpret the term showpiece.

Good question. I have many thoughts about this, but essentially I think it needs to be something that looks and feels better than the competition. On the surface, the game needs to draw eyes and show a level of polish, but still look attainable by a novice. Maybe a collaboration with an artist is required.

Then it needs to showcase what is does best and what makes it unique. Simplicity is the key to authoring with Chapbook (because it really is so bare bones, but very capable). The basic markup implementation in Chapbook is really good too. The table/column one in particular is fantastic with only a couple of CSS styles to bring it out of the stone age. It has a good implementation of audio (something that Harlowe lacks completely). The Backstage testing environment is really good as well.

It needs to be honest, but not too honest because reading things like this in the Chapbook Guide as a reason not to use Chapbook…

You’ve invested significant time already in learning another story format. There’s nothing that Chapbook can do that other formats can’t. It may be easier to write with, depending on your point of view, but if you’ve already spent the time to learn how to write for another story format, it may not be worth the time investment.

…does itself no service whatsoever.

I wonder now if Chapbook might be the better default story format for Twine though (as much as a conflict of interest that might appear to be) because it does what it does so well that Chapbook novices can probably do what an intermediate Harlowe author can do. It’s that simple.

Harlowe can be intimidating at first, if one doesn’t know anything about programming. The Twine beginner angle is something to consider as a showpiece too. Maybe Chapbook’s Cloak of Darkness needs to elevate itself by providing the code displayed below for each passage. It’s like, own that simplicity. Showcase it. I’ve pushed Harlowe quite hard over the last 6 months or so and what I’ve discovered about Chapbook is that it embraces HTML, CSS and JavaScript better. That’s not a minor thing and something to promote with a story, as well. Also, the number of inserts and modifiers with Chapbook is surprisingly few. That’s something to admire and makes it very approachable.

I could blather on and on, but I think you know where I’m coming from. Maybe I’ll put my money where my mouth is, so to speak, and make something to draw eyes. I seem to be quite passionate about Chapbook right now, don’t I? :wink:

As a side note, I’ve been making my own {inserts} and [modifiers] with custom parameters today and Chapbook’s handling of this is simply amazing. I’m actually extending the native language of Chapbook. This really excites me, but I know I’m in the minority with that take because it requires a bit of JavaScript experience. I’m probably a beginner/intermediate JavaScript guy (I look up everything online for even the simplest solution). However, my goal is to share what I learn with the community here eventually.

1 Like
11

I think one major barrier for Chapbook becoming the default story format is that it doesn’t natively support the ability for an end-user interaction to dynamically updated variables or the page without doing a Passage Transition.

(and yes, it is possible to use JavaScript to extend the engine’s core functionality to allow such, but that isn’t something a beginner should be required to do)

Another possible barrier is Chapbook’s always enable auto-save system, which an Author can’t disable. Thus requiring the new Author to do a Hard Reset each time they want to use a generated Story HTML file to test the project.

note: I’m not advocating for Harlowe to stay the default Story Format. I’m just trying to point out the potentially wide requirement scope of new Authors, many of which have no background in software development or knowledge of web-based programming.

2 Likes
12

I always welcome your perspective on these things.

I’ve thought about this as well. I wish it could dynamically update parts of the current passage, but I’m not completely sold that it’s a bad thing for beginners. It’s one less layer of complexity. It’s also something that if a novice author decided that it is a hindrance, then they can change the story format as a deliberate choice. It’s almost like they’ve graduated from Chapbook and are ready for something more versatile. And I’m not advocating that Harlowe is a bad choice as the default story format either. I rather like Harlowe. I’m just pleasantly surprised by Chapbook at the moment.

To be honest, I’m not so sure Chapbook can be extended to allow that sort of live functionality, but there are usually clever ways around such things. I have a few ideas up my sleeve to try.

I never saw it that way before, but you’re right that it’s not very intuitive and potentially obtrusive. I removed the restart link only to later realize that I needed it for testing. I wonder if it’s easier in other ways though, when testing a large story, and not having to manage a save system to get back to the point you were at. It’s a catch-22 a bit, but the other formats do feel more logical in comparison.

There’s also no automatic passages assigned as headers and footers from what I can tell. That was a handy way to add functionality throughout an entire story.

It’s going to be an interesting journey, at least. :slight_smile:

I’ve contributed to the bug reports on GitHub already. Nothing show stopping, but surprising that the bug has been in the code for almost a year now. I wonder how often and to what degree Chapbook is maintained. Then again, Harlowe seems to have caused some issues regarding that requestAnimationFrame() flickering problem. Nothing is perfect, it seems.

13

Cloak of Darkness is a baseline test. When I say “showpiece” I mean a full game that everyone plays and inspires interest that shows off all its capabilities, often getting attention in a comp. Like “Detectiveland” made everyone go “I want to use this!” and Robin created Gruescript.

I suspect that’s by design. There are people who are creating straightforward choice narratives and I suspect it’s aimed more at authors who are just wanting to tell a story and not learn all of Twine’s extended macros and fancy tricks and customizations. Chapbook does this, creating a more finished-looking output by default than Harlowe or Sugarcube.

Chapbook is designed to be easy to work with as an author and generate output that is a pleasure to read by players. It provides sensible default behaviors for your story that can be customized to fit your particular needs.

I think if Chapbook came out earlier it would have been many people’s choice, but I think by now most who are into Twine have already settled down with Harlowe and Sugarcube and Chapbook may feel limited. That’s why I used AXMA - it did everything I wanted it to out of the box and produced a very nice finished product that allowed a little customization and handled multimedia well. I’m getting the same vibes now from Chapbook.

Right now I’m in the process of reconceptualizing a story to take advantage of Chapbook - There’s no save system but that can be an advantage based on the story type. I also agree it probably shouldn’t be default but it’s an attractive to new choice-narrative creators who are focused more on the text than doing extended tricks. If you want an RPG-like, Sugarcube is obviously better.

That’s one of my things I’m figuring out - how to do a stats-screen or inventory accessible from anywhere that will return to the correct passage. Axma had modal windows that made this a moot thing, but there was also system variables (I think something like $$previous and $$passage ?) that always held the current and previous passage names, so you could store that when temporarily directing away from the main text flow.

I did notice that Chapbook now has a toolbar with assistance once I updated Twine - which I hadn’t in a while and that’s majorly helpful!

1 Like
14

I’d say the main problem is indeed the autosave. It’s impossible to test any change or to valid that branching works as intended without having to start the story from zero each time. It means a long project is not possible with this format, the story has to keep short in order to allow playtest.

1 Like
15

This was quite noticeable to me as well. Chapbook’s default presentation is quite mature and sophisticated looking. And cross-fade transitions to boot! Harlowe can’t do that.

1 Like
16

I’ve used the Test button in Twine under the Build menu and there is a feature for testing called Snapshots under the State tab:

➤ State - Backstage

image
image752×342 5.61 KB

…so there is a save system dedicated for testing purposes. I checked it out and it re-writes all variables properly and returns you to the right passage. I believe it would be possible to use this for the end-user as well, but is not exposed because… Chapbook purposefully keeps things simple.

Edit: You can even edit the variables. You don’t have to grind to level up your character to 100 to test the final battle with the hellfire dragon in your epic 50 hour interactive fiction RPG game. There’s so much under the hood with Chapbook.

One of the hardest, yet important, design philosophies is addition by subtraction (or less is more). One of the best 3D NURB modelling software is Moment of Inspiration (or MoI 3D). It looks like a toy at a glance, but it’s so intuitively designed and bare bones. Many modellers, unfortunately, ignore it all together. The programmer behind MoI was one of the minds that built Rhino 3D. He purposefully agonizes over “adding features” because it comes at a huge cost of usability. Ease of use is something that not enough software designers adhere to.

Chapbook… you clever rabbit. :wink:

3 Likes
17

And that was the appeal for me. Such as how AXMA handled all the interface like saving and sound control and muting. The interface didn’t allow you to mess with it a whole lot except removing the back button or the options menu depending on what you were doing.

I personally found I experienced choice paralysis sometimes if the system gives me all the options at once.

1 Like
18

“Analysis paralysis” is my middle name. :wink:

19

Nice find, many thanks!

1 Like
20

I managed to add a link to the footer by adding it in the first passage’s var section.

config.footer.center: '[[Stats]]'

Found that by looking at the Cloak of Darkness demo.
If I added it into the backstage section it got reset after each restart.
That might be a quirk of the web version though.

2 Likes