Fixing the Wearing Mechanics

[tajmone]

I noticed that the current libraries (EN/ES) adopt a similar approach to clothing items as the StdLib used to, i.e. via the worn entity as a separate Container for the Hero's worn items.

We've already seen the potential problems with this approach, as discussed in AnssiR66/AlanStdLib#57, and the new StdLib now uses a different approach where basically worn is just an attribute, and every VERB that moves around objects has to take care of setting them as NOT worn to ensure that there are no objects marked as worn while not being IN a character and/or being effectively worn.

The implementation details of the new approach I've enforced are described in detail in the CLOTHING_NEW.md document.

The core definition if the new system id described in the following section (from the above mentioned document):

Clothing and Wearability

The worn status of any wearable item is controlled by the worn boolean attribute only (available on thing class).

The criteria to distinguish between worn and not-worn items is simple:

• Any clothing IS worn DIRECLY IN an actor is a worn item.
• Any clothing INDIRECLY IN an actor can not be a worn item.
• Any clothing DIRECLY IN an actor might be a worn item or not, depending on the value of its worn attribute.

Therefore, in the new system is sufficient to ensure that any verb (or event or script) that might dislocate clothing items outside an actor also sets the dislocated item as NOT worn — if the item is not of a wearable type it doesn't matter, for non clothing items should be set to NOT worn anyhow.

It's important to notice here that, although the library only offers werables of clothing type, the new system introduces a general concept of 'wearability', which extends also to other types of wearables which authors might implement.

The library redefines many verbs on the clothing class to ensure that clothing is handled as expected by the vanilla library, which also includes additional CHECKs to prevent most verbs from dislocating worn items.

I believe that the current libraries in this repo suffer from the same limitations and potential problems as the previous StdLib did, and that we should get rid of the worn entity.

New System Pros

The proposed solution turned out to work very well, and was thoroughly tested. The new system is much simpler, since worn items are still IN the Hero actor. Furthermore, the same criteria is now used for handling items worn by NPCs (e.g. when listing carried and worn items). As and added bonus, wearable items are not restricted to clothing only, but can also be applied to any object or class (e.g. wearable devices, etc.).

I never quite understood why the worn entity system was implemented in the first place, it seems to me overtly complicated and error prone, but then I might ignore the constraints of the ALAN language during those years. I guess that it just carried on being inherited (and expanded upon) by further incarnations of the libraries, until new ALAN features come into being, ultimately leading to conflicts between them and the old system.

New System Cons

The downside is that authors need to ensure that any custom VERB that they add to their games, which might result in transferring objects from actors, needs to ensure that the moved object is always marked as NOT worn (in case it was). This is something that new authors might overlook, and which could lead to adventures breaking-up badly due to bad objects states.

Final Thoughts

As a final consideration, the libraries in this project don't have a dedicated clothing class, so any object marked as wearable can be worn. This is probably good for us, since we don't need to make any distinction between clothes and other wearables (glasses, helmets, etc.).

The StdLib offers a rather sophisticated system to handle clothing layers, and how each clothing item maps to various body regions and wearing-layers, which prevents players to wear/disrobe clothes in the wrong order (e.g. wearing boxers while wearing trousers) or wearing two items belonging to the same body region and layer (e.g. two shirts). I believe that this level of sophistication is well beyond the needs of a Starter Library, and might actually stand in the way of its openness to customization; but we should nonetheless give some thought on how end users might implement such constraints — e.g. how hard would it be to prevent players to wear two clothing items at once?

I guess that subclassing would be the way to go. Since the wearing mechanism would be class-agnostic, any items that shouldn't be worn together could be rendered as a custom class, and CHECKs added to ensure the actor is not wearing (i.e. containing as IS worn) items from the same class.

What are your thoughts about the potential problems of the current wearing mechanism, and whether we should fix it?

Consistently Enforce Changes across Libraries

If we decide to embrace this change, it should be applied to all existing libraries (EN, ES) as well as those in the making (IT, SV) so that it becomes a commonly shared feature in v1.0.0 — then any new ports would just follow the example.

Creating a Test-Suite before Proceeding

Of course, we'd also should set up a test-suite to cover the current wearing system (and its bugs) and any changes to it, in order to ensure that the transition goes smooth. We could probably reuse some of the tests found the StdLib to do this, with some minor code tweak:

https://github.com/AnssiR66/AlanStdLib/tree/dev-2.2.0/tests/clothing

[tajmone]

On Using Sets for Worn Items

In alan-if/alan#35#issuecomment-886834334 you mentioned that using Sets could be a viable alternative to having a worn entity to store items worn by the Hero:

As I have mentioned before I think the worn-problem could be solved with a set attribute on the hero. This should also be easy to extend if you want to have multiple "containers" like various pockets, backpacks and what not, and manage them separately. This should at least be tried in the context of #18.

I vaguely remember considering this approach when I was testing various alternatives for the StdLib, although I don't recall the implementation details I've actually tried and why Sets were discarded (it might just be that I didn't investigate them well).

Considering that any actor (not only the Hero) could be wearing items (clothes, glasses, helmets, ecc.), we need to figure out a method that is simple to handle for authors, especially if they add their own verbs to an adventure.

The reason I went for a simple worn boolean attribute, directly on the item, is because it's simple to handle when moving around objects — i.e. every VERB that moves an item should blindly make it NOT worn because it could potentially have been worn, and after the relocation it shouldn't be (or terrible things would happen in the adventure).

IMO, Sets complicate things because Set attributes are implemented on the Actors, not the object, so author creating new VERBs that relocate object would have to first check if the item is worn, and (if it is) find out who's wearing it in order to remove it from the wearer's Set of worn items — which in ALAN means having to iterate through every actor at the current location.

I remember that during my experiments I was really pleased when I came up with those three rules about what a worn items is, isn't or could be — because they are semantic rules mimicking the way we'd think about this problem, and they focus on the item rather than the wearer.

Item don't accidentally end up being worn in an adventure, they are either:

1. Worn by an Actor since the game starts.
2. Become worn/unworn as a result of a player command.
3. Become worn/unworn as a result of a SCRIPT/EVENT.

So, ultimately authors have full control over VERBs (and their commands) and SCRIPTs that make change a wearable item's status from worn/unworn.

The only dangers lie in VERBs and SCRIPTs which might be moving around worn items without setting them to NOT worn (the StdLib used EVENTs to control that no worn items where floating around outside actors). But then, as I said, if every VERB/SCRIPT does relocates an object always set it to NOT worn (and is not a 'wear' action) there are no risks in this respect — because it's guaranteed to no relocated item could possibly be worn, unless it was done by an action implying wearing it.

Of course, whether a game should allow relocating worn items ultimately depends on the author's choices and rules — Should the player be allow to simply TAKE an item worn by an NPC? or THROW it, ecc.? Should such commands work for items worn by the Hero? or should the player first REMOVE an item before being able to DROP it, THROW it, GIVE it, ecc.? — these are all personal choices, so there's no standard or golden rule for these; and I believe that a Starter Library should not enforce opinionated choices in this respect.

Going back to using Sets instead ... I'd love to read about your idea on how to use them, because I'm quite sure I haven't explored their potential deep enough when searching for alternative "wearing" implementations.

[tajmone]

Very interesting proposals, both of them.

Sets Approach

The advantage of this is that you can have multiple sets for wearing on your head, body, carrying around in your pockets etc. depending on your needs.

That's really a good added bonus, but I think it can also work with the worn attribute since one doesn't exclude the other; but this might be an advanced feature which is beyond a basic library.

In essence the "attribute approach" is similar to this, using an attribute instead of the set to indicate "wornness". But since the attribute is on the item, you don' t have to hunt around in other objects to remove it from their set. So one point for the attribute approach.

Yes, it's safer to keep it the attribute on the object being moved around, dropped, etc. My experience with the worn status is that it takes one single overlooked custom verb to break a whole game — once a dropped (or moved around item) is kept in the "being worn" status, the whole game state becomes unpredictable, with objects not being usable any more, and potentially the game solution being compromised.

Nested Containers

How about using nested containers? Now that we know how, and that, they work ;-)

This is a really ingenious approach, yet still quite simple in nature, and hence easy to understand and keep in mind when creating new custom verbs.

I'll need some time actually testing this locally, starting with your example code (thanks for it). Not having tested it, I'm just expressing some general concerns based on past experiences:

• 1. Will there be any problems with ALL verbs?

Even if the worn_container is invisible in terms of being listed automatically or when using 'inventory', it's still plausible that it will become the target of verbs allowing ALL (take all, drop all, etc.).

• 2. How easy is it going to be to check whether a clothing item is currently being worn by an actor?

e.g. the 'take' verb might need to fail if the target object is a worn item. Checking the worn attribute is easy, because it's implemented directly on the object, but checking whether the item in inside the worn_container of any other actor requires quite some iteration through all actors in the current room (and, potentially everywhere, in case the verb had the ! indicator, for whatever reason).

But, apart from these concerns, it looks a very good solution, and one that sounds very ALAN idiomatic too.

[tajmone]

A Further Proposal: wearer of <item>

After having given some more thought to the issue I came to following conclusions:

1. Having an attribute on the object is definitely necessary to simplify checking its worn/unworn status.

2. Instead of a boolean attribute we should use a reference attribute pointing to its wearer or a dummy person actor if unworn. E.g.

   The nobody is a person at nowhere -- i.e. in the limbo location.
   End the.
   
   Every clothing Isa object
     Has wearer nobody.
     Verb wear
       ...
     End Verb.
   End Every clothing.
   

   This way, we can easily check whether an item is worn by using

    If wearer of this <> nobody
   

   and if we need to quickly identify its wearer (e.g. for a verb message):

    Say the wearer of this. "won't let you take it!"
   

So, we still have single attribute on wearable items, but now it allows to check both its worn status and who's wearing it, at the mere cost of an extra dummy actor (which is never reachable in the game).

This solution doesn't even clash with your proposal of a worn container inside each actor, they can work hand by hand with just an extra statement to also set the attribute. But now to identify who's wearing an item we don't need to iterate through every actor in the location to find where the item is.

As for the worn container, we need to understand if this can easily be added to every person actor in the game, i.e. automatically via INITIALIZE, or some other way by manipulating the person class (right now I'm too tired to think about it, I need some sleep).

As for the initial proposal of using sets for indicating on which part of the body an item is worn, although not eligible for inclusion in the "Foundation Library", that could become a suggestion for expanding the library, since that wouldn't clash with either of the above, it would be just an extra set attribute being added to them.

[thoni56]

In order to make the "set-approach" work well, the Alan language is missing a construct.

Since an instance can be in many sets at the same time, and from the instance itself it is impossible to know which, we need a mechanism to remove an instance from all sets:

Verb wear
    Does
        Exclude this From All.
        Include this In worn Of hero.

This addition seems reasonable from other perspectives also, and it would make it easy to ensure that the item is only in one set, the set of the wearer.

I'll add this to the long list of future features ;-)

[tajmone]

Seems a powerful addition to the language, and doesn't do any backward compatibility harm either! Excellent.

[tajmone]

Start Implementing via Worn Attribute

@thoni56, after some thoughts I sill think that currently the best solution is to implement wearing mechanics via a wearer attribute (as of my latest proposal, using a reference pointing to the wearer, rather than a boolean), and then just ensure that any verb that moves around objects also sets them as being unworn (i.e. Set wearer of this to nobody).

As for listing actors inventories that distinguish between carries and worn items, I still think that the solution adopted in StdLib is the simplest, i.e. to defined custom MESSAGEs and Container code for listing items, plus an ad hoc inventory verb.

I'm still a bit skeptic about using a nested container for worn items, partly because of the complexity of adding such a container in NPCs, but mostly because it could lead to unexpected problems with verbs acting on ALL, which could either reveal to the player the presence of this mysterious container, and in the worst case might lead to the container being dropped from the actor (e.g. in verbs that empty all contents on the floor, etc.). I tend to prefer safer (albeit more verbose) solutions, like iterating over objects twice to provide a list of carried vs worn items (it worked out fine in the StdLib, and once the code is there end users don't have to replicate it elsewhere, except in very rare cases of custom verbs).

In any case, if it's OK with you I'd like to start working on this in a dev branch for the English library, so I can start adding a test-suite; and then if we're not happy with it we can always try another approach.

The point is that the current wearing mechanics are a huge blocker in this project — can't really create a test suite until this is fixed, nor proceed with the Italian library either. This is a quite a central issue, affecting many verbs and all tests, for its effects are not limited to wearable items but to a variety of other verbs and all Actors.

Of course, when the new Sets feature are out we can always improve the clothing mechanics, but from what I read so far most of your proposal will work well with the attribute approach I'm proposing, since they would not be mutually exclusive.

[thoni56]

Remember that I'm not a "real" Alan author, just the implementor ;-) So I don't have much experience to throw into this discussion, just ideas.

Having a wearer reference attribute sounds like a reasonable solution. The Foundation library should definitely provide a mechanism for wearing things, so, as you say before going forward with fleshing out the library, this has to be settled. And it's as good an approach as any other, probably with less unforseen problems. The other proposals probably has to be tested out in a larger experiment before adopting in a library.

So I totally ok with you proceeding with this approach. We can probably try it out later, and as we go along, we learn what problems it may bring.

Just to make this clear:

• each wearable will have a reference attribute wearer
• when the item is worn, that attribute it set to the wearer (obviamente!)
  • is it still in the inventory of the wearer?
• when the item is carried, as opposed to being worn, the wearer reference attribute is set to the special instance nobody
  • in this case it must be in the inventory
• if it is not carried or worn, it is not in any inventory, and it has wearer set to nobody

If the answer to my question is yes in the middle there, then the action of removing a worn object is probably also just Set wearer of this to nobody.

The "ad hoc" inventory verb (and description of actors, if they can wear things too) need only to distinguish worn object by them being wearable and has the wearer set to something not nobody. Something along the lines of (ignoring formatting):

For Each item in actor Do
    Say the item.
    If item Isa wearable And wearer Of Item Is actor Then
        "(worn)"
    End If.
End For.      

[tajmone]

So I totally ok with you proceeding with this approach.

Thanks! I'm really hoping to have a usable version of the Foundation Italian library so that I could create an adventure by Christmas time.

And it's as good an approach as any other, probably with less unforseen problems. The other proposals probably has to be tested out in a larger experiment before adopting in a library.

Indeed, and at least this approach has been tested thoroughly in the StdLib dev branch, albeit with just a boolean attribute (but the change to a ref attribute doesn't change much implementation-wise, besides the added benefits).

Just to make this clear:

• each wearable will have a reference attribute wearer

Yes. Either named wearer of worn_by, whichever looks nicer in all possible contexts (most likely the former though).

• when the item is worn, that attribute it set to the wearer (obviamente!)
  • is it still in the inventory of the wearer?

The inventory being an abstract construct, the answer is: it's always IN the actor which is wearing it (not being so would be an error which should never happen). As far as the inventory goes, it will be listed separately, in the list of worn items, when this is possible, or being followed by "(being worn)" in context where creating separate lists shouldn't be possible. IIRC, we managed to ensure separate lists with both the 'inventory' verb and Listing actor containers, without problems.

• when the item is carried, as opposed to being worn, the wearer reference attribute is set to the special instance nobody
  • in this case it must be in the inventory

Exactly, a wearable item can only be in the worn status if its wearer attribute points to an actor other than the nobody dummy actor (located at nowhere), if it points to nobody it's not worn, which means that if it's IN an actor it has to be just a carried item. Every object will by default have wearer pointing to nobody, and since the wear verb can only apply to wearables (i.e. having the wearable attribute set to True) only wearable can ever become worn by an actor.

That is, unless at some point we decide to create a wearable class instead of it being an attribute, which right now I don't see the need to. Also, since authors might implement custom classes that might also be wearable (e.g. a VR helmet, implemented as a device class that can be turned on and off, have batteries, etc.) I think it's best to keep it an attribute, since ALAN doesn't support polymorphism.

• if it is not carried or worn, it is not in any inventory, and it has wearer set to nobody

Yes, which is the reason why every library verb that moves objects around should always Set wearer of this to nobody on the object being dislocated, without further checks (even if it was worn before, it won't be after being moved elsewhere, unless we're dealing with the 'wear' verb of course).

Authors need to remember this when creating custom verbs, otherwise they could end up with object on the floor which the game considers as being still worn. We could easily create an additional "debug module" to test adventures with, like I did in the StdLib, where the modules simply adds a recurring event that tests every object in the current location to ensure it's not being set as worn without being IN an actor, and report an error if this is the case — this module is only used for testing adventures, so it's OK if it hits performance with huge checks every turn.

The "ad hoc" inventory verb (and description of actors, if they can wear things too) need only to distinguish worn object by them being wearable and has the wearer set to something not nobody.

You can see the actual code used in StdLib for inventory here:

https://github.com/AnssiR66/AlanStdLib/blob/dev-2.2.0/StdLib/lib_verbs.i#L3566

VERB i
  CHECK my_game CAN i
    ELSE SAY my_game:restricted_response.

  DOES
    -- ------------------
    -- List carried items
    -- ------------------
    SET my_game:temp_cnt TO COUNT IsA object, IS NOT worn, DIRECTLY IN hero.
    IF  my_game:temp_cnt = 0
      THEN "You are empty-handed."
      ELSE
        "You are carrying"
        FOR EACH carried_item IsA object, IS NOT worn, DIRECTLY IN hero
          DO
            SAY AN carried_item.
            DECREASE my_game:temp_cnt.
            DEPENDING ON my_game:temp_cnt
              = 1 THEN "and"
              = 0 THEN "."
              ELSE ","
            END DEPEND.
        END FOR.
    END IF.
    -- ------------------------
    -- List worn clothing items
    -- ------------------------
    -- Don't say anything if the Hero is not wearing anything.
    SET my_game:temp_cnt TO COUNT IsA clothing, DIRECTLY IN hero, IS worn.
    IF  my_game:temp_cnt <> 0
      THEN
        SAY my_game:hero_worn_header. --> "You are wearing"
        FOR EACH worn_item IsA clothing, DIRECTLY IN hero, IS worn
          DO
            SAY AN worn_item.
            DECREASE my_game:temp_cnt.
            DEPENDING ON my_game:temp_cnt
              = 1 THEN "and"
              = 0 THEN "."
              ELSE ","
            END DEPEND.
        END FOR.
    END IF.
END VERB i.

And here's the code for handling LISTing actors:

https://github.com/AnssiR66/AlanStdLib/blob/dev-2.2.0/StdLib/lib_messages_runtime.i#L63

  CONTAINS_COMMA: "$01"
    IF parameter1 IsA thing THEN
      IF parameter1 IS worn
        THEN "(being worn)"
      END IF.
    END IF.
    "$$,"
  CONTAINS_AND: "$01"
    IF parameter1 IsA thing THEN
      IF parameter1 IS worn
        THEN "(being worn)"
      END IF.
    END IF.  "and"
  CONTAINS_END: "$01"
    IF parameter1 IsA thing THEN
      IF parameter1 IS worn
        THEN "(being worn)"
      END IF.
    END IF. "."

the above will produce a single list of all items, specifying "(being worn)" for each worn item. But this only applies to LIST an_actor, whereas for the 'examine' verb we've implemented an ad hoc version of the VERB which will show two separate lists, just like inventory:

https://github.com/AnssiR66/AlanStdLib/blob/dev-2.2.0/StdLib/lib_actors.i#L222

ADD TO EVERY ACTOR
  ...
  VERB examine
    DOES AFTER
      IF THIS <> hero
        THEN
          -- ------------------
          -- List carried items
          -- ------------------
          -- Don't say anything if the actor is not carrying anything.
          SET my_game:temp_cnt TO COUNT IsA object, IS NOT worn, DIRECTLY IN THIS.
          IF  my_game:temp_cnt <> 0
            THEN "$+1"
              IF THIS IS NOT plural
                THEN "is"
                ELSE "are"
              END IF. "carrying"
              FOR EACH carried_item IsA object, IS NOT worn, DIRECTLY IN THIS
                DO
                  SAY AN carried_item.
                  DECREASE my_game:temp_cnt.
                  DEPENDING ON my_game:temp_cnt
                    = 1 THEN "and"
                    = 0 THEN "."
                    ELSE ","
                  END DEPEND.
              END FOR.
          END IF.
          -- ------------------------
          -- List worn clothing items
          -- ------------------------
          -- Don't say anything if the actor is not wearing anything.
          SET my_game:temp_cnt TO COUNT IsA clothing, DIRECTLY IN THIS, IS worn.
          IF  my_game:temp_cnt <> 0
            THEN "$+1"
              IF THIS IS NOT plural
                THEN "is"
                ELSE "are"
              END IF. "wearing"
              FOR EACH worn_item IsA clothing, DIRECTLY IN THIS, IS worn
                DO
                  SAY AN worn_item.
                  DECREASE my_game:temp_cnt.
                  DEPENDING ON my_game:temp_cnt
                    = 1 THEN "and"
                    = 0 THEN "."
                    ELSE ","
                  END DEPEND.
              END FOR.
          END IF.
      END IF.
  END VERB examine.
END ADD TO ACTOR.

The above is what allows to handle NPCs wearables in a seamless way, just like for the Hero (obviously, "inventory" only applies to the Hero, the equivalent verb for NPCs is examining them).

[tajmone]

Lib v0.2.0 Draft Available

OK @thoni56, I've implemented the new wear mechanics, which you can preview in the dev_alan-en branch already.

I still need to fix all the verbs that move around objects, to ensure they are set to unworn status — but we'll also need to discuss whether an item worn by an NPCs should be allow to be moved around by the Hero or not, e.g. via verbs like 'throw', 'put in', etc., or if these attempts should result in an error message saying that the wearer would object to this. Deciding the default course of action is always a difficult task.

Anyhow, in the end I had to implement two attributes, not just one:

• wearer — a reference attribute pointing to the wearing actor or nobody (a dummy actor at nowhere).
• worn — a boolean attribute. Also needed because ALAN aggregators only support boolean attributes in filters.

So, we now have to always manipulate two attributes. But I think it's still worth it, for wearer allows us to mention the wearing actor in messages, directly from the context of the item being handled; and the worn attribute is needed for aggregators, which also make it easier to carry out checks via is not worn instead of having to use wearer of this = nobody.

You'll find all the details in the CHANGELOG document.

Now I need to add a testsuite and start checking that everything works as expected, so it's going to take some time before these changes are squashed into main.

Please, let me know what you think of the new system.

PS: I think that the wearer attribute is so practical that I'll propose to @AnssiR66 that we also add it to the StdLib, along with the (already implemented) boolean worn.

[tajmone]

I think the natural choice would be to go for an error message. I'm sure there are cases where the wearer is an animal or something that would not object, but for the most part any sentient being probably would, at least until you ask ;-)

The problem with that would arguably be the need for the author to override those verbs via a DOES ONLY in order bypass the conditional checks, unless we also add a is compliant attribute to allow similar actions — the StdLib uses compliant for blocking/allowing any actions involving taking possessions from actors, and by default you can't interfere with carried/worn items by person actors unless they are compliant. But you can always 'ask for' their possessions, and they'll oblige by default, as you suggested. I think that @AnssiR66's rationale behind this was to make it easy to handle animals or other non-human actors in adventures, as you suggested.

I'm not sure, but doesn't aggregate filters support boolean expressions, like wearer = nobody?

You can test this by changing the invent.i file at line 52 from:

        For each worn_item directly in hero, is worn

to:

        For each worn_item directly in hero, is worn

You get the following compiler error:

../Foundation/invent.i

   52.2         For each worn_item directly in hero, has wearer hero
=====>                                                   1      2

  *1*   440 E : Aggregate filters can currently only accept boolean attributes.

The Aggregates section of the ALAN Manual doesn't mention this limitation, nor §3.22. Filters. The former only states:

The Sum, Min and Max aggregates return the sum, minimum and maximum value respectively, of an attribute of all instances in the filtered set.

The latter doesn't mention anything about which attributes are allowed. So I guess we should add an Issue on ALAN Docs to update these sections with more details about the type of attributes supported.

The shorter expression is a benefit of the worn attribute, but I am always concerned with duplication. And it is the worst case of duplication, semantic duplication, having one attribute holding a value that can be deduced from another.

I agree, and I was initially hoping to do away with just the wearer reference, but then I bumped into the compiler limit. I could have stuck to just using the boolean attribute, but I thought the benefit of being able to mention the wearer without having to iterate through all actors in the current location was precious enough to justify the redundancy (the StdLib is doing fine with just the boolean worn, so the wearer reference is not strictly necessary).

The good news is that while you usually only need to use of them for read operations, whenever there's a status change you'll always be updating the value of both of them at once (only exception would be a verb that explicitly makes an item worn by one actor become worn by another, but again always updating worn never hurts and is a good precaution).

If I had a chance to, I would drop worn and use wearer = nobody instead, which is slightly more verbose but better than having redundant attributes. So, if ALAN was ever to support non-boolean filters we can always fix this.

Somehow, I have the impression that this Issue of filters requiring boolean attributes already came up once in some Issue or Discussion (or maybe the mailing list), but I can't recall any specific details. I do have a vague feeling that you explained why it was difficult to extend filters to include other attributes types. I guess we should just open a Discussion on this on ALAN repository, and add the feature to our wishlist.

Do we even have a centralized wishlist, where all proposed eligible features are listed, with links to their Issue or Discussion? I think we ought to create one at ALAN repo, and also create a syntax updates label to track them.

[thoni56]

I think the natural choice would be to go for an error message. I'm sure there are cases where the wearer is an animal or something that would not object, but for the most part any sentient being probably would, at least until you ask ;-)

The problem with that would arguably be the need for the author to override those verbs via a DOES ONLY in order bypass the conditional checks, unless we also add a is compliant attribute to allow similar actions — the StdLib uses compliant for blocking/allowing any actions involving taking possessions from actors, and by default you can't interfere with carried/worn items by person actors unless they are compliant. But you can always 'ask for' their possessions, and they'll oblige by default, as you suggested. I think that @AnssiR66's rationale behind this was to make it easy to handle animals or other non-human actors in adventures, as you suggested.

Right. I think this is one of those items that forces us to talk about the limits of the Foundation library. We can't obviously bring in every feature from StdLib because that would make the Foundation lib to big and blur the lines between them. But we don't want it to be to simplistic either.

Reflecting on where the Foundation library started from I think we should lean towards the lean side ;-) And the dividing line will probably something along the lines of "which typical game features does it support, and when do you have to hack it?"

If a majority of future game makers will be content with an error message and this forces the few that goes beyond to hack the library or write their own, I think that is a reasonable decision. Doing that will make it clear that we do not intend to support every possible feature. But the problem instead is a judgment call on what is the "majority and their needs".

But, again, I would be content with having a clear "the library supports this, if you need something else, you have to go beyond the library policy" rather than try to make it possible to override and change everything and still use the Foundation library. That's probably why we have decided to have both libraries.

I'm not sure, but doesn't aggregate filters support boolean expressions, like wearer = nobody?

You can test this by changing the invent.i file at line 52 from:

        For each worn_item directly in hero, is worn

to:

        For each worn_item directly in hero, is worn

You get the following compiler error:

../Foundation/invent.i

   52.2         For each worn_item directly in hero, has wearer hero
=====>                                                   1      2

  *1*   440 E : Aggregate filters can currently only accept boolean attributes.

The Aggregates section of the ALAN Manual doesn't mention this limitation, nor §3.22. Filters. The former only states:

The Sum, Min and Max aggregates return the sum, minimum and maximum value respectively, of an attribute of all instances in the filtered set.

The latter doesn't mention anything about which attributes are allowed. So I guess we should add an Issue on ALAN Docs to update these sections with more details about the type of attributes supported.

Probably.

Somehow, I have the impression that this Issue of filters requiring boolean attributes already came up once in some Issue or Discussion (or maybe the mailing list), but I can't recall any specific details. I do have a vague feeling that you explained why it was difficult to extend filters to include other attributes types. I guess we should just open a Discussion on this on ALAN repository, and add the feature to our wishlist.

You have good memory. A few quick tests confirmed that adding a general expression as a filter is impossible because of the ambiguities it creates in the grammar. It is impossible for the parser to understand if a '= ' would be part of the filter or is the comparison part of the whole expression. So without extensive semantic analysis merged into the parsing pass to guide the parsing this will not be possible (in any parser generator).

I remember now that I was quite frustrated with this since I felt the aggregates and filters was a very handy addition. To make that possible I need to change the syntax for the filters, and I'm not sure even that would help. Fortunately you can do the same with explicit loop unrolling and If statements.

Do we even have a centralized wishlist, where all proposed eligible features are listed, with links to their Issue or Discussion? I think we ought to create one at ALAN repo, and also create a syntax updates label to track them.

I have always used https://www.pivotaltracker.com/n/projects/92303 as that list. But I have probably not been very good at linking appropriate discussions (if they were on the mailing list they are gone now anyway).

[thoni56]

Do we even have a centralized wishlist, where all proposed eligible features are listed, with links to their Issue or Discussion? I think we ought to create one at ALAN repo, and also create a syntax updates label to track them.

I have always used https://www.pivotaltracker.com/n/projects/92303 as that list. But I have probably not been very good at linking appropriate discussions (if they were on the mailing list they are gone now anyway).

But perhaps we should add a new discussion area for ideas, whishes and so on. As that would (might?) make it easier to find the discussions, and keep them on topic.

I'll do that.

[thoni56]

Do we even have a centralized wishlist, where all proposed eligible features are listed, with links to their Issue or Discussion? I think we ought to create one at ALAN repo, and also create a syntax updates label to track them.

I have always used https://www.pivotaltracker.com/n/projects/92303 as that list. But I have probably not been very good at linking appropriate discussions (if they were on the mailing list they are gone now anyway).

But perhaps we should add a new discussion area for ideas, whishes and so on. As that would (might?) make it easier to find the discussions, and keep them on topic.

I'll do that.

Actually, there already was one.

[tajmone]

Actually, there already was one.

I should link to that section from the ALAN Wiki, lest we forget (yet again) about it. 😉 [ DONE! ]

[tajmone]

English Test Suite

@thoni56, I've now added a basic test suite to English dev branch, which currently covers only wearables.

The reason it took me so long was partly due to my need to get off the PC for a couple of days, but also because I took a whole day digging into Ruby and Rake to come up with a good solution to handle transcripts generation (I've found an excellent solution, only need to implement it now).

As you can see from the generated test transcripts, there are still many verbs which execute an implicit taking which should probably be prevented when dealing with worn items:

• wearables_hero.a3t
• wearables_npcs.a3t

So, should I block these actions on all actors, or just on person actors?
By blocking it only on person, it would allow these actions on animals, robots, and other type of non-moral agents, whereas if we block it on all actors it will be harder to implement this behaviour for end users.

Since it's all about VERB CHECKs, it's easier for author to add those checks on their custom classes, whereas removing them implies altering the library sources. I think that enforcing them only on person is a fair compromise.

Then, of course, we'll have to look into the error messages of these verbs, which need to be precise.

I've found some rather strange library bugs during this work, e.g. with the undress verb which was implemented on object and wouldn't work on actors, even though it's a verb without parameters, so I just made it global. I think this is a reminder that we should go over the whole library code with a thin comb, because much of its code will probably need to be updated due to new syntax constructs having been added to the language, and some odd bugs and stray logic being left there due to lack of a proper test suite for the library.

As a final note: Rake is making life so much easier! Just having to type rake anywhere within the project, and being able to see which files needed updating, without having to go through the entire re-build. It's fabulous!

[tajmone]

On Handling Worn Items

@thoni56, I've been doing some tests regard restricting handling worn items.
But before going ahead I need your confirmation on a couple of points.

My idea was to prevent implicit taking an item only if it's worn by a person, but allow it if it's worn by another type of actor — the idea being that this should be allowed on non-sentient actors.

The problem here is that it's not possible to handle this via VERB CHECKs, because there's no negative form of IsA, i.e. this won't work:

Check wearer of obj not IsA person
  else ...

(tried other variations too, but there seems no way of negating the IsA expression).

Which means that the restriction has to be done in the verb body, like:

    Does
      If wearer of obj IsA person then
        say the wearer of this. "is wearing" say the obj.
      else
        If obj not in hero then
          Locate obj in hero.

Of course, this approach is much more limiting, for authors won't be able to handle custom classes by simply adding an extra CHECK, but will have to either edit the original library verbs or re-implement them on each class, if they want to also restrict the action on custom actor classes.

Currently, the only library verb doing an implicit take action is the wear verb, so this change won't be affecting many verbs in any case. But of course, we haven't yet discussed whether the library should add implicit taking to verbs at all, and if yes, which verbs should attempt an implicit taking?

Obviously, some actions are made simpler by having their VERB do an implicit taking, but the downside is that it's not easy to predict whether the taking attempt will fail (abruptly) or not, since there's no way of trying the action.

So, what are you suggestions in regarding to the above point?

[thoni56]

I think this is good thinking. It is difficult to draw the boundaries for a foundation library, but I agree that having a basic wearing mechanism but suggest ways to solve some common "extensions" to documentation and examples is a good way to do that.

It also makes it more clear cut what the Foundation library offers and what StdLib offers. And, again, I think clearly drawing that line is important to not muddle the Alan space with overlapping objects. Maybe that is one way to think about it, if StdLib has it, and it is tempting to add to the Foundation library, what would be the most basic flavour of that feature?

Where would we put this "readme", or amend, to make this distinction clearer? I'm thinking a semi-newbie might want to understand when to select the Foundation library and when the StdLib. And also help ourselves remembering this fuzzy line... Formulating that would be tricky of course, but we have until 1.0.0 to revise the wording ;-)

[thoni56]

But I'll also have look at not Isa...

[tajmone]

Good to see that we're on the same wavelength here.

As I start working on any library feature I'm immediately reminded of how that feature is implemented in the StdLib, so the first temptation is to just re-implement it, but then I realize that the feature being available in the StdLib can also be a sign of its being an advance feature, and I start to imagine how it would be to actually work with a library that exposes this feature, and then with another that doesn't.

Luckily, I'm fresh on the StdLib codebase (which I've learned inside out during the last years) and how the various features play out in the test suite, edge cases and all. This allows me to remember both the pros and cons of having details covered in any feature.

Where would we put this "readme", or amend, to make this distinction clearer?

I'm currently updating the English docs folder, simply making a Foundation book with all the stuff in there (lookup tables, changelog, etc.). It's probably easier for us at this stage to have a single document, and probably also end users might prefer a single HTML doc with all the info, after all thanks the TOC, book parts and appendices, it's fairly easy to find what one is looking for.

Of course, when the package release time arrives, we could also provide some smaller docs with basic info, and hopefully these could be created using the same ADoc sources (using preprocessor directives to adapt them), so we don't have to maintain multiple documents.

Again, this is something that will become clearer as we go along, so right now the single-mega doc might be the best solution. I'm also thinking of getting rid of the original NOTES.md and INDEX.md docs, after I've ported their info to the new AsciiDoc documentation.

I'm thinking a semi-newbie might want to understand when to select the Foundation library and when the StdLib. And also help ourselves remembering this fuzzy line... Formulating that would be tricky of course, but we have until 1.0.0 to revise the wording ;-)

It probably has more to do with on whether the user is an ALAN newbie or has already some experience creating ALAN adventures. The StdLib is much bigger and feature rich, which also means that it takes quite some time to learn how to use it, and it's harder to introduce new verbs and classes or extend the library without having first studied its code. Like any library, there'll be basic and advanced users, i.e. those who studied the library sources to gain insights and those who just read its manual.

But it could also boil down to tailoring needs, e.g. an author that writes adventures of a specific genre might end up wanting to build a dedicated library, probably picking from both the Foundation and the StdLib, according to needs.

In any case, I can easily add an admonition block in the Foundation book, pointing out how any given features is covered in the StdLib — e.g. mentioning that the StdLib offers a full-fledged clothing class that maps clothes to body parts and wearing-layers; or outdoor locations vs rooms, handling both artificial lighting and day/night cycles, etc. This should be a good enough prompt for Foundation users, which will make them aware of the gap between the two libraries, and might lead them to investigate how those more advanced features are implemented in the StdLib (I could also link to the feature source module, since the StdLib is quite big).

[tajmone]

Not IsA

But I'll also have look at not Isa...

Yes, that's something that would be quite useful to have. Also, the Manual doesn't really mention anything about negating class-level expressions, so we should add an Issue to Alan-Docs too for this — I've scavenged the whole Manual seeking for an answer to this, but couldn't find anything. If it's not supported, then we should make it clear.

[thoni56]

Not IsA

But I'll also have look at not Isa...

Yes, that's something that would be quite useful to have. Also, the Manual doesn't really mention anything about negating class-level expressions, so we should add an Issue to Alan-Docs too for this — I've scavenged the whole Manual seeking for an answer to this, but couldn't find anything. If it's not supported, then we should make it clear.

Yes. And we actually already discovered this in alan-if/alan#14 (comment). It is on the top of the list, after the release.

But I think I need to refactor the grammar radically to make this possible. Simply adding the optional_not creates the same kind of grammar ambiguities that we saw for filters.

But this requires focus and treading carefully as to not mess anything up. So I'll do beta8 first.

[tajmone]

Ready to Polish and Merge?

@thoni56, now that the whole issue of how to prevent handling worn items has been resolved by leaving it to end authors, and having removed implicit taking from the library, I would then probably say that the wearing mechanics are now fixed and probably read to be merged into a new library update (v0.2.0).

But before that, I'd like to make sure we're not forgetting anything (in any case I'll need some time to break the branch changes into multiple commits, because it contains too many changes — new Rake feature, the test suite, the new docs, etc.).

All Library changes have been annotated in the CHANGELOG of the dev branch, and all the tests in the new test suite seem to indicate that feature is working correctly.

I could possibly add some extra testing, e.g. by adding an event that runs at every turn to see if it can find an object which is lying around and is set as worn, and then test all the verbs that move around objects — but frankly, I'm quite sure that I've already tweaked all these verbs to set the moved-around object always to an unworn status.

In any case, even if there's a bug we'll probably catch it later on, as the test suite grows, and surely before v1.0.0 is out.

• Are there any other aspects of the wearing mechanics which we might have not considered?

E.g., we've focused mainly on clothing when thinking of wearables, but are there some other types of wearables which we didn't consider and which might deserve some extra features or considerations?

[thoni56]

Haven't really thought through that question but as you mention "other types of wearables" I imediately think of wear bracelet or wear the one ring. Is that problematic?

[tajmone]

I imediately think of wear bracelet or wear the one ring. Is that problematic?

They shouldn't be. But I was also thinking of exploring more lateral applications, not just non-clothing apparel for human (like glasses, backpacks, wrist watches, etc.) but also accounting for non-human actors, like animals.

E.g. it should be OK to say that a dog is "wearing a collar", but in some other cases the item might be linguistically described via some term other than "worn" even though the library will treat it still as a worn item — e.g. a horse saddle, I'm not even sure which verb will be used to describe that it's mounted on the horse, but it probably won't be "wearing" nor "carrying"; whereas it's probably OK to say that a donkey is "carrying a stack of wood".

Also, so far we've considered "wearing" only from the perspective of the Hero wearing or removing items, and as a passive status on other actors, but in some adventures the player might actually need to act on NPCs clothing too, especially with animal actors (mounting/removing the horse saddle, putting on/removing a dog's muzzle, etc.). Also, a game featuring small kids might require the Hero to help them wear/disrobe a coat, etc.

I just wanted to do some final brainstorming to imagine possible extensions and advanced applications of "wearing/disrobing" in adventures, across a variety of different actors types and contexts, to ensure that our wear mechanics and attributes would play out well in all situations.

Using a similar brainstorming approach for the StdLib illumination mechanics allowed us to realize that artificial lights (torches, candles, etc.) would clash with natural light and darkness in some contexts, which ultimately allowed us to introduce an extra optional attribute for handling day-night cycles without breaking artificial lighting — something which could have been hard to implement for end users, and was worth adding to the core library.

So, the idea was to also try to imagine far-fetched uses here, for any Foundation Lib feature, just to be sure we're prepared for all use cases.

[tajmone]

Anyhow, I've polished the dev branch and merged it into main. If we can think of any edge case uses of wearables, we'll add them to the test suite and see how they play out. And any good cases we'll use them as examples on how to extend/customize the library to meet adventures needs.