Advice on documenting multiple scripts wanted

[Gregory McLeod]

I am having trouble trying to document the interaction between three scripts in a HUD.

They are structured so that one script (let's call it Start) prepares itself with various functions and then sends a LINK_THIS message to the two other scripts (Main & UserInterface). These are set up so that they do some intialization but wait on the receipt of the LINK_THIS message from the Start script before proceeding to more complex tasks. If they do not get this first message from Start they all abort and detach the HUD with appropriate messages to the wearer.

Before you ask the necessity of three scripts is because of memory limitations.

These two other scripts when they have completed their initialization send a LINK_THIS message to all the other scripts.

The Start script when it has received both the messages from the Main and UserInterface scripts sends a final LINK_THIS message to the two other scripts which then switch to a Running state.

Because the scripts are event driven I cannot find a satisfactory way to document them.

Can anyone suggest a method, notation or other way of doing this?

 

[revochen Mayne]

Hello Gregory!

 

I always prefer to document object internal script communication at the top of the script, stating the communication channel, command keywords, optional or obligatory parameters, separators and a short description for.

 

BTW as you refering to a HUD. Do you ever had a look at the OpenHUD project? It's open source and provides a lot of useful features like user input detection including swipe gestures, modular structure and many more.

You might want to have a look at the LSL script files at:

http://wiki.openhud.org/index.php?title=Category:Script_Files 

(The "Core Panel" and "Core Lib" scripts might be a good example)

 

Cheers =)

[LepreKhaun]

---

Gregory McLeod wrote:

I am having trouble trying to document the interaction between three scripts in a HUD.

They are structured so that one script (let's call it Start) prepares itself with various functions and then sends a LINK_THIS message to the two other scripts (Main & UserInterface). These are set up so that they do some intialization but wait on the receipt of the LINK_THIS message from the Start script before proceeding to more complex tasks. If they do not get this first message from Start they all abort and detach the HUD with appropriate messages to the wearer.

Before you ask the necessity of three scripts is because of memory limitations.

These two other scripts when they have completed their initialization send a LINK_THIS message to all the other scripts.

The Start script when it has received both the messages from the Main and UserInterface scripts sends a final LINK_THIS message to the two other scripts which then switch to a Running state.

Because the scripts are event driven I cannot find a satisfactory way to document them.

Can anyone suggest a method, notation or other way of doing this?

 

---

 

 

 

What you need is what's referred to as an API reference (http://en.wikipedia.org/wiki/Application_programming_interface. See http://ace.c9.io/#nav=api for a simple example, ). This documents what each program does and how the parts communicate/interact.

 

This is best done in a separate document that is kept with your programs as you develop them. That way you'll have a central location to both refer to and change as needed (and you will make changes as you go along!). It should be as detailed as possible, covering not only the data each module will hold but how it will make it available to the others interacting with it as well a full description of the communication protocols used between them. The more complete and detailed these descriptions are, the easier it will be to both write and debug the application.

 

I use Notepad++ (http://notepad-plus-plus.org/ with Dari's Better Highlighting- http://home.comcast.net/~volfin/LSL.XML) for this, using it's Session capability to group files together as well as the split screen ability to look at two documents at the same time. That way I can open all my programs tabbed on the left and my API reference to the right of my screen.

 

I'm unsure what problems you're experiencing as far as LSL being event-driven, that actually makes it easier to coordinate things. The only thing to be careful with is "extended loops" where, for instance, one program is iterating through a list held by another. This can be dealt with by use of global variables and (possibly) state changes to keep track of what a program is doing at any given time.

 

One of the more difficult things I've found is to work out the communication protocols, which will be dependent on whether all the scripts are within the same prim (necessitating the use of an addressing mode/channel, I usually use the integer part of the messages for that*) as well as what the information being passed (a cvs list may be all that's required or, in more complex data, JSON). I've found that first working that out with the basic structure of who does what in the API reference best. Once I've developed that to my satisfaction will I actually start to code the programs themselves.

 

* When using the integer for "message channels" between multiple scripts, assign your scripts channels in powers of 2's (as in; Channels 1, 2, 4, 8, 16 etc). That way you can use bit-wise operators and comparators to message groupings if desired.

Either way, always be certain a script never, but never, processes its own link messages!

[Gregory McLeod]

Thank you for the reply. Unforunately I cannot see anything from the second link you gave

http://ace.c9.io/#nav=api

all I get is a page headed by ACE and some options none of which respond to clicking. Do you have a complete page link?

I am finding it difficult to visualise the events which happen in three scripts in a HUD. I am intially tryiing to document how the scripts are started as much for my own understanding as for whomever takes over from me.

I am interested in  your solutions to the various problem you outline.

I am using Link messages for communicate between the scripts. Yes I know about the never ending loop danger. I detect all the messages but throw away the ones not intended for the script I am coding at the time.

I have a feeling that this subject is one which might be better addressed to expert in business system documentation methodology. I am NOT implying that you are not an expert.

 

 

 

[revochen Mayne]

Also creating a flow chart may help to visualize the scripts processes on a single view. I'm using uDraw as its free and easy to use. You may get flow charts like this:

[LepreKhaun]

Oh, you must have JavaScript disabled, that page relies on it extensively, sorry. Here's the picture I was meaning to show you:

It's just a way of diagramming the interactions of the parts and how they relate to each other. Boxes represent the elements and you fill them with whatever detail you wish (more is better!) and the arrows between them show the communication flow. The arrows can be labeled as well and detailed with the specifics of the messages being passed, what I'll detail in a bit as messaging protocol.

 

But I feel you may be complicating this more than you need to. Scripts "start" as soon as they are successfully compiled and saved. Then they pretty much don't do anything except wait for one of their event handlers to be triggered. What happens at that point depends on the code you've written for that event within the script.

So, you modularize your script into parts. One part will go into the UserInterface script. This primarily would be a menu system which requires a touch and listen handlers, a timer for closing listens, possibly a state_entry to initialize some global variables and, of course, a link_message event handler to receive messages from the other scripts. And that's pretty much it except for deciding how sophisticated the menu system you need and hacking out the code.

Now, at this point, there's two things you have to keep in mind. First, UserInterface should be just that and nothing more. Everything in it should be devoted to "discussing" things with the user, determining what their wishes are and communicating their needs to the other scripts to act upon. If it's not related to the user interface, it gets off loaded to another script via llMessageLinked. Second, no other script is to interact with the user. That one is easily followed, you just don't have any touch or listen event handlers in them. Trust me on that, if your interaction with the user isn't centrally contained, you'll have a debugging nightmare ahead of you. That strictness of one functionality per script doesn't have to be followed for the other scripts btw but do keep all functionality together, no exceptions. You do not want to be in the position of having to search multiple documents to find where a buggy line is hiding.

And that's pretty much modularity in a nutshell. Just think of each script as a super function, one you call using llMessageLinked and get a return value back via link_message. When making these calls, you have three [ETA] user parameters at your disposal, an integer, a string and a key (which could be a string). How you use these parameters is what's called your message format, which is a part of your messaging protocol, which you have to design from scratch. (Study Chapters 4 and 5 of the e-book at http://jan.newmarch.name/go/ for what's all that about).

Messaging protocols can be crude and basic or as elaborate as required. Besides including the message format, they cover the request and reply sequence, definitions of the client and server, what action to take if a request is unanswered, security issues and a lot more. The main thing though is documenting it! Even a crufty, one-time use, protocol should be thought out, written and then consistently followed.

Looking at each script within your network as a "super function"; keep in mind that variables, our data, are nouns while functions are verbs, in that they do something (and both of these traits are usually reflected in the naming). And since we'd now have "super functions" that may be capable of many possible actions, your message format should include a COMMAND. For instance, if you've implemented a database in a script, the command in any message sent to it might (minimally) include GET, SET, CREATE and DELETE. Another parameter of the message could then hold the DATA. But, since link messages can't pass lists, you'd most likely require a (de)serialization of your data elements to/from a string (such as JSON offers). A message ID may be required to ensure order at the receiving end or to verify which request the reply is answering.

And, since you're considering more than 2 programs working together, you have to decide on your network's logical topology (http://en.wikipedia.org/wiki/Network_topology). In other words, who will be talking to who. IMO, the easiest to implement in SL (besides point-to-point) is a Star configuration within a multiple-prim object, one script per prim. That eliminates channel and script ID checking almost entirely: All that the node scripts require is the location of the hub/dispatcher script, which alone knows of the others and need only look at the link number to know where any message originated. A side benefit of this is that completely frees up all the parameters within the link message.

Anyway, I hope that helped a bit. Basically, you just have one script that interacts with the user and it'll be the only one having the event handlers required for that. All the scripts, of course, would have a link_message event handler having whatever code is appropriate for its purpose. They can all use their timer events as they wish, one or more of them might have a sensor in operation or doing HTTP operations, whatever. Just keep in mind that link messages are queued, a script's event queue can only be accessed once a server frame (45 times a second, excepting state_entry) and there is a 65 event limit. In other words, don't get too crazy with messages.

[Gregory McLeod]

#LepreKhaun

I really must thank you for the extensive reply which has been very helpful.

I am working my way through the contents having sampled the references.

#revochen

Thank you too for your input I have not heard of uDraw. I tend to use Visio when I want to chart things as it provides a method of communicating with others with MS S/W. In this case I thought it would be overkill as it involves a little more effort than I thought would be necessary. LepreKahaun's reply is astounding in it's completeness.

Thanks to both. I am now fully prepared to get to grips with my personal problems (old age).

[LepreKhaun]

I shared a little sumpthin-sumpthin that might help you along with your HUD development, a LinkMessage Monitor - http://community.secondlife.com/t5/LSL-Library/LinkMessage-Monitor/m-p/2417567.

 

With it, you'll be able to see your scripts interacting as needed, which should go a long way to getting them to dance together correctly.