SCREE FORMAT

About This Template

By default, when compiled (File > Compile), this project can generate a plain text file in “twee” format, a flat-file Markdown-like format for gamebooks that is also used by the graphical gamebook editor Twine. Optionally, the template can also compile the “twee” file into an HTML gamebook using an additional compiler program such as Twee2 (http://twee2.danq.me) or Tweego (https://www.motoslave.net/tweego/); the instructions below include installation and use of these compilers.

You can also import an existing Twine or twee file into Scrivener by following the Import/Export directions below, and it will be separated into scenes for you automatically.

Installation

Install the Scree template: Unzip the appropriate Scree archive for your version of Scrivener.  This template is for Scrivener 3.  (For any Scrivener 2, or for Scrivener 1 on Windows, use the Scrivener 2 version of Scree.)  To install the template file, Scree.scrivtemplate, open the Project Templates window, either by just opening Scrivener, or, if it doesn't appear then, by choosing File > New Project from the Scrivener menus.  In the Options dropdown at the bottom right of the Project Templates window, click Import Templates…, then browse to and open the template file in the file dialog.  After that, you can create a new project using the Scree template.

• Install Tweego or Twee2: 
• Install Tweego (https://www.motoslave.net/tweego), as follows:

1. Download the Tweego zip for your operating system from the URL above.
2. Unzip the zip file.  You will get a folder with a name like tweego—1.3.0-youros-x64, which you may want to rename and move to a convenient location.  Scree assumes you have named it tweego and put it into the main Applications folder.  (See Making Changes if you didn’t.)
3. Download the story formats zip file from the same URL and unzip the file.
4. Put the story formats folder inside your (possibly renamed) tweego folder.

• Alternately install Twee2 (http://twee2.danq.me), as follows:

1. If your system is not running Ruby 2.0, install that first following the instructions here:  http://mcdemarco.net/tools/scree/rubyHelp.html 
2. Open a command prompt or terminal and type:  gem install twee2

If you have trouble installing Ruby and the gem on Windows (or MacOS), you can always use Tweego instead.  For more help with Tweego, see the documentation (https://www.motoslave.net/tweego/docs/).  Note that Twee2 does not support decompiling on Windows while Tweego does; Twee2 includes story formats while Tweego does not.

How To Use This Template

• Under Draft, create a new text document for each node in your interactive story, and give each one a unique title. A few such scenes have been created for you with the placeholder titles "Scene 1", "Scene 2", etc.
• Link between nodes of your story with Markdown-style links such as [[Scene 1]] or [[The longer description of scene 1 that I want my reader to see->Scene 1]].  To this end, it helps to name the scenes with the text you want to show the reader, such as [[Talk to the mysterious man]].  
• Alternately, you can use Scrivener's internal document links for these links, and they will be converted to Markdown links when compiling.  Internal links are handy for navigating your Scrivener project, but have a downside: you cannot rename any internal document links; they should match the literal scene name.  However, you may combine both approaches, using internal links for all simple links like [[Scene 1]], but Markdown links for renamed links like [[The longer description of scene 1 that I want my reader to see->Scene 1]].
• Ideally, your story sections should be written in Markdown format or plain text, with blank lines between paragraphs.  However, Scrivener can convert some rich text to plain text for you later, if you prefer to view your story as rich text within Scrivener itself.  Because Twee/Twine uses a plain text format, some rich text settings, corkboard text, and other Scrivener annotations will not be included in your final output.  (In particular, you should not use the Bold or Italics button in Scrivener 3.)
• You can nest text documents in folders or under each other as shown in the example scenes, but this is not necessary.  When you compile, all text scenes (documents) will be treated as regular nodes of the story, and folder information will be ignored.
• When you are ready, compile your story.  This will output a plain-text Twee or Twee2 file, which you (or Scrivener) can then process into an HTML story file (using Twee2 or Tweego), which you (or Scrivener) can open in any browser.  You can also import this HTML story file into the Twine visual editor (version 2), or import the plain-text Twee file into the older Twine v.1 visual editor.

Compiling with Scrivener

• The title of your story should be in a specific format set up for you in the “Front Matter” folder (between the “Draft” and “Research” folders). It defaults to the project title, but you can replace the Scrivener title placeholder with a different title if you desire.  The title and some other values will be available for use anywhere in your story with the appropriate Scrivener placeholder variable (e.g., <$author>). 
• Scrivener remembers your compile settings, so you only need to go to File > Compile… and click the “Compile” button.  If you change any compile settings, Scree may no longer work properly.
• There are two compile options, Twee and Twee2, for use with Tweego or Twee2, respectively.  See Import/Export below for more details.
• After compiling, and if you are using a version of Scrivener 3 that supports it, Scree will attempt to convert your story to Twine, using Tweego for the Twee option and Twee2 for Twee2.  In the Twee2 case you may want to add your chosen story format to the appropriate settings document under Front Matter; for Tweego you will need to edit the Scrivener format to pass in a non-default format name.  (See Making Changes for details.)  Scrivener will ask which browser to open the resulting HTML file in; if possible, switch this dropdown to a different browser than Safari (due to issues opening local files with Safari in some story formats).

Compiling Outside of Scrivener

You don't have to use the Scrivener post-proccessing options (and cannot use them if you have a Scrivener from the Mac App Store).  Instead you can compile Scrivener's twee output using a command prompt or terminal window.  First, navigate to the directory containing your compiled file.  (For help with this, see http://www.wikihow.com/Change-Directories-in-Command-Prompt.)

1. If, for example, you saved your compiled story as mystory.txt, then you would type the following in the command prompt or terminal to compile with Twee2:  
   • twee2 build mystory.txt mystory.html
2. Twee2 and Tweego may give you a warning about a StoryIFID.  You can ignore this warning in Twee2, but in Tweego you should copy the text it gives you into the Twee Settings document in Front Matter on a new line.
3. If all goes well, you can now open your html output file, mystory.html, in a browser, and read your story interactively.
4. You can change story format at the Twee2 command line.  For example, you may need the SugarCube format on twee files that include an older style of Twine scripting:  
   • twee2 build mystory.txt mystory.html --format=SugarCube
5. You can also open your generated html file in Twine 2, at http://twinery.org/2/, or in a downloadable version of Twine 2 and change the story format there instead of at the command line.
6. See the Tweego documentation for help doing similar actions using Tweego instead:
   • https://www.motoslave.net/tweego/docs/

Making Changes

There are various minor changes you can make to the settings to tweak this template and Scrivener itself so that it better suits your needs, as follows:

• Project and author name: The default book title used in headers and elsewhere can be customized by going to You can also edit the project title in the Metadata section of the File > Compile… window (under the tag icon in the right-hand column).  The default Scrivener 3 author name can be filled out under Scrivener > Preferences > General > Author Information.  Scrivener may also find you in your Contacts.
• Setting plain-text preferences:  The Scrivener manual recommends some preferences to make Scrivener behave more like you'd expect for plain text editing.  Rather than set these individually, you can load a set of plain text preferences and styles available at the Scrivener website: 
• https://www.literatureandlatte.com/forum/viewtopic.php?f=21&t=14412  
• Note that none of these changes are necessary; you can write in rich text mode and either of the Twee compile options will still output plain text.
• Do not use the “Convert Rich Text to MultiMarkdown” option, even if you see it.  If you used rich text bold or italics in a Scrivener 2 story, you should convert them to Markdown before upgrading to Scrivener 3, by selecting all your draft text and use Scrivener 2’s Format > Convert > Bold and Italics to MultiMarkdown Syntax menu item.
• Automatically creating document links:  In Scrivener's Preferences, under the Corrections tab, check off the Data Detection: Automatically detect document links]] checkbox to have your Twine links automatically converted to Scrivener links.  (They will be converted back during compilation.)  Note that this will not convert any pre-existing links for you, and will convert arrow links incorrectly.  To insert arrow links with this setting you can link to the Trash and then use the Edit -> Remove Link menu item to unlink your link.
• Changing the Tweego location or story format:  In the Compile window, right-click the Twee format (or click the gear at the bottom of the format list) and select Edit Format.  Click the Processing tab in the sidebar to open the command-line settings for Tweego.  To change the location of Tweego, edit the Path setting.  Be sure to set it to the full path of tweego, including tweego itself.  To add more command-line arguments to tweego, such as the story format, make your desired changes to the Arguments field.  For example, to use Harlowe as your Twine story format, add the following to the Arguments field:  -f harlowe-2 
• You could make changes for twee2 in the Twee2 format the same way, but they’re generally not necessary.
• Character and setting sketch sheets and other helpful Scrivener sections have not been included in this template, but they can be dragged into your story file from another template or project that includes them, if desired.  Be sure not to drag them into the Draft section.
• Making your own special folders: The “Research” folder is just a regular folder that has been set up in a particular way, and you are free to create other folders that work in a similar manner.
  1. To create a folder with a custom icon, add a new folder, place it where you want it, ensure it is selected, and then go to Documents > Change Icon to choose a different icon.
  2. To create your own template sheets, simply create a new document inside the “Template Sheets” folder and set it up however you want (whether by adding text, changing the title, setting default meta-data, or whatever). Now this document will be available as the basis of new documents from the New From Template menu. (You can add a custom icon to this if you so wish, too.)
  3. To set things up so that when the special folder created in (1) is selected and you hit “Add”, a new document based on the one you set up in (2) is created, select the folder and go to Documents > Default New Subdocument Type and select the special template document you created.

Import/Export

• To import a Twine 2 file to Scrivener, first install the Enscree proofing format: open Twine 2, press the Formats button, choose the Add a New Format tab, and paste the following URL into the form field: https://www.mcdemarco.net/tools/scree/enscree/format.js.  Go to the Proofing Formats tab in the same popup and click the star to make this your default proofing format.  Close the popup, open your story, and choose View Proofing Copy from the popup menu.  Your file may download automatically, or it may open in a new tab where you will need to save using your browser's save option.  Finally, click on the Draft header and import the saved file into Scrivener using the File > Import > Import and Split… menu item, choosing the option to Split and structure using Markdown headings in the text.  Note that:
  • All scenes will be imported at the same level. (You can rearrange them afterwards.)

• Some non-story nodes may also be imported; these can be ignored or deleted manually.

• To import an existing twee or twee2 text file to Scrivener, first compile it with Twee2 or Tweego as you would Scrivener output (see Compiling Outside of Scrivener above), then import it into Twine 2 with Twine 2's Import from File option.  Lastly, follow the previous instructions for importing a Twine 2 file into Scrivener.

• To import an existing Twine 1 story to Scrivener, first export as twee from Twine 1, then follow the previous instructions for importing a twee story.
• You can also import an existing Twine 2 story file by decompiling it with Twee2 (twee decompile mytwine2story.html mytwine2story.txt), then manually replacing "::" with "##" in a text editor, and importing with Scrivener's MultiMarkdown importer as above.  This process will preserve Twine's layout position codes, which is useful if you want to go back and forth between Twine 2 and Scrivener.

• If you import a twee2 file that has tags or position codes, they will appear in text document titles.  They are harmless, but note that they are not part of the link text.  You should use the Twee compile option instead of the Twee2 one if you want to preserve any existing  tags or position codes in the title line on export from Scrivener, and your label and status will not be converted to tags in that case.
• As mentioned earlier, you can import your story into Twine 2 (after processing it with Twee2).  Scree's Twee2 compile option adds (somewhat random) position codes to facilitate import into Twine 2 (and also passes Label and Status to Scrivener as tags).  You can rearrange the nodes within Twine 2 as desired.  If you use the Twee compile option, then compile with Tweego to get better automatically-generated position codes.
• It is possible to go back and forth between Scrivener and Twine 2 in this way, but note that any hierarchical structure to the Drafts folder, labels, tags, corkboard entries, and internal Scrivener links will not be preserved.

Scripting and Styling

• Gamebook scripting (e.g., using variables to track user inventory) is supported by Scree and Twee2; just add the appropriate script to the individual text document where you want it to run.  Note that the scripting language is determined by your choice of story format; you can read more about scripting in the Twine wiki: https://twinery.org/wiki/.
• Likewise, the different story formats have different ways of altering the default style of the HTML output or of a particular story node which you can read about in the Twine wiki.  Twee2 also has extensive styling support that you can read about in the Twee2 documentation: http://twee2.danq.me/documentation.html.

• Twee2, Tweego, and Twine support using your own format instead of the default ones.
• If you are working with an old twee/sugarcane story, the story format you probably want to go forward with is SugarCube.

Credits

This template is by M. C. DeMarco, http://mcdemarco.net, and is released as-is.  Version: 3.0.3a, 26 July 2018.

Twee2 is by Dan Q, https://danq.me, and is released under GPL 2.0.

Tweego is by Thomas Michael Edwards, and is available under a BSD license.

Twine2 is by Chris Klimas and many others and is released under GPL 3.0.