I take it the browser's internal storage area something that's separate from the cache (which would present issues in itself if the cache was flushed)?
I assume that Twine 2.0 uses Web Storage at the moment, which means that yes, it's totally separate from the browser's cache.
AntonMuerte wrote:
If this is the case, is there no way of at least letting the user know where the file is and what it's called so they could sync it themselves?
(Assuming the above is correct.) Not really. Most, if not all, browser's handle on-disk storage for Web Storage by using a binary blob of some kind, generally a database (e.g. Firefox uses SQLite for this and most other things, I wouldn't be surprised if others do as well). It's not something you can easily swap in and out at will.
IMPORTANT: This version changes the story output format
What this means is if you have saved archive files from preview 1 or 2, you must import them in this version and then re-export them in order for them to work in the future. We've changed the output format for stories a little bit, but preview 3 can read both old and new formats. This won't be true in future versions.
Enough scary stuff, this is what's new
You can now hold the space bar to pan around the story.
Basic marquee selection is available on desktop OSes -- you can select passages and drag them around, but mass deletion isn't implemented yet.
There's now syntax highlighting for the JavaScript and stylesheet editing dialogs, thanks to Ross Smith.
We now have Test and Test From Here buttons thanks to Leon.
Just a note about Preview 3... the Twine passage syntax highlighting I tweeted about yesterday is still being hotly developed, so expect to see it in the version after this one.
Bug, maybe?: Whenever I try to edit a passage, the text window is grayed out and while I can write in it, I can't click the "done" button (or anything else at all). I'm running Firefox on Windows Vista.
I want to make a few remarks regarding syntax development that I've been just reserving for Twitter...
1. I've mentioned here and there that I've been working to change the macro and function syntax, so that macros and functions use the same syntax. I've chosen for now to make macros use function syntax, so, for instance, <<checkbox "Pearls" "Peas">> is now checkbox("Pearls", "Peas"). This has a number of advantages. I found that I'm not alone in thinking the double-chevron markers << and >> to be a tad cumbersome - even though they may be visually striking, they somewhat hinder <<print "readability">> in the midst of passage text, so forgoing them is probably a net boon. Also, the TiddlyWiki macro style didn't, in my opinion, make the distinction and separation of macro name and parameters clear - unless you're familiar with HTML, it isn't immediately apparent that the word "display" in <<display previous()>> is a different kind of entity to "previous()" - and, it isn't obvious how many parameters <<set $red to 1>> and <<checkbox "Gold" "Myrrh">> each have, as the second separates two distinct expressions with only whitespace.
You might wonder how a plainer syntax like function() is programmatically distinguished from ordinary English prose (with its own parentheticals). The rule is: the function name must be a single word, and there must be zero whitespace between the name and the open-bracket (, for it to be considered a macro.
2. Actually, I must admit that instead of just changing the syntax, I've done something more radical: made it so that macros and functions are structurally the same thing, and can be used interchangeably. So, you can type either("caterpillar", "worm") directly into passage text, and take the passage text returned by a display() and manipulate it as a string. This, I feel, produces a much simpler conceptual model for Twine coding. For one thing, one could create both "functions" and "macros" using shorthand <<display>>: create an "antagonise" passage that returns certain story-specific values, then call it with antagonise().
3. Now, how does <<if>>, <<else>> and <<endif>> work with this syntax? Well, first, let's look at [hooks][1]. I've introduced hooks as the primary syntactic structure for squaring off sections of passage text for special treatment. So, it's only logical that I extend this to the design of the if() macro - instead of putting the nametag at the end of a hook, put an if() macro at the start:
if(visited("magicbath"))[Your magically induced cleanliness repels the Gunkwads's advance!]
The hook is only displayed if the if()'s expression is true. Thus, the [ and ] replace the need to delimit text with the <<endif>> macro.
if($blush < 4) [Your face is pink.] else() [Your face is sheer crimson.]
The else() macro looks behind to see if the previous if() was true or not, and displays if it's so.
The "if()" macro actually internally works like this: it returns a simple JS function (a "hook augmenter") which, when occurring immediately before a hook, transforms the hook in some way. In the case of if(), it removes the hook if it's false. But it suggests other macros could be developed easily - a transition() macro could make a hook transition in with a specific animation, for example - and in a much simpler manner than is possible in Twine 1.
All of the above are very recent developments and I'm still weighing up how they'll work, but I'm enthusiastic that these continue the design goals I've been furthering.
You might wonder how a plainer syntax like function() is programmatically distinguished from ordinary English prose (with its own parentheticals). The rule is: the function name must be a single word, and there must be zero whitespace between the name and the open-bracket (, for it to be considered a macro.
If an Author wishes to have a multi-word function name, for example check_stats, using whitespace characters between the words for readability (does not have to be underscore, could be dash), will they now have to use something like Camel Casing instead? (eg: CheckStats or checkStats)
How does this effect readability, as it considered less readable by many people.
Because java-script is case sensitive, will this lead to more problems/errors? (eg: CheckStats and checkStats are considered different functions)
L wrote:
if($blush < 4) [Your face is pink.] else() [Your face is sheer crimson.]
How would you write the following using the new if() and else() functions?
I omitted to mention that by "word" I'd somewhat foolishly mean the RegExp "word class" \w, which includes _. (Actually the code re-uses the TiddlyWiki "anyLetter" class, which is somewhat broader than just the ASCII letters.)
Twine 2 expressions are planned to be case-insensitive.
You can write nested if() (at least, of the kind you've given) in a style that's a little embarassingly C-like:
if ($var is "value1")[ if ($var is "value2") [ ] ]
Since my last post, I've been pondering an easy shorthand to make macros nest - to write <<click ?1>><<replace ?2>> with this function-call syntax.
I tried implementing it so that you can simply place functions sequentially before the hook, and write it like so:
click(?1)replace(?2)["Some text"]
This follows the C tradition of omitting the curly braces for single-line if-statement clauses (a practice that, for the record, many regard as a flaw.) But that aside, I don't really like it much in retrospect, because "click(?1)replace(?2)" doesn't make sense as an expression inside a macro - you can't do "either(1,2)either(3,4)" inside a macro.
I'm wondering what to consider next. Recall that the present means of writing it is this:
click(?1)[replace(?2)["Some text"]]
which is a tad cumbersome, owing to the nesting of the square brackets.
I'm also wondering how to implement <<continue>>. You may recall that macro's main virtue is that you can drop it into a passage and omit the closing <<endcontinue>> - it regards all text afterward as being in its enclosure. Currently, the enclosure macros use explicit hooks as their enclosures, and can't switch any "mode" that causes the following text to fall into an "implied hook" that they control.
(I feel that the conceptual model used by Twine 1 users for understanding <<if>><<endif>> etc. is to think of them as modal - <<if>> turns on the if-macro "mode", and <<endif>> turns it off. This is contrary to how most proglangs implement if, and more saliently how I've been implementing and designing Twine 2's macros, but is aligned with how the text formatting syntax of Twine works - // switches italics on and off, etc. Modality, as we know, is a limited conceptual model to implement a proglang in, but it does provide something of an intuition handle for new users.)
Really, the big questions I'm grappling with are whether A) overloading the hook syntax for inline macros' enclosures is a good thing, and what other alternatives are there.
If this is a little confusing, let me reiterate. Currently I'm quite satisfied with the fact that macros can reference hooks (enclosed spans of text) from afar using the hook syntax:
...in the middle of a paragraph, just a few square brackets instead of long unwieldy macro tags... The man turns to you, and utters [a greeting.][1] You stand stock still.
...bottom of the passage, like a footnote... <<click-replace ?1>>"Good morrow!"<</replace>>
This satisfies my separation-of-text-and-code goal. But! There are altogether too many common cases where a little bit of code should be next to a lot of text. Consider a common case like:
<<if $logs >= 2>> <<if $fire is false>>The logs have arrived. <<else>>The logs are burning. <</if>> <</if>
It would be a tad convoluted if it was rendered thus:
[The logs have arrived.][1] [The logs are burning.][2]
In this particular case, keeping the short, curt conditions guarding alternative spans of text aids readability instead of detracting from it. So, there should be a way to make Twine 2 macros 1) refer to a nearby hook, anonymously, to save having to explicitly name them for a one-time referral, while... 2) remaining as lightweight, syntax-wise, as possible, and being "natural" to read (at least as natural as Twine 1's <<if>> is).
My current solution, to make the macros automatically refer to hooks by immediate placement, is one I'm finding myself grow wary of for reasons outlined prior.
....
This seems a dour note to end this post on, so I'll try and make up an alternative on the spot, right now. Hmm...
if($a > 4, do this) [ .... ] replace(?a, with this) [ .... ] click("kitten", do this) [ .... ] if($a > 7, do ?1)
replace(?a, with ?b)
click("kitten", do ?dogs)
This suggestion alters the enclosing macros (if, replace, click) with an extra keyword "do" (for conditonal macros like if or click) or "with" (for transformative macros like replace or append), which determines the target of the macro (specifically, what its enclosure is). The special keyword "this" specifies that its target is the very next anonymous hook - thus its targeting is explicitly stated rather than implicit. Of course, it has its obvious issues - the "do" clause being in parameter position sort-of makes sense (insofar as the target is indeed an input to the macro) but could be confusing and insufficiently memorable to users.
(I feel that the conceptual model used by Twine 1 users for understanding <<if>><<endif>> etc. is to think of them as modal - <<if>> turns on the if-macro "mode", and <<endif>> turns it off.
Would a modal "if" be nestable? I think that would be a very desirable property, but unless I'm misunderstanding what modal means it would not be possible to have nested modal "if"s.
L wrote:
...in the middle of a paragraph, just a few square brackets instead of long unwieldy macro tags... The man turns to you, and utters [a greeting.][1] You stand stock still.
...bottom of the passage, like a footnote... <<click-replace ?1>>"Good morrow!"<</replace>>
The <<macro>> syntax is useful for inlining macro into text, but if you have a separate code section, a different syntax could be easier to type and easier to read as well. The close tag in particular is overkill, plus in the example it doesn't match the open tag, which is either a typo or a shorthand that the user would have to remember.
Some possible alternative syntaxes:
...in the middle of a paragraph, just a few square brackets instead of long unwieldy macro tags... The man turns to you, and utters [a greeting.][1] You stand stock still.
...bottom of the passage, like a footnote... ...function calls with space-separated arguments: click-replace ?1 "Good morrow!" ...really make it look like a footnote by putting hook first: ?1 click-replace "Good morrow!" ...JavaScript-like with hook support... ?1.onClick = replace("Good morrow!")
By the way, numeric hook labels look good in examples, but I have some doubt it works well in practice: as you rewrite your passages, hooks will get inserted and removed and the numbers will no longer be in sequence. I think text labels would be better than numbers. (Of course a number is a special case of a text label.)
L wrote:
<<if $logs >= 2>> <<if $fire is false>>The logs have arrived. <<else>>The logs are burning. <</if>> <</if>
It would be a tad convoluted if it was rendered thus: [The logs have arrived.][1] [The logs are burning.][2]
Does this mean hooked text is invisible by default? Otherwise the second code fragment doesn't do what it's supposed to do.
L wrote:
if($a > 4, do this) [ .... ] replace(?a, with this) [ .... ] click("kitten", do this) [ .... ] if($a > 7, do ?1)
replace(?a, with ?b)
click("kitten", do ?dogs)
I'm wondering: if you're going for a C-like macro language, wouldn't it be possible to use JavaScript instead? Maybe with a small extension to be able to use it inline and work with hooks, but mostly just JavaScript. It would reduce the number of languages that users have to learn to get the most out of Twine.
Sorry for not answering the actual questions that you were asking, but I'm having a hard time deducing how the proposed language would work from examples. To be able to discuss a language design without the risk of miscommunication, I think a more formal description of the language is needed.
(I feel that the conceptual model used by Twine 1 users for understanding <<if>><<endif>> etc. is to think of them as modal - <<if>> turns on the if-macro "mode", and <<endif>> turns it off.
Would a modal "if" be nestable? I think that would be a very desirable property, but unless I'm misunderstanding what modal means it would not be possible to have nested modal "if"s.
Twine 1 (and Twine 2)'s "if" isn't modal, and moreover would not be advantageous to be implemented as modal, but I suggest that users conveniently think of it as if it's so (as compared to its actual implementation as a function that takes an expression and a block of passage text as inputs.)
mth wrote:
The <<macro>> syntax is useful for inlining macro into text, but if you have a separate code section, a different syntax could be easier to type and easier to read as well. The close tag in particular is overkill, plus in the example it doesn't match the open tag, which is either a typo or a shorthand that the user would have to remember.
Yes, that was a mistake in the post.
mth wrote:
Some possible alternative syntaxes:
...in the middle of a paragraph, just a few square brackets instead of long unwieldy macro tags... The man turns to you, and utters [a greeting.][1] You stand stock still.
...bottom of the passage, like a footnote... ...function calls with space-separated arguments: click-replace ?1 "Good morrow!" ...really make it look like a footnote by putting hook first: ?1 click-replace "Good morrow!" ...JavaScript-like with hook support... ?1.onClick = replace("Good morrow!")
Space-separated arguments is not good, because if people would pass operator-based expressions in argument position (e.g. if($red > 3)) then they'd either need to square-off said expressions with brackets (e.g. examine(($red > 3) "Halt!")), or we'd have to only permit operator expressions in single-argument macros. This is a problem I currently have with <<display>> in Twine 1: you can't pass operator-expressions to the shorthand version because it treats arguments as space-separated, so <<something $red > 3>> would set parameter(0) to $red, parameter(1) to ">", and parameter(2) to "3".
Hook-first doesn't really work either because A) it wouldn't be too readable for pseudo-hooks (i.e. "click-replace "bear" [dog]" would become ""bear" click-replace [dog]") and it wouldn't work too well for if(), either(), etc. You should be able to write click(?1)[ replace(either(?1, ?2, ?3)) [...]].
mth wrote:
By the way, numeric hook labels look good in examples, but I have some doubt it works well in practice: as you rewrite your passages, hooks will get inserted and removed and the numbers will no longer be in sequence. I think text labels would be better than numbers. (Of course a number is a special case of a text label.)
My use of numbers is purely a case of hurriedly written example code - it actually allows any string of non-] characters as a hook tag. (Which is a bug - it should just be anyLetter or \d characters.)
mth wrote:
L wrote:
<<if $logs >= 2>> <<if $fire is false>>The logs have arrived. <<else>>The logs are burning. <</if>> <</if>
It would be a tad convoluted if it was rendered thus: [The logs have arrived.][1] [The logs are burning.][2]
Does this mean hooked text is invisible by default? Otherwise the second code fragment doesn't do what it's supposed to do. I wasn't really thinking straight when writing this - the meaning of the macros isn't supposed to matter, except insofar as they perform an action upon a hook.
However, it does remind me of an ongoing issue, that there isn't yet a good (not hacky) syntactic means of declaring a hook "inactive" initially, which is bound to be useful, as this hypothetical show() macro does feel like it would be a convenient idiom.
The problem I have with the hook / annotate concept is that it does not handle more complex structures like nested substitution and that the related code portion is also embed within the passage text which is easy to mistake for a normal IF/ELSE/ENDIF statement set. *note: code structure from an actually game, content changed because it is not mine. Formatted for easy reading. *
The quote was <<if var1 = 1>> "The quick <<if var2 = 1>>brown<<else>>red<<endif>>fox jumped over the <<if var3 = 1>>lazy dog<<else>>sleeping cat<<endif>>." <<else>> "Now is the time for all good......." <<endif>>
I wonder if extending the concept so that it behaves more like document annotating, were you mark the text and then add the instructions/comments about the marked text somewhere else (eg: external to normal passage text) and I would change the background colour of the marked text so it stood out.
So the above example would be something like the following: pretend that the background colour of the highlight text is red, not the foreground
The quote was "The quick brown fox jumped over the lazy dog[1]."
// This is the code related to annotate 1. // note: original contents of annotate stored in $text variable. Code is natural java-script but could be anything. // The replace method is friendly version of real String.replace() function.
if (var1 != 1) { $text = "Now is the time for all good......."; } else { if (var2 != 1) { $text = replace($text, "brown", "red"); } if (var3 != 1) { $text = replace($text, "lazy dog", "sleeping cat"); } }
The problem I have with the hook / annotate concept is that it does not handle more complex structures like nested substitution and that the related code portion is also embed within the passage text which is easy to mistake for a normal IF/ELSE/ENDIF statement set.
This is a concern I have - that by providing the option to use macros within the passage, then it will be used at the expense of readability. The problem is, I currently feel that the fluency that comes from tastefully putting a tiny conditional next to a large span of passage text, instantly communicating what branch or conditional is bound to it, is too desirable to pass up.
...But maybe I'm not thinking hard enough, as usual. Maybe it should be the hook tags that should carry this burden?
if($item is "Chalice")[ Wielding the chalice, you bravely.... ....................................................... ] elseif($item is "Medallion")[ The medallion? Of course!....................................................... ....................................................... ] else()[ You mount a spirited defense, but ....................................................... ]
My sensation has been that the above, representing the current state of affairs in Twine 2 syntax, is generally preferable to this:
[ Wielding the chalice, you bravely.... ....................................................... ][a] [ The medallion? Of course!....................................................... ....................................................... ][b] [ You mount a spirited defense, but ....................................................... ][c] ------- if($item is "Chalice")[ show(?a) ] elseif($item is "Medallion")[ show(?b) ] else()[ show(?c) ]
BUT, maybe it could be rewritten like so:
[has_chalice][ Wielding the chalice, you bravely.... ....................................................... ] [has_medallion][ The medallion? Of course!....................................................... ....................................................... ] [has_neither][ You mount a spirited defense, but ....................................................... ] ------- if($item is "Chalice")[ show(?has_chalice) ] elseif($item is "Medallion")[ show(?has_medallion) ] else()[ show(?has_neither) ]
Hmm...
Notice that in that one, the hook tags prepend the hooks... I've regarded this as inferior readability-wise in the case of an inline hook:
You ready your [1][crystal] shield and sally forth.
(Scalability is always at mind when thinking of syntax design concerns.) Although - I recall I made the link syntax bi-directional by way of the "arrow" (that is, [[Link text->passage name]] and [[passage name<-Link text]]) so maybe I could make the hook tag bidirectional as well. Something like this?
It's vaguely but reassuringly reminiscent of a gift tag, with its triangular shape.
OK, now let's try this again:
[has_chalice>[ Wielding the chalice, you bravely.... ....................................................... ] [has_medallion>[ The medallion? Of course!....................................................... ....................................................... ] [has_neither>[ You mount a spirited defense, but ....................................................... ] ------- if($item is "Chalice")[ show(?has_chalice) ] elseif($item is "Medallion")[ show(?has_medallion) ] else()[ show(?has_neither) ]
I'll admit - it's a small difference, but def some kind of improvement. I'll think about it.
Hooray, preview 4 is out! This is the last preview release before we move to beta (e.g. all features for 2.0 have been added and the releases are strictly for fixing bugs). You can try it online at http://twinery.org/2 or download it for offline use at https://bitbucket.org/klembot/twinejs/downloads.
Major changes in this release:
Revised UI, in particular a new editor toolbar
Test buttons on both the story toolbar and on individual passages (e.g. the "Test From Here" functionality in Twine 1.4)
Quick find field that highlights passages in the story map that match a search term
Find/replace dialog box for making changes storywide (still a bit rough)
Passages can now have tags added and removed
Amount of browser local storage space left is shown on story list page
Font based icons not displaying correctly when using Firefox 31 on Windows 7. They do display correctly when using Chrome 36 and Internet Explorer 11 on same machine.
Font based icons not displaying correctly when using Firefox 31 on Windows 7. They do display correctly when using Chrome 36 and Internet Explorer 11 on same machine.
The problem was that although "NoScript" was allowing the downloading of "font-awesome.min.css" because it is directly referenced in the HTML page, it was NOT allowing the download of the fonts listed within the css file.
To fix I had to add an extra rule for "netdna.bootstrapcdn.com", so the problem was my end.
I suppose an apology is in order... my aim of getting syntax-highlighting into this release has come to naught. The troubles were several: balancing day work, consolidating the implementation of various Harlowe syntax changes and the engine, pains at trying to implement a CodeMirror mode for Harlowe's syntax, the ongoing necessity of making the Harlowe parser performant enough in different browsers, and of course fear and shame at getting behind in these responsibilities.
What I should do now is at least introduce the syntax changes that haven't made it into p4, but which are ready to be included. I've already discussed several of these in previous posts, but I feel a confident reintroduction is in order.
* You can print variables by placing their names in the passage text. In preview 4, you can write:
<<print $red>>
In the next release, you can shorten that to
$red
You may note this is even smaller than Twine 1's shorthand print - <<$red>> - and more aligned with the conciseness of HTML templating engines. But, note that, like the Twine 1 shorthand, you can't include full expressions here - $red + 1 will simply print the $red variable's contents, then "+ 1".
* The macro syntax will shift to the function-call and anonymous-hook syntax. In preview 4, you currently write this:
if($red > 2)[ Yikes! set($red to 2) ] elseif($blue > 2)[ Wow! set($blue to either(1,2)) ] click(?bears)[ replace(?bears)[Ducks] ]
As you can see, it's more concise, and unifies functions and macros into a single device, but comes with a dubious ambiguity, in that the name of the macro cannot touch the prose of the story - there must be a space, line break, or punctuation mark separating them. I should note I don't want to complicate this syntax any or much further by forcing a sigil at the start - it's my belief that the () argument brackets are the "sigil" that designate the name as being that of a macro.
* The <<time>> macro have been replaced with when() and until() macros, which are more general and capable than either of them. In preview 4, you may write this:
<<time 2s>>Two seconds passed.<</time>>
That will become this:
when(time > 2s)[Two seconds passed.]
"time" is a special keyword that evaluates to the number of milliseconds that have elapsed since the passage was entered. The when() macro's condition is re-run 60 times per second, so it will show the contained text once "time" evaluates to over 2 seconds. "2s" is special syntactic sugar based on the CSS time syntax, that evaluates to a number of milliseconds - in this case, 2000.
Also, you will now be able to write these:
until(time > 2s)[This will vanish in two seconds.] when($red is 7)[This will appear as soon as the $red variable is set to 7, possibly by a click macro elsewhere in the passage.]
As you can see, you need not reference "time" inside the when() macro at all.
* The hook syntax will change to become less ambiguous In preview 4, you can write:
Green [gold][color] yellow white
<<replace ?color>>silver<</replace>>
As you can see, the tag on the right of the hook is not easily disambiguated, even with syntax-highlighting, and furthermore makes it difficult to place multiple hooks side-by-side. This will become the following:
Green [gold]<color| yellow white
replace(?color)[silver]
The <color| is supposed to resemble a gift-box tag, as it's the tag of the hook that identifies it. It can actually be placed either before or after the hook - [gold]<color| and |color>[gold] are equally valid.
There's a bit more (such as a transition() macro, and click-replace() etc.) but I'm out of time to keep typing, so I must leave it at this. Again, I'm sorry for having been such an unreliable developer, and hope I can live up to delivering the final push needed to get these into your possession.
I can't seem to change the CSS formatting at all in preview 4. I've tried putting some CSS into the story stylesheet, but it doesn't change anything. Is anyone else having this issue?
I can't seem to change the CSS formatting at all in preview 4. I've tried putting some CSS into the story stylesheet, but it doesn't change anything. Is anyone else having this issue?
I used the following CSS and tried the "Test", "Play" and "Publish to File" options with no results. I tried both Firefox 31 and Chrome 36.
tw-passage { color: blue; }
There was a style tag containing my CSS rule within the tw-storydata tag in all three options. There was also an empty style tag within the head tag in both the "Test" and "Play" options but not in the "Publish to File".
Ah, so it's not just me then? I thought perhaps the way the css was written might have changed or something? I'm sure it did work to an extent in previous previews as I even mentioned in an earlier post that I had got it working but not with images for backgrounds.
http://twine2.neocities.org/ has been updated with a big horrible infodump of the current state of affairs of Twine 2 coding.
First, a few bits of news: * As those who read my tweets may have surmised, the macro syntax has changed again. Yes, this is a bit embarassing and shameful, but I couldn't overcome a few small but serious issues with the C-style function call syntax: separating the left side of the macro name from passage prose, and the severity of the leap from << twine 1 >> syntax to the new syntax. The new and most definitely final syntax is (macroname: param, param, param ...) - which is to say, I just moved the ( from the right side of the name to the left side, and inserted a : where it was. (The : is important: it separates ordinary English param usage from macro usage. "Leon aren't these just S-expressions? Did you just jump from C to fourteen years in the past to Lisp?" I have no comment except to mirror those who claim that SGML tags are just verbose S-expressions anyway. * For those wondering how escaping would work, I've re-purposed what was the Markdown code syntax `some code` to now be the verbatim text syntax. If you want to, say, include the text "(or: not?)" in your passage, put tildes around it to protect it from being parsed. For readability purposes, I prefer this to other escaping methods such as single-character escaping.
So, I was sitting around board between classes yesterday and decided to take a look at Twine 2. Pretty cool! I love how it makes boxes on its own. The UI is slick.
Couldn't figure out how to set variables or do anything with them. Is there a link to a wiki page or another page with syntax or a help file or something?
Aaand we're now at beta 1 (download, try online). I wrote up my notes on it on my blog. Next up, the stack of open bugs.
Extremely embarrassing noob issue here, but I can't figure out how to open Twine 2, the downloaded version? Unzipped it but I'm not seeing anything particularly runnable to my limited knowledge in the ensuing folder.
* Open the HTML file in a web browser to "run" it.
Within the directory/folder you un-zipped the twine-2.0b1.zip archive into there should be a file named index.html, this is the HTML file you need to open with a web-browser of your choice.
Comments
I assume that Twine 2.0 uses Web Storage at the moment, which means that yes, it's totally separate from the browser's cache.
(Assuming the above is correct.) Not really. Most, if not all, browser's handle on-disk storage for Web Storage by using a binary blob of some kind, generally a database (e.g. Firefox uses
SQLitefor this and most other things, I wouldn't be surprised if others do as well). It's not something you can easily swap in and out at will.IMPORTANT: This version changes the story output format
What this means is if you have saved archive files from preview 1 or 2, you must import them in this version and then re-export them in order for them to work in the future. We've changed the output format for stories a little bit, but preview 3 can read both old and new formats. This won't be true in future versions.
Enough scary stuff, this is what's new
1. I've mentioned here and there that I've been working to change the macro and function syntax, so that macros and functions use the same syntax. I've chosen for now to make macros use function syntax, so, for instance, <<checkbox "Pearls" "Peas">> is now checkbox("Pearls", "Peas"). This has a number of advantages. I found that I'm not alone in thinking the double-chevron markers << and >> to be a tad cumbersome - even though they may be visually striking, they somewhat hinder <<print "readability">> in the midst of passage text, so forgoing them is probably a net boon. Also, the TiddlyWiki macro style didn't, in my opinion, make the distinction and separation of macro name and parameters clear - unless you're familiar with HTML, it isn't immediately apparent that the word "display" in <<display previous()>> is a different kind of entity to "previous()" - and, it isn't obvious how many parameters <<set $red to 1>> and <<checkbox "Gold" "Myrrh">> each have, as the second separates two distinct expressions with only whitespace.
You might wonder how a plainer syntax like function() is programmatically distinguished from ordinary English prose (with its own parentheticals). The rule is: the function name must be a single word, and there must be zero whitespace between the name and the open-bracket (, for it to be considered a macro.
2. Actually, I must admit that instead of just changing the syntax, I've done something more radical: made it so that macros and functions are structurally the same thing, and can be used interchangeably. So, you can type either("caterpillar", "worm") directly into passage text, and take the passage text returned by a display() and manipulate it as a string. This, I feel, produces a much simpler conceptual model for Twine coding. For one thing, one could create both "functions" and "macros" using shorthand <<display>>: create an "antagonise" passage that returns certain story-specific values, then call it with antagonise().
3. Now, how does <<if>>, <<else>> and <<endif>> work with this syntax? Well, first, let's look at [hooks][1]. I've introduced hooks as the primary syntactic structure for squaring off sections of passage text for special treatment. So, it's only logical that I extend this to the design of the if() macro - instead of putting the nametag at the end of a hook, put an if() macro at the start: The hook is only displayed if the if()'s expression is true. Thus, the [ and ] replace the need to delimit text with the <<endif>> macro. The else() macro looks behind to see if the previous if() was true or not, and displays if it's so.
The "if()" macro actually internally works like this: it returns a simple JS function (a "hook augmenter") which, when occurring immediately before a hook, transforms the hook in some way. In the case of if(), it removes the hook if it's false. But it suggests other macros could be developed easily - a transition() macro could make a hook transition in with a specific animation, for example - and in a much simpler manner than is possible in Twine 1.
All of the above are very recent developments and I'm still weighing up how they'll work, but I'm enthusiastic that these continue the design goals I've been furthering.
If an Author wishes to have a multi-word function name, for example check_stats, using whitespace characters between the words for readability (does not have to be underscore, could be dash), will they now have to use something like Camel Casing instead? (eg: CheckStats or checkStats)
How does this effect readability, as it considered less readable by many people.
Because java-script is case sensitive, will this lead to more problems/errors? (eg: CheckStats and checkStats are considered different functions)
How would you write the following using the new if() and else() functions?
Twine 2 expressions are planned to be case-insensitive.
You can write nested if() (at least, of the kind you've given) in a style that's a little embarassingly C-like:
I tried implementing it so that you can simply place functions sequentially before the hook, and write it like so: This follows the C tradition of omitting the curly braces for single-line if-statement clauses (a practice that, for the record, many regard as a flaw.) But that aside, I don't really like it much in retrospect, because "click(?1)replace(?2)" doesn't make sense as an expression inside a macro - you can't do "either(1,2)either(3,4)" inside a macro.
I'm wondering what to consider next. Recall that the present means of writing it is this: which is a tad cumbersome, owing to the nesting of the square brackets.
I'm also wondering how to implement <<continue>>. You may recall that macro's main virtue is that you can drop it into a passage and omit the closing <<endcontinue>> - it regards all text afterward as being in its enclosure. Currently, the enclosure macros use explicit hooks as their enclosures, and can't switch any "mode" that causes the following text to fall into an "implied hook" that they control.
(I feel that the conceptual model used by Twine 1 users for understanding <<if>><<endif>> etc. is to think of them as modal - <<if>> turns on the if-macro "mode", and <<endif>> turns it off. This is contrary to how most proglangs implement if, and more saliently how I've been implementing and designing Twine 2's macros, but is aligned with how the text formatting syntax of Twine works - // switches italics on and off, etc. Modality, as we know, is a limited conceptual model to implement a proglang in, but it does provide something of an intuition handle for new users.)
If this is a little confusing, let me reiterate. Currently I'm quite satisfied with the fact that macros can reference hooks (enclosed spans of text) from afar using the hook syntax: This satisfies my separation-of-text-and-code goal. But! There are altogether too many common cases where a little bit of code should be next to a lot of text. Consider a common case like: It would be a tad convoluted if it was rendered thus: In this particular case, keeping the short, curt conditions guarding alternative spans of text aids readability instead of detracting from it. So, there should be a way to make Twine 2 macros 1) refer to a nearby hook, anonymously, to save having to explicitly name them for a one-time referral, while...
2) remaining as lightweight, syntax-wise, as possible, and being "natural" to read (at least as natural as Twine 1's <<if>> is).
My current solution, to make the macros automatically refer to hooks by immediate placement, is one I'm finding myself grow wary of for reasons outlined prior.
....
This seems a dour note to end this post on, so I'll try and make up an alternative on the spot, right now. Hmm... This suggestion alters the enclosing macros (if, replace, click) with an extra keyword "do" (for conditonal macros like if or click) or "with" (for transformative macros like replace or append), which determines the target of the macro (specifically, what its enclosure is). The special keyword "this" specifies that its target is the very next anonymous hook - thus its targeting is explicitly stated rather than implicit. Of course, it has its obvious issues - the "do" clause being in parameter position sort-of makes sense (insofar as the target is indeed an input to the macro) but could be confusing and insufficiently memorable to users.
Would a modal "if" be nestable? I think that would be a very desirable property, but unless I'm misunderstanding what modal means it would not be possible to have nested modal "if"s.
The <<macro>> syntax is useful for inlining macro into text, but if you have a separate code section, a different syntax could be easier to type and easier to read as well. The close tag in particular is overkill, plus in the example it doesn't match the open tag, which is either a typo or a shorthand that the user would have to remember.
Some possible alternative syntaxes: By the way, numeric hook labels look good in examples, but I have some doubt it works well in practice: as you rewrite your passages, hooks will get inserted and removed and the numbers will no longer be in sequence. I think text labels would be better than numbers. (Of course a number is a special case of a text label.)
Does this mean hooked text is invisible by default? Otherwise the second code fragment doesn't do what it's supposed to do.
I'm wondering: if you're going for a C-like macro language, wouldn't it be possible to use JavaScript instead? Maybe with a small extension to be able to use it inline and work with hooks, but mostly just JavaScript. It would reduce the number of languages that users have to learn to get the most out of Twine.
Sorry for not answering the actual questions that you were asking, but I'm having a hard time deducing how the proposed language would work from examples. To be able to discuss a language design without the risk of miscommunication, I think a more formal description of the language is needed.
Twine 1 (and Twine 2)'s "if" isn't modal, and moreover would not be advantageous to be implemented as modal, but I suggest that users conveniently think of it as if it's so (as compared to its actual implementation as a function that takes an expression and a block of passage text as inputs.)
Space-separated arguments is not good, because if people would pass operator-based expressions in argument position (e.g. if($red > 3)) then they'd either need to square-off said expressions with brackets (e.g. examine(($red > 3) "Halt!")), or we'd have to only permit operator expressions in single-argument macros. This is a problem I currently have with <<display>> in Twine 1: you can't pass operator-expressions to the shorthand version because it treats arguments as space-separated, so <<something $red > 3>> would set parameter(0) to $red, parameter(1) to ">", and parameter(2) to "3".
Hook-first doesn't really work either because A) it wouldn't be too readable for pseudo-hooks (i.e. "click-replace "bear" [dog]" would become ""bear" click-replace [dog]") and
Does this mean hooked text is invisible by default? Otherwise the second code fragment doesn't do what it's supposed to do.
I wasn't really thinking straight when writing this - the meaning of the macros isn't supposed to matter, except insofar as they perform an action upon a hook.
However, it does remind me of an ongoing issue, that there isn't yet a good (not hacky) syntactic means of declaring a hook "inactive" initially, which is bound to be useful, as this hypothetical show() macro does feel like it would be a convenient idiom.
*note: code structure from an actually game, content changed because it is not mine. Formatted for easy reading. * I wonder if extending the concept so that it behaves more like document annotating, were you mark the text and then add the instructions/comments about the marked text somewhere else (eg: external to normal passage text) and I would change the background colour of the marked text so it stood out.
So the above example would be something like the following:
pretend that the background colour of the highlight text is red, not the foreground
The quote was "The quick brown fox jumped over the lazy dog[1]."
This is a concern I have - that by providing the option to use macros within the passage, then it will be used at the expense of readability. The problem is, I currently feel that the fluency that comes from tastefully putting a tiny conditional next to a large span of passage text, instantly communicating what branch or conditional is bound to it, is too desirable to pass up.
...But maybe I'm not thinking hard enough, as usual. Maybe it should be the hook tags that should carry this burden? My sensation has been that the above, representing the current state of affairs in Twine 2 syntax, is generally preferable to this: BUT, maybe it could be rewritten like so: Hmm...
Notice that in that one, the hook tags prepend the hooks... I've regarded this as inferior readability-wise in the case of an inline hook: (Scalability is always at mind when thinking of syntax design concerns.)
Although - I recall I made the link syntax bi-directional by way of the "arrow" (that is, [[Link text->passage name]] and [[passage name<-Link text]]) so maybe I could make the hook tag bidirectional as well. Something like this? It's vaguely but reassuringly reminiscent of a gift tag, with its triangular shape.
OK, now let's try this again: I'll admit - it's a small difference, but def some kind of improvement. I'll think about it.
Major changes in this release:
They do display correctly when using Chrome 36 and Internet Explorer 11 on same machine.
Counterpoint: Using the same OS and browser, they appear correctly for me.
If you've been to the Twine 2 preview recently, but before the current release, perhaps you have a stale cache? Did you try a forced reload?
The problem was that although "NoScript" was allowing the downloading of "font-awesome.min.css" because it is directly referenced in the HTML page, it was NOT allowing the download of the fonts listed within the css file.
To fix I had to add an extra rule for "netdna.bootstrapcdn.com", so the problem was my end.
What I should do now is at least introduce the syntax changes that haven't made it into p4, but which are ready to be included. I've already discussed several of these in previous posts, but I feel a confident reintroduction is in order.
* You can print variables by placing their names in the passage text.
In preview 4, you can write: In the next release, you can shorten that to You may note this is even smaller than Twine 1's shorthand print - <<$red>> - and more aligned with the conciseness of HTML templating engines. But, note that, like the Twine 1 shorthand, you can't include full expressions here - $red + 1 will simply print the $red variable's contents, then "+ 1".
* The macro syntax will shift to the function-call and anonymous-hook syntax. In preview 4, you currently write this: That will become this code in the beta: As you can see, it's more concise, and unifies functions and macros into a single device, but comes with a dubious ambiguity, in that the name of the macro cannot touch the prose of the story - there must be a space, line break, or punctuation mark separating them. I should note I don't want to complicate this syntax any or much further by forcing a sigil at the start - it's my belief that the () argument brackets are the "sigil" that designate the name as being that of a macro.
* The <<time>> macro have been replaced with when() and until() macros, which are more general and capable than either of them.
In preview 4, you may write this: That will become this: "time" is a special keyword that evaluates to the number of milliseconds that have elapsed since the passage was entered. The when() macro's condition is re-run 60 times per second, so it will show the contained text once "time" evaluates to over 2 seconds. "2s" is special syntactic sugar based on the CSS time syntax, that evaluates to a number of milliseconds - in this case, 2000.
Also, you will now be able to write these: As you can see, you need not reference "time" inside the when() macro at all.
* The hook syntax will change to become less ambiguous
In preview 4, you can write: As you can see, the tag on the right of the hook is not easily disambiguated, even with syntax-highlighting, and furthermore makes it difficult to place multiple hooks side-by-side.
This will become the following: The <color| is supposed to resemble a gift-box tag, as it's the tag of the hook that identifies it. It can actually be placed either before or after the hook - [gold]<color| and |color>[gold] are equally valid.
There's a bit more (such as a transition() macro, and click-replace() etc.) but I'm out of time to keep typing, so I must leave it at this. Again, I'm sorry for having been such an unreliable developer, and hope I can live up to delivering the final push needed to get these into your possession.
I have some questions for further clarification:
Will this support things like the following: [quote author=L]
The macro syntax will shift to the function-call and anonymous-hook syntax.
a. Will the parser handle things that look like macros but arn't, or will it display a macro "not_a_macro" not found message? b. Will it handle dummy meaningful characters (like end square brackets) or will the Author have to escape them, and if so which escape character? c. What character will be used to seperate macro parameters?
I used the following CSS and tried the "Test", "Play" and "Publish to File" options with no results. I tried both Firefox 31 and Chrome 36. There was a style tag containing my CSS rule within the tw-storydata tag in all three options. There was also an empty style tag within the head tag in both the "Test" and "Play" options but not in the "Publish to File".
First, a few bits of news:
* As those who read my tweets may have surmised, the macro syntax has changed again. Yes, this is a bit embarassing and shameful, but I couldn't overcome a few small but serious issues with the C-style function call syntax: separating the left side of the macro name from passage prose, and the severity of the leap from << twine 1 >> syntax to the new syntax. The new and most definitely final syntax is (macroname: param, param, param ...) - which is to say, I just moved the ( from the right side of the name to the left side, and inserted a : where it was. (The : is important: it separates ordinary English param usage from macro usage. "Leon aren't these just S-expressions? Did you just jump from C to fourteen years in the past to Lisp?" I have no comment except to mirror those who claim that SGML tags are just verbose S-expressions anyway.
* For those wondering how escaping would work, I've re-purposed what was the Markdown code syntax `some code` to now be the verbatim text syntax. If you want to, say, include the text "(or: not?)" in your passage, put tildes around it to protect it from being parsed. For readability purposes, I prefer this to other escaping methods such as single-character escaping.
Couldn't figure out how to set variables or do anything with them. Is there a link to a wiki page or another page with syntax or a help file or something?
Keep up the good work!
Extremely embarrassing noob issue here, but I can't figure out how to open Twine 2, the downloaded version? Unzipped it but I'm not seeing anything particularly runnable to my limited knowledge in the ensuing folder.
Thanks
* Open the HTML file in a web browser to "run" it.
* Consult http://twine2.neocities.org/ for a rough guide to the syntax.
Within the directory/folder you un-zipped the twine-2.0b1.zip archive into there should be a file named index.html, this is the HTML file you need to open with a web-browser of your choice.