As noted in my previous post, I am confused by the three related properties, known, seen, and familiar.
Why three properties? When is a thing known but not seen, seen but not familiar, or familiar but not known or seen? Are they not all the same thing?
Also, when do they get set? I know the doc says they get set when something is observed (but again, I don’t get any sense of what’s different when I read the Library Manual), or when the game code explicitly calls for it (but, I do get a run time error when I try, the topic of the previous thread).
In the example outlined in the previous thread, where a hotel clerk puts a key on the counter, I set some break points and observed both seen and known to be nil after the clerk put them down…
…but both became true when I do a subsequent look command.
Is that correct behavior?
Isn’t it a valid expectation that the key becomes known and seen the minute the clerk puts it on the counter?
Here’s how I understand it, from reading the “Learning TADS 3 with Adv3Lite” PDF, on the chapter about knowledge (Chapter 7: Knowledge, pg 118)
seen is set automatically by the library when the PC has seen an object (but doesn’t catch those times when you manually move an object into the same location as the PC)
familiar is set when the PC knows about an object/topic. (such as, the PC knows there’s a key to the safe, but hasn’t seen it.) Most useful when you want the PC to be able to ASK x ABOUT KEY or TELL x ABOUT KEY, without the PC having to have seen it.
known is set automatically by the library when an object has seen and/or familiar set to true. So you don’t have to write a test like:
How is this statement “180 degrees out of phase” with the explanation given in Learning TADS 3 wth adv3Lite? The statement quoted from Learning TADS 3 concerns the meaning of the seen, known and familiar properties. The statement you cited from the adv3Lite Library Manual is a brief recommendation about the API game authors should use to test and set those properties in their own code should they wish to do so. The explanation of the known, seen and famililar properties in the same part of the manual (just above the paragraph you cited) states:
This seems to me to be pretty much equivalent to the explanation Gerynar cited from Learning TADS 3 with adv3Lite, not “180 degrees out of phase with it”. Perhaps I can make the paragraph you quoted a little clearer though, and also cross-reference to the section on Player Character and NPC Knowledge.
After I read the definitions of known and seen in the library manual, I tried using them in my code and they were not working. As I showed in my original post, the key was neither seen nor known after the clerk put it on the counter, but then became both seen and known after I issued a Look command.
Based on what I read in the library manual (seen…(b)ecomes true when the object has been seen by the player character) I expected it to be seen at the time the clerk put it into play. Yes, the manual does say there are odd circumstances under which the library may miss the correct setting, but I did not expect the clerk putting the key on the counter to be an odd circumstance. It’s only in the Learning TADS3 discussion that this clarifying statement—in particular when we move an object into the player’s location with moveInto()—is made.
So, yes, a cross reference between the two docs would be most helpful, but some additional clarification for the above-cited, apparently conflicting statements would also be helpful.
But I still don’t see how the statements cited conflict; one may be more specific than the other, but I can’t see that they contradict each other, which is what “conflict” implies to me. Or are you talking about the methods used to set the seen property (which is not so much a conflict as each document giving half the story).
I nevertheless agree that the Library Manual could do with a bit of clarification at this point, and that’s what I’ll work on next.
The statement in the library manual, with an emphatic make sure, says to set the seen property using setSeen().
The Learning TADS3 doc, with an emphatic must remember, says I should not manipulate the seen property driectly but rather use the gSetSeen(obj) macro.
You may argue that I am glossing over nuances in your text, and you may be right, but the key takeaway from the Library Manual text, for me at least, is that the seen condition of an object is tracked by the seen property and the proper way to change it is setSeen(), while the key takeaway from the Learning TADS3 doc text is that I must not change the seen property using setSeen().
Those two takeaways are in apparent conflict. If the conflict is not real, then some explanatory text reconciling them, in each of the two documents, would help in understanding how the property should be properly used.
I have to confess that it never occurred to me that anyone would read it that way. What the library manual is advising against is using code like:
brassKey.seen = true;
As opposed to:
brassKey.setSeen();
Or
gPlayerChar.setHasSeen(brassKey);
Both of which do exactly the same thing, while
gSetSeen(brassKey);
Is simply a macro that expands to:
gPlayerChar.setHasSeen(brassKey);
None of these is what I meant by “setting the value of seen directly”.
But there’s something else you’re missing here: your original quote from the adv3Lite Library manual stated:
But by not quoting what came before (in the ellipsis), you miss part of the point of this text:
Please note that “If you do so…”. In other words the advice that follows is only meant to apply if you have defined seenProp and knownProp to distinguish player character knowledge from that of other actors. It’s not giving general instructions that have to apply to all games, just what needs to be done in the special case of tracking NPC knowledge separately from player-character knowledge. It’s thus not really even talking about quite the same thing as the passage in Learning TADS 3 with adv3Lite.
That said, it’s a highly compressed passage which probably isn’t all that clear, since it gives no explanation of seenProp and knownProp. In the latest version just uploaded to GitHub it now links to a more detailed discussion that spells this out more fully, including the use of the seenProp and knownProp properties to track different actors’ knowledge.
Retrieved it, read it, excellent addition! Thanks. It explains it all fully and clearly. Had I seen this, I would not have posted the original call for help.
Yes. I did in fact note that in my first reading, and it left me even more confused, given the paucity of text concerning correct usage of the seen/known/familiar properties.
Probably because you already know the answer, without having to read the manual
Please consider my state of mind when I first encountered the passage. I was coding, came across a problem concerning seen as it relates to a specific item in a specific game, and I turned to the Library Manual for guidance about how to achieve a specific effect in my code.
In the Library manual, I found a single short paragraph on usage (other than the bullet list of property definitions), and its main point…underscored by must use…appeared to be—set the properties seen and known using setSeen() and setKnown().
So I do. And what happens? I encountered the library bug you have now fixed on setKnown(). At that point, I turn to the forum and am told by Gerynar to RTFM the Learning TADS3 book, which contains text that advises, underscored with an emphatic must, do not set seen directly, use instead these new methods I I have never heard of before reading the Learning TADS3 section on seen.
All moot now, of course, because a) you have enlightened me through this forum thread and b) the new text in the Library Manual, which. as already noted, covers the ground admirably.
