viewgit/inc/functions.php:22 Function utf8_encode() is deprecated [8192]

Tried to improve the grammar and clarity of all game.js and game.css comments

Chris Pollett [2023-02-04 23:Feb:th]
Tried to improve the grammar and clarity of all game.js and game.css comments
Filename
css/game.css
js/game.js
diff --git a/css/game.css b/css/game.css
index 6fda924..2a0bc4d 100644
--- a/css/game.css
+++ b/css/game.css
@@ -14,7 +14,7 @@
  * @link https://www.frise.org/
  * @copyright 2022 - 2023
  */
-/* make sure game tags we don't want to display, we don't display
+/* make sure game tags we don't want to display are not displayed
  */
 x-game,
 x-action
@@ -273,8 +273,8 @@ table.save-table td.save-name
     visibility: hidden;
 }
 /*
- * Styles specific to how we want HTML to appear in the game
- * as well as the new x- tags that we use for presentation
+ * Styles specific to how we want HTML to appear in the game.
+ * Also has styles for the new x- tags that we use for presentation
  */
 h1
 {
diff --git a/js/game.js b/js/game.js
index 2be96a6..afb5418 100644
--- a/js/game.js
+++ b/js/game.js
@@ -21,7 +21,7 @@
  * Contains {locale => {to_translate_id => translation}} for each
  * item in the game engine that needs to be localized.
  * There are not too many strings to translate. For a particular game you
- * could tack on to this tl variables after you load game.js in a script
+ * could tack on to this tl variable after you load game.js in a script
  * tag before you call initGame.
  * @type {Object}
  */
@@ -40,7 +40,7 @@ var tl = {
  */
 var locale = "en";
 /**
- * Boolean flag to set the text direction of the game to right-to-left.
+ * Flag to set the text direction of the game to right-to-left.
  * (if false, the text direction is left-to-right)
  * @type {boolean}
  */
@@ -62,7 +62,7 @@ var is_mobile = window.matchMedia("(max-width: 1000px)").matches;
  * Returns an Element object from the current document which has the provided
  * id.
  * @param {string} id of element trying to get an object for
- * @return {Element} desired element if exists, else null
+ * @return {Element} desired element, if exists, else null
  */
 function elt(id)
 {
@@ -72,7 +72,7 @@ function elt(id)
  * Returns a collection of objects for Element's that match the provided Element
  * name in the current document.
  *
- * @param {string} name of HTML/XML Element that want from current document
+ * @param {string} name of HTML/XML Element wanted from current document
  * @return {HTMLCollection} of matching Element's
  */
 function tag(name)
@@ -138,7 +138,7 @@ function sleep(time) {
   return new Promise(resolve => setTimeout(resolve, time));
 }
 /**
- * Add a link with link text message, which when clicked will allow the
+ * Adds a link with link text message which when clicked will allow the
  * rendering of a Location to continue.
  * @param {string} message link text for the link that is pausing the rendering
  *  of the current location.
@@ -156,10 +156,10 @@ function clickProceed(message)
 /**
  * Creates from an HTMLCollection or Nodelist of x-object or x-location
  * elements an array of Location's or Object's suitable for a FRISE Game
- * object. Elements of the collection whose name isn't of the form x-
+ * object. Elements of the collection whose name aren't of the form x-
  * or which don't have id's are ignored. Otherwise, the id field of
- * the output Cbject or Location is set to the value of the x-object or
- * x-location's id. Details about how a sutiable FRISE Game object is created
+ * the output Object or Location is set to the value of the x-object or
+ * x-location's id. Details about how a suitable FRISE Game object is created
  * can be found @see makeGameObject()
  *
  * @param {HTMLCollection|Nodelist} tag_objects collection to be converted into
@@ -179,7 +179,7 @@ function makeGameObjects(tag_objects)
 }
 /**
  * Upper cases first letter of a string
- * @param {string} str string to upper case first letter of
+ * @param {string} str string to upper case the first letter of
  * @return {string} result of upper-casing
  */
 function upperFirst(str)
@@ -203,7 +203,7 @@ var object_counter = 0;
  * Location object will be returned, otherwise, a Javascript Object is returned.
  * The innerHTML of any subtag of an x-object or an
  * x-location beginning with x- becomes the value of a field in the resulting
- * object with  the name of the tag less x-. For example, a DOM_object
+ * object with the name of the tag less x-. For example, a DOM Object
  * representing the following HTML code:
  * <x-object id="bob">
  *   <x-name>Robert Smith</x-name>
@@ -290,7 +290,7 @@ function makeGameObject(dom_object)
 /**
  * Used to change the display css property of the element of the provided id
  * to display_type if it doesn't already have that value, if it does,
- * then the display property is set to none.. If display_type is not provided
+ * then the display property is set to none. If display_type is not provided
  * then its value is assumed to be block.
  *
  * @param {string} id of HTML Element to toggle display property of
@@ -359,7 +359,7 @@ function toggleMainNav()
 }
 /**
  * Adds click event listeners to all anchor objects in a list
- * such that have href targets beginning with #. Such a target
+ * that have href targets beginning with #. Such a target
  * is to a location within the current game, so the click event callback
  * then calls game.takeTurn based on this url.
  *
@@ -380,7 +380,7 @@ function addListenersAnchors(anchors)
             anchor.addEventListener('click', (event) => {
                 if (!anchor.classList.contains('disabled')) {
                     game.takeTurn(hash);
-                    if (game.hasNavBar && call_toggle) {
+                    if (game.has_nav_bar && call_toggle) {
                         toggleMainNav();
                     }
                 }
@@ -400,9 +400,9 @@ function addListenersAnchors(anchors)
  * might have several x-present tags, some of which could
  * be drawn after a clickProceed, or a delay. As these
  * steps in rendering are not good "save places", at the
- * start of rendering a location all save are disabled.
+ * start of rendering a location, all save are disabled.
  * Only after the last drawable x-present for a location
- * has completed at they renabled.
+ * has completed are they renabled.
  */
 function disableSavesAndInventory()
 {
@@ -436,10 +436,10 @@ function enableSavesAndInventory()
 /**
  * Given a string which may contain Javascript string interpolation expressions,
  * i.e., ${some_expression}, produces a string where those expressions have
- * been replaces with their values.
+ * been replaced with their values.
  *
  * @param {string} text to have Javascript interpolation expressions replaced
- *  values
+ *  with their values
  * @return {string} result of carrying out the replacement
  */
 function interpolateVariables(text)
@@ -487,8 +487,8 @@ function loc(location_id)
 class Location
 {
     /**
-     * An array of [check_condition, text_to_present] pairs typically
-     * coming from the x-present-tag's of a in the HTML of a Location.
+     * An array of [check_condition, staging, text_to_present] triples typically
+     * coming from the x-present-tag's in the HTML of a Location.
      * @type {Array}
      */
     present = [];
@@ -498,11 +498,11 @@ class Location
      * in the x-location tag from which the Location was parse. For
      * each such x-present tag in the order it was in the original HTML,
      * the ck condition is first evaluated (this may contain a delay
-     * or clickProceed call or a boolean expression), once/if condition is
-     * satisfied then the HTML contents of the tag are shown. If the case,
-     * where the ck evaluates to false that x-present tags contents are
-     * omitted. In addition to usual HTML tags, a x-present tag can
-     * have x-speaker subtags. These llow one to present text from a speaker
+     * or clickProceed call or a boolean expression), once/if the condition is
+     * satisfied, then the HTML contents of the tag are shown. In the case,
+     * where the ck evaluates to false that x-present tag's contents are
+     * omitted. In addition to the usual HTML tags, an x-present tag can
+     * have x-speaker subtags. These allow one to present text from a speaker
      * in bubbles. An x-present tag may also involve input tags to
      * receive/update values for x-objects or x-locations.
      */
@@ -541,14 +541,14 @@ class Location
     /**
      * Prepares input, textareas, and select tags in the game so that they can
      * bind to game Object or Location fields by adding various Javascript
-     * Event handlers. An input tag like:
+     * Event handlers. An input tag like
      * <input data-for="bob" name="name" >
-     * Binds with the name field of the bob game object (i.e., obj(bob).name).
+     * binds with the name field of the bob game object (i.e., obj(bob).name).
      * In the case above, as the default type of an input tag is text, this
      * would produce a text field whose initial value is the current value
      * obj(bob).name. If the user changes the field, the value of the obj
-     * changes with it. This set up binds input tags regardless of type,
-     * can use with it with other types such as range, email, color, etc.
+     * changes with it. This set up binds input tags regardless of type, so it
+     * can be used with other types such as range, email, color, etc.
      */
     prepareControls()
     {
@@ -630,12 +630,14 @@ class Location
         }
     }
     /**
-     * Evaluates the condition from a ck attribute ofan x-present tag.
+     * Evaluates the condition in a ck attribute of an x-present tag.
      *
      * @param {string} condition contents from a ck or check attribute.
-     *  Conditions can be boolean conditions on game variable.
+     *      Conditions can be boolean conditions on game variables.
+     *      If an x-present tag did not have a ck attribute, condition is null.
      * @param {string} staging contents from a stage attribute.
-     *      If none empty, such an attribute could have a sequence of
+     *      If no such attribute, this will be an empty string.
+     *      Such an attribute could have a sequence of
      *      pause(some_millisecond); and clickProceed(some_string) commands
      * @return {Array} [check_result, proceed, pause] if the condition involved
      *  a boolean expression, then check_result will hold the result of
@@ -644,7 +646,7 @@ class Location
      *  link for the first clickProceed (which is supposed to delay the
      *  presentation of the x-present tag until after the user clicks the
      *  link) if found (else ""), pause (if non zero) is the number of
-     *  miliseconds to sleep before presenting the x-pressent tag according to
+     *  milliseconds to sleep before presenting the x-present tag according to
      *  the condition
      */
     evaluateCheckConditionStaging(condition, staging)
@@ -731,7 +733,7 @@ class Location
     }
 }
 /**
- * Classed used to encapsulate an interactive story game. It has fields
+ * Class used to encapsulate an interactive story game. It has fields
  * to track the locations and objects in the game, the history of moves of
  * the game, and how many moves have been made. It has methods to
  * take a turn in such a game, to save state, load state,
@@ -748,7 +750,7 @@ class Game
      */
     id;
     /**
-     * Current date followed by a space followedby the current time of
+     * Current date followed by a space followed by the current time of
      * the most recent game capture. Used in providing a description of
      * game saves.
      * @type {number}
@@ -756,41 +758,41 @@ class Game
     timestamp;
     /**
      * A counter that is incremented each time Javascript draws a new
-     * clickProceed a tag. Each such tag is given a id, tick is ensure these
-     * id's are unique.
+     * clickProceed a tag. Each such tag is given an id, tick is used to ensure
+     * these id's are unique.
      * @type {number}
      */
     tick = 0;
     /**
-     * Whether this particular game has a nav bar
+     * Whether this particular game has a nav bar or not
      * @type {boolean}
      */
-    hasNavBar;
+    has_nav_bar;
     /**
-     * The list of all Game Object's managed by the FRISE script. An object
+     * List of all Game Object's managed by the FRISE script. An object
      * can be used to represent a thing such as a person, tool, piece of
-     * clothing, letter, etc. In an HTML document an object is defined using
-     * an x-object tag.
+     * clothing, letter, etc. In an HTML document, a game object is defined
+     * using  an x-object tag.
      * @type {Array<Object>}
      */
     objects;
     /**
-     * The list of all Game Location's managed by the FRISE script. A Location
+     * List of all game Location's managed by the FRISE script. A Location
      * can be used to represent a place the main character can go. This
-     * could be standard locations in the game, as wells as Lcoations
+     * could be standard locations in the game, as well as Locations
      * like a Save page, Inventory page, Status page, etc.
-     * In an HTML document a Location is defined using an x-location tag.
+     * In an HTML document a game Location is defined using an x-location tag.
      * @type {Array<Location>}
      */
     locations;
     /**
      * Used to maintain a stack (using Array push/pop) of Game State Objects
-     * based on the turns the user has taken (top of stack corresponds
+     * based on the turns the user has taken (the top of the stack corresponds
      * to the previous turn). A Game State Object is a serialized string:
-     * {
-     *  timestamp: capture_time,
-     *  objects: array_of_game_objects_at_capture_time,
-     *  locations: array_of_game_locations_at_capture_time,
+     *  {
+     *    timestamp: capture_time,
+     *    objects: array_of_game_objects_at_capture_time,
+     *    locations: array_of_game_locations_at_capture_time,
      *  }
      * @type {Array}
      */
@@ -798,20 +800,20 @@ class Game
     /**
      * Used to maintain a stack (using Array push/pop) of Game State Objects
      * based on the the number previous turn clicks the user has done.
-     * I.e.,when a user clicks previous turn, the current state is pushed on
-     * to this array so that it the user then clicks next turn the current
-     * state canbe restored.
+     * I.e., when a user clicks previous turn, the current state is pushed onto
+     * this array so that if the user then clicks next turn the current
+     * state can be restored.
      * A Game State Object is a serialized string:
-     * {
-     *  timestamp: capture_time,
-     *  objects: array_of_game_objects_at_capture_time,
-     *  locations: array_of_game_locations_at_capture_time,
+     *  {
+     *    timestamp: capture_time,
+     *    objects: array_of_game_objects_at_capture_time,
+     *    locations: array_of_game_locations_at_capture_time,
      *  }
      * @type {Array}
      */
     future_history;
     /**
-     * Sets up game object with empty history, an initialized main navigation,
+     * Sets up a game object with empty history, an initialized main navigation,
      * and with objects and locations parsed out of the current HTML file
      */
     constructor()
@@ -842,12 +844,12 @@ class Game
     }
     /**
      * Sets up the main navigation bar and menu on the side of the screen
-     * determined  by the is_right_to_left variable, sets up an initially empty
+     * determined  by the is_right_to_left variable. Sets up an initially empty
      * game content area which can be written to by calling a Location
-     * object's renderPresentation. The main navigation consists of hamburger
-     * menu toggle button for the navigation as well as previous,
+     * object's renderPresentation. The main navigation consists of a hamburger
+     * menu toggle button for the navigation as well as previous
      * and next history arrows at the top of screen. The rest of the main
-     * navigation content is determined by the contentsof the x-main-nav
+     * navigation content is determined by the contents of the x-main-nav
      * tag in the HTML file for the game. If this tag is not present, the
      * game will not have a main navigation bar and menu.
      */
@@ -867,10 +869,10 @@ class Game
         let main_nav_objs = tag("x-main-nav");
         if (typeof main_nav_objs[0] === "undefined") {
             game_screen.innerHTML = `<div id="game-content"></div>`;
-            this.hasNavBar = false;
+            this.has_nav_bar = false;
             return;
         }
-        this.hasNavBar = true;
+        this.has_nav_bar = true;
         let main_nav_obj = main_nav_objs[0];
         let history_buttons;
         if (is_right_to_left) {
@@ -897,9 +899,10 @@ class Game
         this.initializeGameNavListeners();
     }
     /**
-     * Used to initialize the event listerns for the next/previous history
+     * Used to initialize the event listeners for the next/previous history
      * buttons. It also adds listeners to all the a tag and x-button tags
-     * to process the href before following any links to the target.
+     * to process their href attributes before following any link is followed
+     * to its target.
      * @see addListenersAnchors
      */
     initializeGameNavListeners()
@@ -917,10 +920,12 @@ class Game
         addListenersAnchors(anchors, is_mobile);
     }
     /**
-     * Checks if the game is being played on mobile device. If not, this
-     * method does nothing; if it is, sets up the viewport so HTML will
-     * display properly. Also, in the case of playing on a mobile device,
-     * sets it so the main nav bar on the side of the screen is closed.
+     * Checks if the game is being played on a mobile device. If not, this
+     * method does nothing, If it is being played on a mobile device,
+     * then this method sets up the viewport so that the HTML will
+     * display properly. Also, in the case where the game is being played on a
+     * mobile device, this method also sets it so the main nav bar on the side
+     * of the screen is closed.
      */
     initializeScreen()
     {
@@ -928,7 +933,7 @@ class Game
         if (is_right_to_left) {
             html.classList.add("rtl");
         }
-        if (!this.hasNavBar) {
+        if (!this.has_nav_bar) {
             html.classList.add("no-nav");
         }
         if(!is_mobile) {
@@ -941,8 +946,8 @@ class Game
         toggleMainNav();
     }
     /**
-     * For each object, if object.position is defined, then add the object
-     * to the location.item array of the Location who id is
+     * For each object, if object.position is defined, then adds the object
+     * to the location.item array of the Location whose id is
      * given by object.position .
      */
     initializeObjectsLocations()
@@ -964,9 +969,9 @@ class Game
         }
     }
     /**
-     * Create a JSON encoded string representing the current state of
-     * the game (all object and location states and where the main character
-     * is).
+     * Creates a JSON encoded string representing the current state of
+     * the game (all of the object and location states and where the main
+     * character is).
      *
      * @return {string} JSON encoded current state of game.
      */
@@ -1010,8 +1015,8 @@ class Game
         for (const field in old_objects) {
             if (!this.objects.hasOwnProperty(field)) {
                 /* we assume our game never deletes objects or locations, so
-                   if we find an object in old_objects (presumably coming
-                   from a more recently parse HTML file) that was not
+                   if we find an object in old_objects (presumably it's coming
+                   from a more recently parsed HTML file) that was not
                    in the saved state, we copy it over.
                  */
                 this.objects[field] = old_objects[field];
@@ -1053,7 +1058,8 @@ class Game
     }
     /**
      * Deletes the game state capture history for the game. After this
-     * is games the next and previous arrow buttons won't do anything.
+     * calling this method, the game's next and previous arrow buttons
+     * won't do anything until new turns have occurred.
      */
     clearHistory()
     {
@@ -1066,9 +1072,9 @@ class Game
         }
     }
     /**
-     * Function called when the left arrow button on the main nav page is
-     * clicked to go back one turn in the game. Pushes the current game state
-     * to the future_history game state history array, then pops the most
+     * Called when the left arrow button on the main nav page is
+     * clicked to go back one turn in the game history. Pushes the current
+     * game state to the future_history game state array, then pops the most
      * recent game state from the history game state array and sets it as
      * the current state.
      */
@@ -1091,8 +1097,8 @@ class Game
         elt('next-history').disabled = false;
     }
     /**
-     * Function called when the right arrow button on the main nav page is
-     * clicked to go forawrd one turn in the game (assume the user had
+     * Called when the right arrow button on the main nav page is
+     * clicked to go forward one turn in the game history (assuming the user had
      * clicked previous at least once). Pushes the current game state
      * to the history game state array, then pops the game state from the
      * future_history game state array and sets it as the current state.
@@ -1116,9 +1122,9 @@ class Game
         elt('previous-history').disabled = false;
     }
     /**
-     * Initializes the save slots for saves location page of a game.
-     * This involves looking at session storage and determine which slots
-     * have games alread save to them and for those slots determining also
+     * Initializes the save slots for the saves location page of a game.
+     * This involves looking at session storage and determining which slots
+     * have games already saved to them, and for those slots, determining also
      * what time the game was saved.
      */
     initSlotStates()
@@ -1149,9 +1155,9 @@ class Game
         }
     }
     /**
-     * Saves the current state to a sessionStorage save slot if that
+     * Saves the current game state to a sessionStorage save slot if that
      * slot if empty; otherwise, if the slot has data in it, then sets
-     * the current game state to the state stored at that slot. When saving
+     * the current game state to the state stored at that slot. When saving,
      * this method also records the timestamp of the save time to the
      * game's saves location.
      *
@@ -1178,12 +1184,12 @@ class Game
     }
     /**
      * Deletes any game data from sessionStorage at location
-     * "slot" + slot_number, updates the game's save location to reflect the
+     * "slot" + slot_number, updates the game's saves location to reflect the
      * change.
      *
      * @param {number} slot_number which save game to delete. Games are stored
-     *   at a sessionStorage  field "slot" + slot_number where it is intended
-     *   (but not enforced) that slot_number be an integer.
+     *   at a sessionStorage field "slot" + slot_number where it is intended
+     *   (but not enforced) that the slot_number be an integer.
      */
     deleteSlot(slot_number)
     {
@@ -1211,8 +1217,8 @@ class Game
         this.evaluateAction(saves_location['default-action']);
     }
     /**
-     * Launches a file picker to allowthe user to select a file
-     * containing a saved game state, then tries to loads the current game
+     * Launches a file picker to allow the user to select a file
+     * containing a saved game state, then tries to load the current game
      * from this file.
      */
     load()
@@ -1255,7 +1261,7 @@ class Game
      * fragment. A url hash fragment is the part of the url after a # symbol.
      * In non-game HTML, #fragment is traditionally used to indicate the browser
      * should show the page as if it had been scrolled to where the element
-     * with id attribute fragment is. In the FRISE game a fragment has
+     * with id attribute fragment is. In a FRISE game, a fragment has
      * the form #action_1_name;action_2_name;...;action_n_name;next_location_id
      * Such a fragment when processed by takeTurn will cause the Javascript in
      * x-action tags with id's action_1_name, action_2_name,...,action_n_name
@@ -1263,10 +1269,10 @@ class Game
      * location next_location_id.  If the fragment, only consists of
      * 1 item, i.e., is of the form, #next_location_id, then this method
      * just moves the main-character to next_location_id.
-     * After carrying out the action and move the main-character,
+     * After carrying out the action and moving the main-character,
      * takeTurn updates the game state history and future_history
      * accordingly. Then for each object and each location,
-     * if the object/location, has a x-default-action tag, this default action
+     * if the object/location, has an x-default-action tag, this default action
      * is executed. Finally, the Location of the main-character is presented
      * (its renderPresentation is called).
      * takeTurn supports two special case action #previous and #next
@@ -1277,7 +1283,7 @@ class Game
      */
     takeTurn(hash)
     {
-        if (this.hasNavBar) {
+        if (this.has_nav_bar) {
             if (hash == "#previous") {
                 this.previousHistory();
                 return;
@@ -1294,7 +1300,7 @@ class Game
             return;
         }
         this.future_history = [];
-        if (this.hasNavBar) {
+        if (this.has_nav_bar) {
             elt('next-history').disabled = true;
         }
         if (sessionStorage["current" + game.id]) {
@@ -1304,7 +1310,7 @@ class Game
         this.evaluateDefaultActions(this.locations);
         sessionStorage["current" + game.id] = this.captureState();
         this.describeMainCharacterLocation();
-        if (this.hasNavBar) {
+        if (this.has_nav_bar) {
             if (this.history.length == 0) {
                 elt('previous-history').disabled = true;
             } else {
@@ -1314,8 +1320,8 @@ class Game
     }
     /**
      * For each game Object and each game Location in x_entities evaluate the
-     * Javascript (if exists) of its default action (from it x-default-action
-     * tag).
+     * Javascript (if it exists) of its default action (from its
+     * x-default-action tag).
      *
      * @param {Array} of game Object's or Location's
      */
@@ -1329,7 +1335,7 @@ class Game
         }
     }
     /**
-     * Moves a game Object to a new game Location. If the object had
+     * Moves a game Object to a new game Location. If the object had a
      * previous location, then also deletes the object from there.
      *
      * @param {string} object_id of game Object to move
@@ -1405,7 +1411,7 @@ class Game
     /**
      * Given a string holding pre-Javascript code from an x-action tag,
      * evaluates the code. If this function  is passed additional arguments
-     * then an args array is set up that can be used as closure variable for
+     * then an args array is set up that can be used as a closure variable for
      * this eval call.
      *
      * @param {string} Javascript code.
@@ -1421,7 +1427,7 @@ class Game
         eval(code);
     }
     /**
-     * Used to present the location the Main Character is currently at.
+     * Used to present the location that the Main Character is currently at.
      */
     describeMainCharacterLocation()
     {
@@ -1432,7 +1438,7 @@ class Game
     }
 }
 /**
- * Module initialization function, used to set up the game object corresponding
+ * Module initialization function used to set up the game object corresponding
  * to the current HTML document. If there is a current game state in
  * sessionStorage it is used to initialize the game state, otherwise,
  * the game state is based on the start of the game. After this state is
ViewGit