Document Overriding Verbs on 'my_game'

[tajmone]

• [ ] Document in StdLib Manual that verbs defined on my_game override the default library-defined verbs thanks to the INITIALIZE code on DEFINITION_BLOCK, which nests every game location into the my_game location before the game starts.
  • [ ] Add cross references to the above explanation in all places where overriding verbs on my_game is suggested.

---

@AnssiR66, in various places the Manual mentions that it's possible to globally override the default behavior of a library-defined verb by re-defining it on the my_game instance.

Although I haven't tried this out, I'm quite skeptical that this might actually work.

As I've written in an editors' warning admonition in StdLib Manual §18.3. Replacing Syntaxes:

We need to check if verbs defined on my_game really work as described here. Do they? And why should they?

The my_game is just an instance of DEFINITION_BLOCK, which is a location class, which the Hero never enters into; so, why should these verbs come into effect during play if they're never in scope?

Maybe these texts are referencing older version of the library, which no longer apply to the its later versions. We need to test if this actually works, and if it does we need to explain why, otherwise we'll need to amend or purge similar examples and instructions from this Manual.

I was wondering if this way of redefining verbs is indeed something left over from older versions of the library. In any case, we need to check if this actually work — and if it does, we should explain to the reader why and how it works, and externalize all examples to real adventure sources.

[AnssiR66]

Ok, we can of course check it. When I have been testing this before, though, it has been working just the way the manual explains, and I haven't noticed any problems. Did you run into some issues somewhere? Because, just like a verb can be defined to override the default behavior in a specific location (The cellar is a location. Verb jump Does Only "The ceiling is too low for jumping here." End Verb. End The cellar.), similarly, if we define a verb to work only in my_game, which is a specific location, the verb works in all of its nested locations, too, - because the verbs are in scope in these locations. Where does it say they are not? It is, I understand, the same logic that for example walls, floor and ceiling are in scope in all indoor locations (the Room class) , etc, so that you can 'x walls' in all Rooms, etc.

[tajmone]

Ahhh! You're right. I've tested it and it works as expected.

The reason why this happens is because the DEFINITION_BLOCK contains the following code in its INITIALIZE block:

        FOR EACH l ISA LOCATION
          DO
              IF l <> my_game AND l <> nowhere
              THEN LOCATE l AT my_game.
            END IF.
        END FOR.

So, every location in a game that uses the StdLib is in fact nested inside the my_game location. Since this isn't mentioned in the documentation we need to mention it — at least, I don't remember coming across this, so if it's there it needs more visibility.

I wasn't aware (i.e. I forgot entirely) about that initialization part.

We definitely need to document this in the early parts of the Manual, where it gives an overview of the StdLib — also, the fact that every location will end up as being nested in my_game can be exploited by end authors to quickly create some globally present objects (e.g. the sea, etc.).

Maybe it's worth adding at least a cross reference to this explanation in the various parts that mention using my_game to override verbs, etc., for it's an important point to understand remember for end authors.