# -*- mode: org; coding: utf-8-dos; -*-
#+TITLE: MinStory Manual
#+TITLE: for MinStory version 1.2.0 and MinStory Editor version 1.2.0
#+AUTHOR: Tor Egil Hoftun Kvæstad
#+EMAIL: me+minstory@toregilhk.org
* MinStory
** Running the Program
You must unpack the zip-file you have downloaded, and then enter the "minstory" directory that is created. To start the program you then run the command

#+begin_src sh
  ./bin/player
#+end_src

** About the Program
The program is intended to enable users to create their own interactive stories that can be shared with others and run with the program.

The term "interactive story" is used here to describe the kind of stories created by "Choose Your Own Adventure"-books, where the reader is given a page of text, and then has a choice how to further advance the story. This is implemented by telling the reader which page to turn to.

Using this program, a user can play an interactive story that has pictures and text. The story can be advanced by clicking on the user's respective choice.

Originally, the name was decided to be "iStory", short for "Interactive Story" and because Apple likes to use i in front of their product names. A quick search found that the name was already in use, and the name "InStory" was considered instead. However, by choosing to name it "MinStory", short for "My Interactive Story", a sort of pun would emerge. The word "min", means "my" in norwegian.
* The Editor
** About the Editor
Instead of crafting the stories by hand, you can use the Editor to create them using a graphical user interface. You should be aware, however, that the Editor currently is rather rude. If you open a file and save it again, it will probably not be completely identical to the way it was before you saved it
anew. Keep this in mind, especially if you are using the editor to work on files that have been made by hand.
** Running the Editor
You must unpack the zip-file you have downloaded, and then enter the "minstory" directory that is created. To start the program you then run the command

#+begin_src sh
  ./bin/editor 
#+end_src
** The Difference Between Saving and Exporting
Saving a story to a file and exporting it do nearly the same thing. Which function you should use depends on what you need to do.

When saving a file it saves to an xml-file, and it only saves the story. If you send the xml-file to someone, they will have a problem opening it, since the images are still on your computer. In addition, even if you sent the images as well, the paths to the images may be absolute, pointing to a directory on your computer.

When you export your story, it will be exported to a zip-file. All the images that you have used will be put inside it, and the paths to the images will be changed accordingly. There should be no problems sending the zip-file to someone.
* The MinStory File Format
** Making Your Own Story
If you want to make your own story, you should probably have a look at the "Welcome"-story. It can be found in the file story.xml inside the file welcome.zip (which can be found in the directory where you have installed MinStory).

Some things to note about a story-file:

- MinStory-files are in the xml-format. You should read about the format before trying to make a story
- It is case-sensitive, ie. <MinStory> works, while   <minStory> doesn't
- All "id"s must be unique within a story
- All "z"-coordinates should be unique in a scene. Even if two elements are not overlapping, give them differing "z"-coordinates
- A <story> contains one <main>-section with information about it
- A <story> contains at least one, and maybe more <scene> elements
- A <scene> contains zero or more of <hotspot>, <image> and/or <text> elements

Further tips:

- If you are going to distribute your story, unly use text and images that you are allowed to use (that is, that you have created yourself, or that you have obtained the proper permissions from the creator)
- Remember that the user cannot see which areas he/she can click on (Except by moving the mouse around to see where the cursor changes to a hand). Make it easy for him/her to see it by differentiating the clickable areas in some way
- <image> vs <text>: There are two ways of adding text to your story, each one has advantages and disadvantages
  - If you save your text as an image, you can use whatever font you like, whichever colour, size and decorations. However, if the user resizes MinStory, the text might become blurred. Also, you can use no more text than the screen can show at once
  - If you use the <text> element, you get no control over fonts, colours, sizes or decorations. On the other hand, the user can scroll through the text (so you can write more text than can be shown on the screen at once), and the text is not changed if MinStory is resized
- Use relative paths! If you're not using relative paths in the story-file, it will not work for other users
- To ease the distribution and use of your story, consider putting it in a zip-file. This also has the benefit of reducing the file-size. You can arrange the contents of the zip-file in any way you want, as long as you keep the story in the file story.xml and place it in the root directory of your zip-file
- If you want to use a <Hotspot>-element that has a tooltip spanning multiple lines, put "\n" where you want the linebreaks to occur
** Format Overview
This overview documents version 0.1 of the MinStory file format. You can also take a look at the schema used, in the file [[file:minstory.xsd][minstory.xsd]]. You can, of course, also use it to validate your story-files.

Please note that there are some constraints that are not yet described in the schema, so you shouldn't trust it blindly.
*** Root element – MinStory
**** Synopsis
#+CAPTION: Attributes of MinStory
| Name    | Type   | Default | Required |
|---------+--------+---------+----------|
| version | String |         | Required |

- Parents :: None


#+CAPTION: Children of MinStory
| Name  | Type     | Amount      | Required |
|-------+----------+-------------+----------|
| [[main]]  | Elements | One         | Required |
| [[scene]] | Elements | One or more | Required |
**** Description
The MinStory element is the root element of a story. It must be spelled "MinStory". It is a required element.
**** Attributes
- version :: A string, the version of the MinStory format this document is using. It is a required attribute.
*** main
**** Synopsis
- Parents :: [[Root element – MinStory]]


#+CAPTION: Children of main
| Name          | Type    | Amount      | Required |
|---------------+---------+-------------+----------|
| [[authorName]]    | String  | Zero or One |          |
| [[authorContact]] | String  | Zero or One |          |
| [[description]]   | String  | Zero or One |          |
| [[height]]        | Integer | One         | Required |
| [[width]]         | Integer | One         | Required |
| [[start]]         | String  | One         | Required |
| [[title]]         | String  | Zero or One |          |
| [[website]]       | String  | Zero or One |          |
**** Description
The "main"-element contains information about the story. It is a required element.
*** authorName
**** Synopsis
- Parents :: [[main]]
**** Description
The name of the author. It must occur only once, or not at all.
*** authorContact
**** Synopsis
- Parents :: [[main]]
**** Description
Contact details for the author. It must occur only once, or not at all.
*** title
**** Synopsis
- Parents :: [[main]]
**** Description
The title of the story. It must occur only once, or not at all.
*** website
**** Synopsis
- Parents :: [[main]]
**** Description
An URL to a website pertaining to the story (or its author). It must occur only once, or not at all.
*** description
**** Synopsis
- Parents :: [[main]]
**** Description
A description of the story. It must occur only once, or not at all.
*** width
**** Synopsis
- Parents :: [[main]]
**** Description
An integer larger than 0, the width of the story, in pixels. It is a required element.
*** height
**** Synopsis
- Parents :: [[main]]
**** Description
An integer larger than 0, the height of the story, in pixels. It is a required element.
*** start
**** Synopsis
- Parents :: [[main]]
**** Description
The scene of the story in which the story should start. Must be the id of an existing scene. It is a required element.
*** scene
**** Synopsis
#+CAPTION: Attributes of scene
| Name | Type   | Required |
|------+--------+----------|
| id   | String | Required |

- Parents :: [[Root element – MinStory]]


#+CAPTION: Children of scene
| Name    | Type     | Amount       | Required |
|---------+----------+--------------+----------|
| [[hotspot]] | Elements | Zero or more |          |
| [[image]]   | Empty    | Zero or more |          |
| [[text]]    | String   | Zero or more |          |
**** Description
A "scene"-element contains all information about a scene. It is a required element, but can occur many times.
**** Attributes
- id :: A string, the id of the scene. It must be unique in a story. It is a required attribute.
*** image
**** Synopsis
#+CAPTION: Attributes of image
| Name   | Type    | Default | Required |
|--------+---------+---------+----------|
| height | Integer |         | Required |
| id     | String  |         | Required |
| src    | anyURI  |         | Required |
| width  | Integer |         | Required |
| x      | Integer |         | Required |
| y      | Integer |         | Required |
| z      | Integer |         | Required |

- Parents :: [[scene]]
**** Description
An image to be rendered on the specified position in the scene.
**** Attributes
- src :: The path to an image-file. It should be a relative path, to ensure that it works correctly on differing systems. The image must be of the type Graphics Interchange Format (GIF), JPEG or Portable Network Graphics (PNG). It is a required attribute.
- x :: An integer, in the range 0 to (story-width - image-width). The horizontal position of the image. It is a required attribute.
- y :: An integer, in the range 0 to (story-height - image-height). The vertical position of the image. It is a required attribute.
- z :: An integer, equal to or larger than 0. It is a required attribute.
- height :: An integer larger than 0, the height of the image, in pixels. It does not have to correspond to the original height of the image. It is a required attribute.
- width :: An integer larger than 0, the width of the image, in pixels. It does not have to correspond to the original width of the image. It is a required attribute.
- id :: A string, the id of the image. It must be unique in a story. It is recommended that it is unique in the set of elements in the story. It is a required attribute.
*** text
**** Synopsis
#+CAPTION: Attributes of text
| Name   | Type    | Default | Required |
|--------+---------+---------+----------|
| height | Integer |         | Required |
| id     | String  |         | Required |
| width  | Integer |         | Required |
| x      | Integer |         | Required |
| y      | Integer |         | Required |
| z      | Integer |         | Required |

- Parents :: [[scene]]
**** Description
A scrollable textbox to be rendered on the specified position in the scene.
**** Attributes
- x :: An integer, in the range 0 to (story-width - text-width). The horizontal position of the textbox. It is a required attribute.
- y :: An integer, in the range 0 to (story-height - text-height). The vertical position of the textbox. It is a required attribute.
- z :: An integer, equal to or larger than 0. It is a required attribute.
- height :: An integer larger than 0, the height of the textbox, in pixels. It is a required attribute.
- width :: An integer larger than 0, the width of the textbox, in pixels. It is a required attribute.
- id :: A string, the id of the textbox. It must be unique in the story. It is recommended that it is unique in the set of elements in the story. It is a required attribute.
*** hotspot
**** Synopsis
#+CAPTION: Attributes of hotspot
| Name    | Type    | Default | Required |
|---------+---------+---------+----------|
| height  | Integer |         | Required |
| id      | String  |         | Required |
| tooltip | String  |         |          |
| width   | Integer |         | Required |
| x       | Integer |         | Required |
| y       | Integer |         | Required |
| z       | Integer |         | Required |

- Parents :: [[scene]]


#+CAPTION: Children of hotspot
| Name  | Type     | Amount      | Required |
|-------+----------+-------------+----------|
| click | Elements | Zero or one |          |
**** Description
A hotspot that may show a tooltip when hovered over and/or send the player to another scene when clicked.
**** Attributes
- tooltip :: A string, a tooltip that should be shown when the player hovers the mouse pointer over the area defined by the hotspot. Use "\n" to split a tooltip over multiple lines.
- x :: An integer, equal to or larger than 0. The horizontal position of the hotspot. It is a required attribute.
- y :: An integer, equal to or larger than 0. The vertical position of the hotspot. It is a required attribute.
- z :: An integer, equal to or larger than 0. It is a required attribute.
- height :: An integer larger than 0, the height of the hotspot, in pixels. It is a required attribute.
- width :: An integer larger than 0, the width of the hotspot, in pixels. It is a required attribute.
- id :: A string, the id of the hotspot. It must be unique in the story. It is recommended that it is unique in the set of elements in the story. It is a required attribute.
*** goto
**** Synopsis
#+CAPTION: Attributes of goto
| Name        | Type   | Default | Required |
|-------------+--------+---------+----------|
| destination | String |         | Required |

- Parents :: [[click]]
**** Description
An action that, when activated, sends the player to a specified scene.
**** Attributes
- destination :: A string, the id of the scene to which the player should be sent if this action is activated.
*** click
**** Synopsis
- Parents :: [[hotspot]]


#+CAPTION: Children of click
| Name | Type  | Amount | Required |
|------+-------+--------+----------|
| goto | Empty | One    | Required |
**** Description
An action to be taken when the player clicks on the parent element.

