READMEs and comments

README.md

@@ -11,7 +11,7 @@ Here's what you can see here:
 * International support
 * HTML5 sound effects with volume control
 * Graphical effects
-* Realtime timer
+* Realtime events
 * Menu dialogue section
 
 #### International support
@@ -31,6 +31,26 @@ Please.
 See `Gulpfile.js.`
 The trick is to concatenate your files before every build.
 
+#### The custom text cycling
+A cycling link is a "replacer" hyperlink that replaces its contents with another text.
+The game implies that a situation cannot have more than one cycling link.
+
+The basic function for a replacer link is this:
+`textcycle = (content, ref) -> a(content).replacer(ref).class("cycle").id(ref).toString()`
+
+The `shoot_pacifist` situation uses only this function to do a text cycle.
+But there's also a more advanced version.
+
+The function `cycle` expects your situation to have a replacer action `cyclewriter`
+written like this:
+
+    cyclewriter: (character) -> cycle(this, character)
+
+Also it expects your situation to have a `cycle_gallery` function.
+This is the function that returns your text strings.
+
+You can see how it's done in the `start` situation.
+
 ## MIT License
 Copyright © 2015 Alexander Yakovlev, http://en.oreolek.ru
 

game/begin.coffee

@@ -3,11 +3,15 @@ undum = require('undum-commonjs')
 oneOf = require('raconteur/lib/oneOf.js')
 qualities = require('raconteur/lib/qualities.js')
 
+# load the translations
 undumloc = require("./translations/ru.coffee").language
 undum.language["ru"] = undumloc
 undumloc = require("./translations/en.coffee").language
 undum.language["en"] = undumloc
+
+# jQuery is used for showing the custom controls when the player clicks on title
 $ = require("jquery")
+# jQuery UI is for volume slider
 require('jquery-ui/slider');
 
 Array.prototype.oneOf = () ->
@@ -18,11 +22,16 @@ markdown = new md({
   html: true
 })
 
+# unique UUID
 undum.game.id = "7a1aba32-f0fd-4e3b-ba5a-59e3fa9e6012"
+# You bump the version each time you make a save-breaking bug, i.e. change the game logic.
+# Comment and text changes should be fine.
 undum.game.version = "3.6"
 
 a = require('raconteur/lib/elements.js').a
+# link to a different situation. Styled differently. Not used in this project.
 way_to = (content, ref) -> a(content).class('way').ref(ref)
+# link to a writer action. Not used in this project.
 textlink = (content, ref) -> a(content).once().writer(ref)
 textcycle = (content, ref) -> a(content).replacer(ref).class("cycle").id(ref).toString()
 # Cycling link. It's implied there can be only one per situation.
@@ -36,11 +45,14 @@ cycle = (obj, character) ->
   if character.sandbox.cycle_index[obj.name] == responses.length
     character.sandbox.cycle_index[obj.name] = 0
   return textcycle(response, 'cyclewriter')
+# usage: writemd( system, "Text to write")
 writemd = (system, text) ->
   if typeof text is Function
     text = text()
   system.write(markdown.render(text))
 
+# The first situation. It should be before is_visited because is_visited expects
+# the situations array to be already initialized with something.
 situation "start",
   cycle_gallery: () -> "christine".l()
   content: (character) ->

game/end.coffee

@@ -1,4 +1,7 @@
 
+# This game does not *show* any qualities but it uses them.
+# You can even resurrect the qualities block from the previous commits
+# and it would work!
 qualities
   head:
     bullets: qualities.integer("bullets".l()),

html/en.html

@@ -41,7 +41,7 @@
         <div class="row">
           <div id="legal">
             <div id="footleft">
-              <p>Approximate play time: five minites.</p>
+              <p>Approximate play time: three minites.</p>
               <p>Made using <a href="http://undum.com">Undum</a> and <a href="http://sequitur.github.io/raconteur/">Raconteur</a>.</p>
               <p class="text-muted">Betatesting credit: headless zombie, Kie Kazuki, <a href="http://udivas.livejournal.com/profile" target="_blank">udivas</a></p>
             </div>

html/index.html

@@ -43,7 +43,7 @@
       <div class="row">
         <div id="legal">
           <div id="footleft">
-            <p>Приблизительное время прохождения игры: пять минут.</p>
+            <p>Приблизительное время прохождения игры: три минуты.</p>
             <p>Написано при помощи <a href="http://undum.com" target="_blank">Undum</a> и <a href="http://sequitur.github.io/raconteur/" target="_blank">Raconteur</a>.</p>
             <p class="muted">Бета-тестеры: headless zombie, Kie Kazuki, <a href="http://udivas.livejournal.com/profile" target="_blank">udivas</a></p>
           </div>