Commentary mode definitions, 2011-09-08:
----------------------------------------
 CURRENT HIGHEST NODE (2011-09-08): 001

Activating "Commentary Mode" in Rell-Too, enables (age-wide) the
display of icons, which a visitor can click, to hear an out-of-cavern
message from one of the contributors.

 - The Commentary_mode toggle switch is a line of text in the top right
   corner of the Blackboard near the Link-in point.

 - All commentary content is contained on PAGE_1 (and on layer 20 in Blender). 
   The commentary mode switch simply pages it -in and -out.

 - The icons are simple free-floating objects in the likeness of flat pen nibs.

 - When clicked, a commentary node plays its message once. 
   Playback can be interrupted and reset, by clicking the node a second time.

 - You are not discouraged from creating more complex, multi-stage nodes 
   (such as, say, a step-by-step hints system), but the current script only 
   supports the simple "one-shot" On/Off nodes, described above.
   If you wish to implement something beefier, but are unsure how 
   to go about it; let me know and I'll see if I can help -- I have a decent
   idea about how to implement a simple and intuitive version of the icon,
   with a superimposed progress_indicator/GUI sprite, which would let the
   player step through hint levels, without accidently hearing "too much".


  Guidelines:
  -----------

  - All objects that has to do with commentary are kept on 
    layer 20 in Blender. (lower right, in the button bank pair)

  - All commentary objects shall be on page 1. 
    Do this by giving them the logic property: string = "page_num = 1"
    
  - Naming convention: Each node has at least 2 objects, typically:
         1 "commentary_nnn_node"  -  The clickable icon
         1 "commentary_nnn_rgn"   -  A region which restricts operation
         1 "commentary_nnn_snd"   -  A sound emitter (optional)
       ...where "nnn" is a three digit serial 
       number, common to all objects belonging to the node. 
       FIND THE CURRENT HIGHEST SERIAL NUMBER AT THE BEGINNING OF THIS README.
       (...and please do update it, if you add a node.)
    If your node needs additional objects, please name them in accordance
    with the pattern shown above: "commentary_nnn_", appended with your own
    designations, such as: "aux-1", "aux-2", etc... 
     (preferrably all in lower case)

  - The Logic Action for a simple commentary node is the pythonfile:
    "relltooCommentaryNodeClick.py", which shall be passed the following
    parameters:
         1) activator  -  The calling logicmod
         2) responder  -  The START responder that plays back the message.
                          The contents of this responder can be as complex as
                          you wish; from just one audio message, to longer
                          presentations which may e.g. give the player a ride,
                          during which objects and paths are highlighted in
                          sequence and accompanied with slideshows, to explain 
                          how something works or evolved -- anything that you
                          can do within in a respondermod.
                          THIS RESPONDER MUST MAKE A "NOTIFY" CALLBACK MESSAGE
                          TO THE SCRIPT, WHEN IT HAS FINISHED, SO THAT IT CAN
                          KEEP TRACK OF PLAYBACK/IDLE STATE.
         3) responder  -  The STOP responder, that breaks off- and resets all
                          playback ,at the end, or at user "cease" command
                          (icon activated again, during playback).
         4) string     -  A text message that is shown when playback starts.
                          It should name the Author of the node, the Topic of
                          the commentary and how long it takes to play back, 
                          each written on a new line, with approprate headers.
                          Additional information is optional.
                          The message will be padded by the script, with 
                          "playback starts" and "don't panic" type info.
         5) boolean    -  Freeze Avatar: If you set this to TRUE, player input
                          will be disabled during playback. You may wish to
                          do this e.g. if you take control of the camera, or
                          even the player's avatar itself, in any major way, 
                          but it should be avoided as far as possible, 
                          to avoid player irritation. :)


It is not as complicated as this whole long readme may make it look:

To only put in you own audio message: just copy every object and the 
alcscript, belonging to an older commentary node; rename the object copies 
and all references within the alcscript, with a fresh serial number and pop
in your own .ogg audio file.
(preferrably named along the pattern: "rellCommentaryNNN.ogg")