SCREE FORMAT

About This Template

By default, when compiled (File > Compile), this project will 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. The “twee” file can be compiled into an HTML gamebook using an additional converter program such as Twee2 (http://twee2.danq.me); the instructions below include installation of Twee2.

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

Installation

Install the Scree template: Unzip the Scree archive.  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.  Click on the category you want to put the template under--e.g., Fiction. In the Options dropdown at the bottom right, click Import Templates...  Then browse to and open the template file in the file dialog.  Then you can create a new project using the Scree template.

Install the Twee compile presets (Windows only): In Scrivener 1 for Windows, compile presets need to be installed separately. So you will need to install at least one of the preset files Twee.ini or Twee2.ini: 

1. Open any project, then choose File -> Compile from the menu.  
2. If you get the small version of the Compile panel with no presets buttons, then press the down arrow button next to the first dropdown to show the full Compile panel.
3. Press the Load Preset... button at the lower right of the full compile panel.  This brings up a second popup.
4. Press the Import... button, navigate to Twee.ini or the other preset file in the file browser, and open it.  
5. Twee will be added to the Compile format list (under My Formats near the end of the list);  press Cancel to close the second popup.  
6. Twee is now included in the Format As dropdown in the Compile window.  You can now repeat these steps for the other preset file, or shrink the Compile window down using the up arrow, if desired.

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

1. If your system is not running Ruby 2.0, follow the instructions below to install that first. 
2. Open a command prompt or terminal and type:  gem install twee2

Install Ruby (mostly Windows only): Note that newer versions of MacOS probably are running Ruby 2.0, despite the warning at the Twee2 site.  If  you're running an older MacOSX, see the instructions at the Twee2 site for installing Ruby: http://twee2.danq.me/install.html.  To install on Windows:

• Download the Ruby installer for Windows from http://rubyinstaller.org/downloads/.
• Run the installer, being sure to check off "Add Ruby executables to your PATH".  (You can repeat the install if you forget to do so the first time.)
• If the Windows Firewall blocks the gem installer, check off the relevant checkbox, click Allow Access, and try again.
• If you get an SSL error at the command line from the gem installer, see the directions here for manually updating the gem installer: 
• https://gist.github.com/luislavena/f064211759ee0f806c88#installing-using-update-packages-new

To open a cmd window, type cmd into the search box at the bottom of the Windows Start menu.  If you have too much trouble installing Ruby and the gem on Windows (or MacOS), you can use a Tweego binary instead: https://bitbucket.org/tmedwards/tweego/overview.  Note that Twee2 does not support decompiling on Windows while Tweego does, but Tweego does not support Twine2 story formats, and you will need to download the Twine 1 story formats if you don't have a Twine 1 or Twee install handy.  (Twee2 supports most story formats.)

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]].
• Ideally, your story sections should be written in Markdown format or plain text, with blank lines between paragraphs.  However, Scrivener can convert 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 passed into your final output.
• 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 will be treated as nodes of the story, and all folder information will be ignored.
• When you are ready, compile your story.  This will output a plain-text Twee or Twee2 file, which you can then process with Twee2 into an HTML story file which you can open in any browser.  You can also import the HTML story file into the Twine2 visual editor.  (Twine v.1 should also work with the Twee format.)

Compiling with Scrivener

• The title of the story must 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.
• 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.
• There are two compile options, Twee2 and Twee.  Unless you plan to use Twine 2, they make little difference; see Import/Export below for more details.  
• Note that on Windows, Scrivener will only remember your currently selected compile format for the duration of your Scrivener session, so you may need to select a Twee format again when you start a new Scree project or reopen an existing Scree project.
• On MacOS, the default Format As: Scree option is the same as the Twee2 option.
• If you have rich text bold or italics within your story, they will be lost unless you convert them to Markdown before compiling.  You can do the conversion by selecting all your draft text and using the Format > Convert > Bold and Italics to MultiMarkdown Syntax menu item.

Compiling with Twee2

• After compiling your story in Scrivener, open a command prompt or terminal window and navigate to the directory containing your compiled file.  (For help with this, see http://www.wikihow.com/Change-Directories-in-Command-Prompt.)
• If, for example, you saved your compiled story as mystory.txt, then you would type the following in the command prompt or terminal:  twee2 build mystory.txt mystory.html
• Twee2 will give you a warning about a StoryIFID.  You can ignore this warning, or you can copy the text it gives you into the StoryTitle document in Front Matter.  Be sure to put it on a new line.
• If all goes well, you can now open your html output file, mystory.html, in a browser, and read your story interactively.
• 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
• You can also open your generated html file in Twine 2, at http://twinery.org/2/, or in a downloadable version of Twine 2.  This is a user-friendlier way to change the story format than at the command line.

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 and author name used in headers and elsewhere can be customized by going to Project > Meta-Data Settings… and choosing the “Project Properties” tab.
• 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 available at the Scrivener site: 
• 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.
• 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 tab: 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 and 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, import the saved file into Scrivener using the Multimarkdown importer; be sure to import them under the Drafts header.  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 deleted manually.

• To import an existing twee or twee2 text file to Scrivener, first compile it with Twee2 as you would Scrivener output (see Compiling with Twee2 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.
• You can also import an existing Twine 2 story file by decompiling it with Twee2 (twee decompile mytwine2story.html mytwine2story.txt), then importing the text with Scrivener's splitter (split on "::"; this will duplicate scene titles), or manually replace "::" with "##" and import 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 position codes, the position codes will appear in text document titles.  These 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 position codes on export from Scrivener.
• 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.  You can then rearrange the nodes within Twine 2 as desired. 
• 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 and any corkboard entries 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 supports using your own format instead of the pre-packaged ones, as does Twine.
• If you are working with an old twee story, the story format you probably want is SugarCube.

Help

This template is by M. C. DeMarco, http://mcdemarco.net, and is released as-is.  Version: 1.0.1, 26 Oct 2016.

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

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