Giters

alan-if / alan-docs

Alan IF Documentation Project

Home Page:https://git.io/alan-docs

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Fix §2.3: Add Mention of Rules, Before Scripts

tajmone opened this issue · comments

commented

In §2.3. Alan Fundamentals » What’s Happening? (master/dev-man) we read:

The execution of an adventure is primarily driven by the input of player commands. A command is analysed by the interpreter program according to the player command syntax allowed by the author and, if understood, transformed into execution of verbs or movements, which in turn may trigger other parts in the game as described in the Alan source. After a player turn, other, scripted non-player characters or actors, can move, controlled by the computer, again according to the definitions in the source. Scheduled events are then run, and then the player takes another turn.

The above paragraph omits Rules! We should correct it, for clarity sake.

  • In "After a player turn …" mention execution of Rules, which are evalued before Scripts.

The order of what is executed at each turn, and in which order, is described in 5.1. A Turn of Events — the order being:

  1. Verbs
  2. Rules
  3. Scripts
  4. Events

Live Dev-Preview links

These links point to previewthe dev-man branch, and will work even after force-pushing to the PR:

commented

This being an early chapter, I'm not sure how rules can be introduced in the text (since they haven't been explained yet) without generating confusion...

I tried changing the above to:

After a player turn, rules are evaluated and then other, scripted non-player characters or actors, can move, controlled by the computer, again according to the definitions in the source. Scheduled events are then run, and then the player takes another turn.

But it doesn't seem to help the reader at all — it might actually confuse him.
Probably "rules" are too abstract a concept to be introduced at this point, unlike "scripted actors", which are more intuitive to imagine even without knowledge about Scripts in Alan code.

This should be thought about carefully. On the one hand, for completeness sake it would be good to not omit rules here (for they are part of the execution context of every turn), but on the other hand confusing the reader would be too high a price for this.

commented

Perhaps, not using the term rules can help. Such as

After a player has input a command, any special conditions that might have been programmed by the author are evaluated. Then other, scripted ...

commented

Sounds better, and it might also justify mentioning them within parenthesis (possibly with cross-links to their sections) in case the reader is curious about them:

After a player has input a command, any special conditions that might have been programmed by the author are evaluated (rules, events, or scripts, in that order).
Then other, scripted ...

where "(rules, events, or scripts, in that order)" should be replaced by the actual special conditions, in the right execution order, and linking to their introductory sections...

Either that, or we could add a TIP! admonition block with an aside describing these type of special evaluated conditions, their order, etc., with cross references for the curious reader. Maybe this would be even better, so the reader can just skip it, for it's obviously not a fundamental part of the chapter flow, but at the same is offered the possibility to dig into it.

commented

Well. not scripts, because that is what "other actors" are doing. And also events and rules are evaluated between each actor. So the trick here is to give a general feeling of what's happening, with out being too specific.

A TIP might be appropriate. "For further details on... see..."

commented

Then let's go for the TIP! block. Personally, I like to have a chance to dig deeper into topic at my second or third read, so I find asides blocks like these very useful, but at the same time non-distracting when reading the first time.

Can you handle these fixes? I'm not sure I fully understand their context, order, etc. (as my proposal revealed). Or at least paste here the final revised paragraph, and the TIP! contents, then I can fix the ADoc sources.

commented

Ok, so here's my best shot at this time ;-)

The execution of an adventure is primarily driven by the input of
player commands. A command is analysed by the interpreter
according to the command syntax prescriped by the author and, if
understood, it is transformed into execution of verbs or movements.

After the player has had his turn, any special conditions, or rules, that
might have been programmed by the author are evaluated.

Then, other, scripted non-player characters, or actors, will
move. Their movements and actions are controlled by the computer,
again according to the definitions in the source.

Scheduled events are then run, and then the player takes another
turn.

TIP! This is described in more detail in Section 5.1, “A Turn of
Events”.

By dividing the text in paragraphs I think it more clearly indicates the parts that are involved. This description is not strictly true, since rules are evaluated after each step (actor, events) but that is on a to detailed level for this section and might also change in the future. What we are after here is an overall "feeling" of the parts involved on how they fit together.

I was thinking about removing the indication of a clear order between them, just to be flexible and leave the actual details for 5.1. But I found no good way to do that without causing even more confusion.

The TIP text was already in the section as the last sentence. I don't think it requires anything else.

commented

Amended Text Previews

Ok @thoni56, I've patched the text as indicated, and also slightly retouched the text in §5.1. A Turn of Events, from (bold added to mark changes):

Then each of the other actors executes one step in their Scripts [...]
Finally, each Event that is scheduled for this round is fired, and the rules evaluated yet again.

to

Then each of the other actors executes one step in its Script [...]
Finally, each Event that is scheduled for this round is fired, and then rules are evaluated yet again.

I thought that the first correct is grammatically better, and that the second one strengthens the idea that Rules are re-evaluated after each special condition is dealt with (as opposed to along with it).

All changes are currently in branch dev-man_whats-happening and can be previewed at these links:

ALAN Manual Live Preview links

These links point to the dev-man branch, and will work even after force-pushing to the PR:

commented

Seems quite alright, good amendment to 5.1.

And, to be clear, I'd like you to feel you have the permission (and my blessing ;-)) to do that type of small changes whenever you feel. I trust you enough to do good things that we don't necessary need branches for these. If I feel differently I'll just change it again ;-)

I think branches are only warranted for "external" contributions (because we want to review, rephrase or restructure them) and when we (as authors) think we need to try, experiment or discuss something.

I am hearby declaring you my co-author/editor for the manual ;-)

commented

I am hearby declaring you my co-author/editor for the manual ;-)

thanks! I feel flattered by this entrustment ( 😳 )