LarryG on 30/8/2017 at 00:17
Quote Posted by R Soul
threshold is the name of the parameter and integer is the type of value
If the type is boolean that means 1 for true and 0 for false (omitting a parameter is usually the equivalent of false).
If the type is string that's just text surrounded by double quotes.
Right. But the documentation makes it look like you should specify it as threshold(6) instead of threshold=6. And Boolean is normally interpreted as TRUE or FALSE, and interpreted behind the scenes by the compiler as 1 or 0. You don't expect the programmer to type 0 or 1 as that would be a BAD PROGRAMMING PRACTICE, making a Boolean variable look like an integer variable. TRUE, true, True, FALSE, False, false are all usually interpreted as legitimate Boolean values. The hidden requirement to specify TRUE as 1 and FALSE as 0 is an example of bad software documentation.
I'm going to rant a bit on this to explain my frustration with the documentation. Please note that my rant is not personal and is not directed at any person, especially not Telliamed, the author of the scripts. It is a rant on how difficult the scripts are for me to understand due to the documentation.
Let's start with the very first script:
Quote:
ScriptController
Send a ScriptControl message to other objects. The first message data argument is the control string, as usual. The second argument can name the object to send the ScriptControl to. If the object isn't given in the message argument, then it is relayed to all ControlDevice linked objects.
How to Generate the Message
There are two means of generating the ScriptControl message:
* Use a Conversation (or AIWatchObj link data, AlertResponse etc)
* Action: Script Message
* Argument 1: ScriptControl
* Argument 2: Some string. Suitable strings depend on the script used by the target object.
* Argument 3: The name of the target object (if omitted, a ControlDevice link from the AI to the target object can be used.
*
* The ScriptController script should then be added to the AI.
*
* Put the script on a regular trap:
* Use the design note to specify on=value, where a suitable value depends on the target object.
* Link the trap with ControlDevice to the target object.
* The trap can be activated with a button, lever, or any other standard trigger.
Inherits GenericControl
Links ControlDevice
The layout alone with three primary bullets for what is described as two methods is confusing. It is especially confusing to someone who is new to DromEd. But let's assume that the reader is familiar with the use of pseudo-scripts in DromEd. And can figure out that the idea is to have a pseudo-script associated with an object which is going to feed data to the script
Scriptcontroller via the pseudo-script operator
Script message (which sends messages to the current actor/AI or object hosting the pseudo-script, depending on whether this is a conversation or WatchObj link data, or other means of executing a pseudo-script). The first argument for Script message should be the name of the message to be sent. In this case the name appears to be
scriptcontrol. Is capitalization important? There is no documentation which says anything on the subject one way or another, so to be safe,
ScriptControl should be used. Then argument 2. "Some string. Suitable strings depend on the script used by the target object." Huh?? What strings are suitable for
THIS script? It doesn't say. Maybe it doesn't matter. Wait, oh, is this the message to be sent to the target object?
Moving on to the next argument, the name of the target object. But if all we are doing is sending a message to a target object via a pseudo-script, doesn't the
Scipt message operator do that already by putting the message in the 1st argument and the target in the third? (Yes, I just verified that works.) So why not just skip using this script altogether?
Moving on.
OR we could use this script by putting information in the Design note as
on=value. Really? how does this work? What is a reasonable value? I think what is meant here is a string specified in double quotes as on="message_to_send_to_the_target_object", but maybe not. And how is the target object specified? By a CD link to it from the object hosting the script, otherwise known as a trap. But what is it trapping? The implication, but not explicitly stated, by "The trap can be activated with a button, lever, or any other standard trigger" is that some other object is CD linked to the script host and will send TurnOn / TurnOff messages to it. And since the only script parameter is
on=value the assumption, not stated explicitly, is that this script only responds to TurnOn messages.
How did I get there? Well, the way this documentation works is that you must follow the hyperlinks to fully understand things. The script documentation inherits information from blocks of meta information not included in the documentation for any given script except by hyperlink reference. To wit: "Inherits GenericControl". This means you need to click on the link and learn about GenericControl:
Quote:
GenericControl
A script which can take a string argument.
The script will respond to TurnOn and TurnOff messages similarly to GenericTrap. The effect is specified in the design note parameters on and off. If either parameter is omitted, then that message will be ignored.
ScriptControl
A ScriptControl message activates the script using the first argument of the message.
Wha?
OK. I think this is saying, in the context of the script ScriptController, that ScriptController takes a string message. So you cannot use
on=3.1415 as that would be giving the script a floating point value. You could use
on="3.1415" I suppose. But why not just say that ScriptController's design note should be
on=string_value up in its documentation instead of the misleading
on=value?
Or is this saying that the script will respond to a string message? The phrase a "script which can take a string argument" could be talking about the trigger for activating the script or the parameter that the script looks at once activated. This is not clear.
Next this GenericControl meta information block tells you that the script responds to TurnOn and TurnOff messages. But ScriptController doesn't do that. it only responds to TurnOn. Or does it respond to both TurnOn and TurnOff as GenericControl indicates, just executing to send the
on message to the target for both TurnOn and TurnOff. Maybe that's what it means. Literally that's what the documentation is saying when it says that the "script will respond to TurnOn and TurnOff messages similarly to GenericTrap." Wait. Here is another hyperlink to another meta information block. Maybe that will clear this up:
Quote:
GenericTrap
A switch-like script which responds to TurnOn and TurnOff messages.
Trap Control Flags
Before activating the trap, the message can be altered by the Trap Control Flags property. Except for the Once flag, which will set the Engine Features→Locked property after the trap is activated.
Locks
A trap that is locked, either with the Engine Features→Locked property or with a Lock link will not respond to any messages.
Timing
After being turned on, the trap will automatically turn off if the Script→Timing property is set. The script waits for the given time in milliseconds before turning off. An automatic off will occur even if the trap was locked after the initial on.
ScriptControl
You can send a ScriptControl message to a trap instead of TurnOn or TurnOff. The first message argument tells whether to activate or deactivate the trap. As a number, the trap will turn off when it is zero, or turn on for any other number. The argument can also be one of the words on, off, turnon, turnoff, true, false, yes, no. Upper and lower-case letters are treated the same.
Well! That clears up nothing about whether or not ScriptController will respond to a TurnOff. I guess an experiment is needed. Moving on. Do things that inherit from GenricTrap also respond to Trap Control Flags, Locks, and Timing? This answer is maybe. The reference was "similar to" not "exactly as", so it is up in the air whether they do or not. Maybe they do so, but differently somehow. That would be similar but not exactly the same.
What about the use of 0 or -12.5 to indicate TurnOff and TurnOn, respectively? does that apply to ScriptController? Finally, we get informed that for the key-words on, off, turnon, turnoff, true, false, yes, no that "pper and lower-case letters are treated the same." So could the
on parameter for ScriptController be specified in the design note as
ON=value? Or does upper / lower case thing only apply to values and not parameter names? This is not clear.
I'm exhausted. And all this script seems to be doing is sending a message to another object when it gets a TurnOn. Does the documentation ever really just say that? Not clearly. It uses the term "a ScriptControl message" without any explanation of how this differs from any other type of message. I begin to suspect that it doesn't. This is a case where the documentation says too much and obfuscates rather than instructs by doing so. Why couldn't this just be described as a RelayTrap script which will convert TurnOn messages that it receives into any other message you want to send to another object via CD link? If it is doing that, it sure goes around the barn in telling you what it does.
And this is just one script, a simple one.
End of rant.
tnhScripts are great scripts whose value is diminished by the documentation. I welcome and applaud Yandros in taking on document de-obfuscation for this important DromEder resource. I fear nothing short of a total rewrite is called for.
