From 176597f13f44892cc055edfd93b5ede93d3bbc9c Mon Sep 17 00:00:00 2001 From: tajmone Date: Wed, 1 Sep 2021 11:16:54 +0200 Subject: [PATCH] [manual] Ch 5 Revisions Polish "5. Running An Adventure" by rephrasing some paragraphs, cleaning-up some formatting, annotating pending fixes, and other fixes that were planned for PR #126, which had to be squashed prematurely to allow the book partitioning changes planned in #133. --- manual/manual_05.adoc | 109 ++++++++++++++++++++++-------------------- 1 file changed, 57 insertions(+), 52 deletions(-) diff --git a/manual/manual_05.adoc b/manual/manual_05.adoc index e895fb3..0805e9e 100644 --- a/manual/manual_05.adoc +++ b/manual/manual_05.adoc @@ -1,27 +1,24 @@ // ****************************************************************************** // * * -// * 5. Running An Adventure * +// * 5. Running an Adventure * // * * // ****************************************************************************** -// The porting to AsciiDoc of this chapter is ultimated, but its contents need -// to be revised and polished here and there (see comments). -= Running An Adventure += Running an Adventure == A Turn of Events -// @NOTE: In the following paragraphs there are many Alan keywords, which should -// be styled as inline code. Maybe it's better not overdoing it, and just -// style a few keywords here and there, to clarify the context to reader -// and allow quickly spotting keywords in the page, but once a keyword has -// been styled as code in a sentence, further occurences don't need to be -// styled when the English meaning and the keyword overlap in that context. - The player controls the (((execution, of an adventure))) execution of an Alan adventure. -Each of his inputs are taken care of and acted upon by the run-time system in the interpreter. -The execution of an Alan adventure starts by executing the `Start` section. -The player is then placed in the `location` indicated in the `Start` section, the location is described, and the player is prompted for a command. +Each player input is taken care of and acted upon by the run-time system of the interpreter. +The execution of every Alan adventure begins from the `Start` section: the player is placed at the location indicated in the `Start` section, the location is described, and the player is prompted for a command. + +// Q: * After all the above has happened, what turn are we in? Turn 0 or 1? +// * Does the initial Start statement count as a turn? +// * Are any events executed during the Start section? +// The above questions should be covered in the initial paragraph(s), +// so that the reader is not left wondering about them (and not knowing +// where to look for their answers). The player input is analysed according to the explicit and implicit `Syntax` rules and converted to an execution of verb checks and bodies. Global `Verb` ``Check``s and bodies are used for verbs taking no parameters, otherwise the verb bodies are found in the parameter instances or their classes. @@ -34,22 +31,23 @@ Finally the player is prompted for another command. So, to summarise: -// @TODO: Could improve styling and layout of the following block: - -[literal, role="plaintext", subs="normal"] -................................................................................ -get and execute a player command -evaluate all rules -for each actor - execute one step (if active) - evaluate all rules as above -end for -for each pending event - execute it - evaluate all rules -end for -................................................................................ - +// @NOTE: The following scheme could be improved upon in various ways. +// It could benefit from having clear markers for PLAYER INPUT, RULES, +// SCRIPTS, EVENTS. We could also convert it to a flow chart using Dia, +// which would also allow us to illustrate player input branching. e.g. +// when the input didn't parse correctly, or when a CHECK fails, etc., +// which would make much clearer when a turn is aborted! + +* get and execute a player command +* evaluate all rules +* for each actor +** execute one step (if active) +** evaluate all rules as above +* end for +* for each pending event +** execute it +** evaluate all rules +* end for A player command may be either a verb command or a directional command. A verb command is executed by checking the syntax of the input, performing any preconditions (``Check``s) and then executing the verb bodies (as described in <> and <>). @@ -75,11 +73,6 @@ The exact list of these words, for every language natively supported in Alan, is The following built-in syntax variations are available to the player: -// @NOTE: I've styled in ALL-CAPS the player-words in the examples, to highlight -// them. It makes sense, because often there are multiple player-words in -// in an input command, and we want the reader to focus only on the ones -// being exemplified. - * Concatenation of commands via (((AND (player input)))) (((THEN (player input)))) *AND*-words, like: + [example,role="gametranscript"] @@ -137,17 +130,25 @@ This allows: > _remove the hat and the scarf then drop THEM_ ================================================================================ -// FIXME: The first sentence below could be polished a bit! - -The reference to multiple objects (or actors) in a position is only possible if the adventure author has allowed it by using a ((multiple indicator)) (((parameter, indicators, multiple))) in the `Syntax` definition (see <>). -All the variations above are built-in and handled automatically by the run-time system. +Referencing multiple instances (objects or actors) in a given command position is only possible if the adventure author has allowed it by using a +(((multiple indicator))) (((parameter, indicators, multiple))) +multiple `*` indicator in the `Syntax` definition (see <>). +All the above variations are built-into the interpreter and automatically handled by the run-time system. -The interpreter also automatically restricts (((parameter, referencing))) parameter references to things which are reachable according to the semantic rules of each built-in base class (see <> for the complete details). -For example, objects can only be referred to if they are present at the current location, except if the `Syntax` for the command uses the (((omnipotent indicator))) (((parameter, indicators, omnipotent))) omnipotent `!` indicator (see <> for details). +The interpreter also restricts (((parameter, referencing))) parameter references to things which are reachable according to the semantic rules of each built-in base class (see <> for the complete details). +For example, objects can only be referred to if they are present at the current location, except if the `Syntax` for the command uses the (((omnipotent indicator))) (((parameter, indicators, omnipotent))) +omnipotent `!` indicator (see <> for details). For some hints on ways to allow the player to refer to objects and actors that are not at the current location, refer to <>. If the player uses *ALL* instead of a reference to an instance in his command, the verb will be applied to all appropriate instances at the current location, _except_ the ones that do not pass all checks for the verb (see <> for further details on this). +// @NOTE: The above paragraph could be clearer about the difference of VERBs +// which are attempted and those which simply fail, when using ALL. +// Q: * How do the SYNTAX WHERE and VERB CHECKs differ here? + +A restriction placed on the player input by the interpreter is that the words the player is allowed to use can only contain alphanumeric characters, underscores and dash. +This must be kept in mind when naming verbs that use the default syntax (an explicit `Syntax` statement can always specify other player words to trigger the verb). + // @TODO: Could add xref to "4.2. Words, Identifiers and Names"! // @CHECK: Here it mentions "underscores and DASH", but it doesn't sound right. @@ -164,9 +165,6 @@ If the player uses *ALL* instead of a reference to an instance in his command, t // encoding (ISO-8859-1, or others). It might be better to specify // "letters, numbers, underscores and hyphens" -A restriction placed on the player input by the interpreter is that the words the player is allowed to use can only contain alphanumeric characters, underscores and dash. -This must be kept in mind when naming verbs that use the default syntax (an explicit `Syntax` statement can always specify other player words to trigger the verb). - == Player Words You use `Syntax` statements to define the structure of available player commands. @@ -214,7 +212,7 @@ This makes it possible to use natural words as nouns and create "`{nbsp}l`'{nbsp // @NOTE: Instead of "adventure DESCRIPTION (source)" we could use: // "adventure GRAMMAR (source)"? or "DEFINITION"? -// In any case, in this particulare sentence using DESCRIPTION and DESCRIBED +// In any case, in this particular sentence using DESCRIPTION and DESCRIBED // so close to each other doesn't sound good. But I like GRAMMAR because // the term is used in BNF contexts, so it might be adopted in the Manual // (not just here, but elsewhere too). @@ -253,7 +251,11 @@ So, the execution of various parts of the adventure source can also be said to h * *A rule* -- rules are executed after each actor (including the hero) and after each event, with the focus set to the complete game world. - +// @NOTE: "Moving Actors" is an ambiguous title -- does it mean "actors that are moving" +// or "how to move around actors?". Possibly "Actors Movement" would be better. +// BEWARE that before changing the title we need to search through all sources for +// possible XRefs that also need to be changed accordingly (since we're still using +// the actual title as the XRef)! == Moving Actors @@ -282,7 +284,13 @@ The command history is saved automatically, and as many states as memory permits The player command to restore a previous game state is handled directly by the interpreter. It must consist of the single word `undo`. - +// Q: * Is therefore the UNDO command hard coded into the interpreter? +// if so, it would be the only hard-coded command in ALAN, something +// worth mentioning. (the UNDO, RESTART and QUIT commands when a game ends +// don't count, for they apply only to a special out-of-game context) +// * Is it possible to translate UNDO to other locales? +// * Would a custom UNDO VERB override the UNDO command? +// * Is it possible to execute/invoke UNDO from ALAN source code? == Scripting and Commenting @@ -297,11 +305,8 @@ It must consist of the single word `undo`. // this section with the wider world of Interactive Fiction, games distribution // common practices, etc. -// @TODO: File extensions of transcripts and solution files? Arun seems to use -// ".log" as default extension. Might be worth mentioning that file extensions -// are not important here, and that usually the convention is to use ".sol" -// for solution files, and the various extensions used for transcripts (by -// other terps as well!). +// @TODO: ALAN now adopts the new official '.a3s' and '.a3t' extensions, so we +// should mention them here! Most versions of the Alan interpreter, Arun, supports both the creation of a transcript for the game in progress, as well as playing back a saved transcript as input passed to the interpreter.