Fate Documentation

Fate Documentation.txt

Fate Documentation


------------------------------------------------------------------------


  1. Features
    1.1. Passages
    1.2. Start passage
    1.3. Links
      1.3.1. Explicit Links
      1.3.2. Implicit Links
    1.4. Conditional Text
    1.5. Rules
    1.6. criteria()
      1.6.1. Standard comparators
      1.6.2. World comparators
    1.7. weight()
    1.8. display()
      1.8.1. passage display
      1.8.2. query display
    1.9. set()
      1.9.1. Assignment
      1.9.2. Basic math
      1.9.3. Percentage math
    1.10. math()
      1.10.1. abs
      1.10.2. ceiling
      1.10.3. floor
      1.10.4. round
      1.10.5. random
    1.11. print()
    1.12. either()
  2. Special Stuff
    2.1. Rich text formatting
    2.2. Comments
    2.3. Named constants
    2.4. control()
      2.4.1. end
      2.4.2. player
  3. World System
    3.1. Nouns
    3.2. Verbs
    3.3. require()
    3.4. move()
  4. Game Information
    4.1. content()
      4.1.1. author
      4.1.2. brief description
      4.1.3. content descriptor
      4.1.4. content rating
      4.1.5. contributor
      4.1.6. credits
      4.1.7. full description
      4.1.8. identifier
      4.1.9. license
      4.1.10. phobia
      4.1.11. sensitive content
      4.1.12. title
      4.1.13. updates
      4.1.14. version
  5. Saving
      5.0.1. save data


------------------------------------------------------------------------


  1. Features
  ===========


	1.1. Passages
	=============

Passages group text.

  :: Passage
  Passages group text.

--------------------


	1.2. Start passage
	==================

The first passage of the game. Called automatically at game start. Must exist.

  :: Start
  First passage of the game.

--------------------


	1.3. Links
	==========


		1.3.1. Explicit Links
		=====================

Links are the connections between passages. When the player clicks one, they go to the specified passage.

  [[Passage Title]]

A link can go to a specific passage, but use a different displayed text value.

  [[Displayed Link Text|Passage Title]]

Links can have criteria that must be true for the link to be displayed.

  [[Passage Title|criteria($KEY == VALUE)]]

Multiple criterion are separated by &&

  [[Passage Title|criteria($KEY == VALUE && $OTHER_KEY == VALUE)]]

Link with a displayed title & criteria

  [[Displayed Link Text|passage(Passage Title) criteria($KEY == VALUE)]]


		1.3.2. Implicit Links
		=====================

When selected this link does a query for the best passage to go to. The arguments within query() are set prior to looking up a passage.

  [[Displayed Link Text|query($key = value)]]

Multiple assignments are separated by ;

  [[Displayed Link Text|query($key = value; $key = value)]]

Query link with criteria.

  [[Displayed Link Text|query($display = enum.VALUE) criteria($KEY == VALUE)]]

--------------------


	1.4. Conditional Text
	=====================

Text can also be conditional within a passage using if statements.

  Here is a passage if ($someCondition == true) { This text will display if the condition is met.} of text.

else

  Here is a passage if ($someCondition == true) { A } else { B } of text.

else if (note you can only use a single else if)

  Here is a passage if ($someCondition == true) { A } else if ($someCondition == false) { B } of text.
  

if, else if, else

  Here is a passage if ($someCondition == 4) { A } else if ($someCondition == 5) { B } else { C } of text.

--------------------


	1.5. Rules
	==========

Similar to a passage, except it is used implicitly.

  :: Passage [rule($variable == 2)]
  Passage is set to only be used when conditions are met. 
  This is shown after a lookup is done. 

--------------------


	1.6. criteria()
	===============

criteria within a rule declaration create more rules with additional criteria.
The text after a criteria call defines the new rule and can include anything a passage body would contain. 
The initial criteria within the rule declaration line are inherited.
Note that if any variable within the criteria does not exist the condition will fail.

  :: Implicit Passage [rule($variable == 2)]
  Body of the first rule.
  
  criteria($anotherVariable == 2)
  Body of the second rule.

You can define many passages under a single passage declaration. Higher criteria passages have higher priority. multiple criterion are separated by &&

  :: Implicit Passage [rule($variable == 2)]
  Body of the first rule.
  
  criteria($anotherVariable == 6626)
  Body of the second rule.
  
  criteria($variable == 2 && $otherVariable != 89)
  Body of the third rule.


		1.6.1. Standard comparators
		===========================

Equal to

  criteria($key == 6626)

Not equal to

  criteria($key != 6626)

Greater than

  criteria($key > 6626)

Greater than equal to

  criteria($key >= 6626)

Less than

  criteria($key < 6626)

Less than equal to

  criteria($key <= 6626)

Divisible by

  criteria($key % 6626)

Indivisible by

  criteria($key !% 6626)


		1.6.2. World comparators
		========================

Noun is in

  criteria(Noun -> Noun)

Noun is not in

  criteria(Noun !-> Noun)

Noun is with

  criteria(Noun ^ Noun)

Noun is not with

  criteria(Noun !^ Noun)

--------------------


	1.7. weight()
	=============

Use weight to give passages higher priority. (default is 1)

  :: Implicit Passage [rule($variable == 2)]
  weight(1000)
  Use weight to give passages higher priority. (default is 1)

--------------------


	1.8. display()
	==============

Displays another passage in it's place. All of the passages functions will be run.


		1.8.1. passage display
		======================

  display(Passage Title)


		1.8.2. query display
		====================

Perform a query to display a passage. Variable assignments are done within the body of display.

  display($key = value)

multiple assignments are separated by ;

  display($key = value; $anotherKey = value)

--------------------


	1.9. set()
	==========

Variables are used throughout fate. Variables are stored in alpha-numeric keys that begin with a $. The following are valid variable names.

  $myVariable
  $myVariable2
  $123MyVariable
  $MY_VARIABLE

Variables can store floats or strings.

floats
any numerical value.
strings
any text value.

There are no special decorations for setting the type of a variable.


		1.9.1. Assignment
		=================

You can assign variables in the following ways.

  set($variableName = 123)
  set($otherVariable = "Text Value")

Multiple assignments are separated by ;

  set($variableName = 123; $otherVariable = "Text Value")

You can assign one variable to another. Conversion between text and numbers will be attempted?

  set($variableName = $otherVariable)

This assigns the value if it is greater than the key's existing value

  set($variableName >= 123)

With text keys, this assigns the value if it's length is greater than the key's existing length

  set($variableName >= "some text")

This assigns the value if it is lesser than the key's existing value

  set($variableName <= 123)

With text keys, this assigns the value if it's length is lesser than the key's existing length

  set($variableName <= "some text")


		1.9.2. Basic math
		=================

Addition

  set($variableName += 123)

Addition with text keys, the specified text will be appended to the key

  set($variableName += "new text")

Subtraction

  set($variableName -= 123)

Subtraction with text keys, the specified text will be removed if it is found in the key

  set($variableName -= "text to remove")

Multiplication

  set($variableName *= 123)

Division

  set($variableName /= 123)


		1.9.3. Percentage math
		================

Special commands that make it easier to work with percentile stats.

Percentage addition

  set($variableName %+ 20)

Percentage subtraction

  set($variableName %- 20)

--------------------


	1.10. math()
	============

There are a few useful math functions available.


		1.10.1. abs
		===========

abs turns the key into it's absolute value.

  math("abs", $variableName)


		1.10.2. ceiling
		===============

ceiling raises the key to the next greater integer value.

  math("ceiling", $variableName)


		1.10.3. floor
		=============

floor lowers the key to the next lesser integer value.

  math("floor", $variableName)


		1.10.4. round
		=============

round changes the key to the closest integer value.

  math("round", $variableName)


		1.10.5. random
		==============

random assigns a floating point value between 0.0 and 1.0 to the key.

  math("random", $variableName)

--------------------


	1.11. print()
	=============

Display the numeric or text value of a variable in it's place.

  print($variableName)

--------------------


	1.12. either()
	==============

Display different text by chance

  You can use either(red|blue|any) to display different text by chance.

You can nest print inside either.

  either(print($money)|print($time)).

====================


  2. Special Stuff
  ================


	2.1. Rich text formatting
	=========================

The following are ways to format text. Check Unity's UI Rich Text Docs for details http://docs.unity3d.com/Manual/StyledText.html

bold

  <b>bold</b>

italic

  <i>italic</i>

size

  <size=50>pixelSize</size>

color

  <color=#00ffffff>color</color>

--------------------


	2.2. Comments
	=============

Comments allow you to comment anywhere within source code. They get excluded from the games output.

  This is a passage /* Example */ of text.

  This is a passage of /* Example multi line comment.
  
  */ text.

 You can't nest comments.

  /* /* Example */ */

--------------------


	2.3. Named constants
	====================

Enum is a useful way to have named constants for arbitrary numerical values throughout source files.

  set($stopLightState = enum.off)

--------------------


	2.4. control()
	==============

Controls are used to control player interaction.


		2.4.1. end
		==========

Saves the game and prevents further player interaction

  control("end")
  


		2.4.2. player
		=============

Sets the perspective of the world, to the specified Noun. Once a noun is set as the player, the game world will be seen from that noun's perspective. 
The player has access to actions on the following: them self, their parent, all nouns with the same parent (siblings), and all nouns that they are the parent of (children). Nouns with the player as a parent are visualized in a separate inventory during the game.

  control("player", Jane)

note that this will also set the value of the $player key to the specified noun.

====================


  3. World System
  ===============


	3.1. Nouns
	==========

Nouns can be anything that exists in the simulated game world. 

  :: Living Room [noun()]

Nouns have a single parent that define where they are located in the world. The default location can be set in the definition. This can also be changed during the game with the move() function.

  :: Chair [noun(Living Room)]

Nouns can be anything that exists in the simulated game world. 

  :: Living Room [noun()]

Nouns must have unique names within the source code, but they can have a displayed name that is different in game. 

  :: Room|Room A [noun()]
  Here the player will see this as a room.
  
  :: Room|Room B [noun()]
  Here the player will see this as a room.

The text in the body of a noun declaration will automatically be mapped to an examine verb. You can avoid this by simply not providing any text.

  :: Ball [noun(Living Room)]
  Default examine passage body

Use criteria to make more specific examine descriptions

  :: Ball [noun(Living Room)]
  Default examine passage body
  
  criteria($key >= 6626)
  More specific examine passage body
  
  criteria($key < 6626)
  More specific examine passage body

--------------------


	3.2. Verbs
	==========

Nouns can be acted upon by the player using verbs.

  :: Sit Down [verb(Chair)]
  This text will be the response to the Sit Down action on the chair.
  Note that you can't define a verb before the noun that it is associated with.

criteria can be used to define more specific results of using a verb

  :: Kick Ball [verb(Ball)]
  We can use multiple criteria within a verb declaration to allow state aware responses.
  
  criteria($ballInflated == 0)
  You kick the ball and it barely moves.
  
  criteria($ballInflated == 1)
  You kick the ball and it moves swiftly away.

--------------------


	3.3. require()
	==============

Require allows you to set a limitation on the availability of a verb to the player, based on conditions. require arguments are the same as criteria

  :: Inflate [verb(Ball)]
  require($ballInflated == 0 && Air Pump -> Jane)
  Also notice that we are using the -> (is in) syntax within the require.

Notice that we can stack require and criteria statements to control when a verb can be used, and what responses we will get.

  :: Throw Ball [verb(Ball)]
  require($ballInflated == 0 && Hoop -> Living Room)
  Some Response
  
  criteria($janeHasSneaks == 1)
  You throw the ball mercilessly.
  
  criteria($janeHasSneaks == 0)
  You throw the ball your best.
  
  require($ballInflated == 1 && Chair -> Living Room)
  
  criteria($chairIsBouncy == 0)
  You use the chair to jump up and dunk the ball.
  
  criteria($chairIsBouncy == 1)
  You use the bouncy chair to jump up and dunk the ball.

--------------------


	3.4. move()
	===========

move moves nouns around

  :: Take [verb(Ball)]
  move(Ball -> Jane)
  To change the location of a noun, use move. Notice the -> syntax. This is essentially how you can move the player around, and move items to and from their inventory.

You can use $player as a move target or destination. $player can also be a key in criteria comparison

  criteria($player == Jane)
  move(Leprechaun -> $player)
  In games with multiple player characters it is useful to have a variable to use in place of an explicit noun.
  $player holds the current noun that has been set as the player, and can be used in criteria and require functions.

multiple assignments are separated by ;

  move(Leprechaun -> $player; noun -> noun)

====================


  4. Game Information
  ===================


	4.1. content()
	==============

Information about the game can be added anywhere within any source file.


		4.1.1. author
		=============

The primary author of the game.

- Called once.
- Single line expected.

  content("author", "Some Name")


		4.1.2. brief description
		========================

Short 140 character description of the game.

- Called once.
- Single line expected.

  content("brief", "description of the game.")


		4.1.3. content descriptor
		=========================

A content descriptor for the game.

- Can call multiple times.

  content("contentDescriptor", "Lyrics - Mild references to profanity, sexuality, violence, alcohol or drug use in music")


		4.1.4. content rating
		=====================

The content rating of the game.

- Called once.

  content("contentRating", "MATURE
  
  Content is generally suitable for ages 17 and up. May contain intense violence, blood and gore, sexual content and/or strong language.")


		4.1.5. contributor
		==================

Name of a contributor to the project. Contributors will be sorted by number of occurrences.

- Can call multiple times.
- Single line expected.

  content("contributor", "Some Name")


		4.1.6. credits
		==============

Full credits list.

- Called once.

  content("credits", "Person - stuff
  Person - Other Stuff)


		4.1.7. full description
		=======================

Full description of the game.

- Called once.

  content("description", "Full description of the game.
  this is multiline and stuff.")


		4.1.8. identifier
		=================

Give the game a unique identifier.

- Called once.
- Single line expected.

  content("identifier", "com.CompanyName.GameName")


		4.1.9. license
		==============

Game legal information.

- Called once.

  content("license", "legal info here
  this is multiline and stuff.")


		4.1.10. phobia
		==============

Phobias or Trigger warnings.

- Can call multiple times.

  content("phobia", "Spiders")


		4.1.11. sensitive content
		=========================

Does the game include sensitive content?

- Called once. 
- Valid values are "true" or "false", defaulting to "false".

  content("sensitiveContent", "true")


		4.1.12. title
		=============

The title of the game.

- Called once.
- Single line expected.

  content("title", "Some Title")


		4.1.13. updates
		===============

Update history.

- Called once.
- Single line expected.

  content("updates", "v 2.5.6 - did stuff
  v 2.5.0 - did stuff")


		4.1.14. version
		===============

Name this version of the game.

- Called once.
- Single line expected.

  content("version", "v 2.5.6")

====================


  5. Saving
  =========

Game saves include all of the actions that the player has taken, along with all of the information required to restore the game to previous history states.The following items are included in a game save.


		5.0.1. save data
		================

- save name
- save time
- save identifier
- game is completed
- game identifier
- game title
- game version
- game snapshots
  - current variables
  - current displayed title
  - current displayed text
  - current displayed options