Customizing the HUD

Building your own Ship
Setting the NC parameters in a Sailboat
Setting the NC parameters in a Motorboat
Adding Sails to your Ship.
Making your own Mesh Sails

Using the main navigation page of the HUD.
Setting up your sailboat.
Instructions on how to control your boat.
Hints on how to sail a boat.

How the HUD and your boat communicate

The HUD communicates over a fixed channel to the boat, but uses a keyword to figure out which boat to connect with. In your boat somewhere there must be a "Magic HUD COM" script. This script communicates with up to 8 HUDs at once. I ship this script in a prim that looks like a whip antenna but you can move it into any other prim in the boat. Make sure there is only one copy of this script in your boat. The HUD and the COM script also use the ID of the owner to find boats only owned by you (unless you over-ride this with the settings). To find boats to connect to, the HUD broadcasts a message that can be heard by any boat withing 20 meters. Only boats that have a matching keyword respond. If the HUD finds several boats with the same keyword all owned by you, it will connect to the closest one. So if the HUD connects to the wrong boat, try getting closer to the boat you want and re-syncing. You can re-sync by detaching and re-attaching the HUD or by pressing the sync button on the settings page of the HUD.


A HUD and a boat are keyed to each other using the description of the HUD root prim and the description of the prim that has the "Magic HUD COM" script in it. In the "Build Your Own Sailing Ship" kit, I set these to "Sailing Ship" so this is the default keyword. To change the keyword, you simply edit the descrition of the HUD and the COM scripts prim. As usual with a HUD you should make a copy of the HUD first, wear that copy, and change the description in the new one. Change the name at the same time to help you remember which HUD is which. The keyword can be any word or short phrase. Note that spelling and punctuation MUST match. After changing both keywords, you can immediately re-sync the HUD to the boat to make sure they have both been changed.

Editing the HUD

The Sailing Ship HUD is very flexible and you (the boat builder) are allowed to edit it. You can move the buttons around, delete the ones you don't need, change the texture maps on the buttons. The HUD comes to you with lots of example buttons for raising and lowering all the types of sails, setting the throttle on the motor. It has an example of how to set up a page of cannon, borrowed from the Golden Hind demo boat. You can remove the buttons you doin't need from this, make copies of the buttons and change them for your uses. All the buttons are low-poly mesh child prims designed especially to be buttons For example the drop-down buttons have up to 8 different faces. You can change the texture map on each of these faces. If you bought my Advanced Sailing Navigation HUD, it came as an example HUD with a big NAV Compass in the middle of the main page. You will find other simpler compasess and instruments to try out.

The script in the HUD has a library of different kinds of buttons that it knows how to handle. You can add a new button, use one of the built in button types, and the HUD, the button and the COM script work together to send a message to your script in your boat. For example, you could add color change buttons to the the HUD without needing to add any new code to the HUD. You just need to add code to your boat to listen for the messages and change the color.

The way you do this is by linking new buttons to the HUD and putting documentation, type codes, and message strings into the name and description of your new button. The type then determines how the HUD script uses the message(s) that are stored in the button prim description. Most buttons on the HUD can be set up by making a copy of another button then changing the name and description. The name of the button prim has two parts, a unique name and a type, separated by a slash (/). The unique name is used for quick help (if you click and hold for a second, that name is displayed). It is also used for sending commands to the button from your script (for exampe to hide a button that is not allowed). Besides not having a slash or a vertical bar, the only other restriction is that prim names are limited to 64 characters. The unique name is used to identify the button and the type is one of the following 2 letter codes (always upper case, so far):

DD Drop Down button. Displays up to 8 faces when clicked the first time. On a second click the face touched becomes the only visible one and the corresponding sub-string from the descriptor is sent to all the prims in the build that the HUD is connected to. The format of the descriptor is a list of sub-strings separated by slashes (/). The number of sub-strings determines how many button faces are displayed, but the button prim should match this number. (There is no way to find out how many face a mesh prim has).
SB Single Button. This button has only one face, you put a texture map on it, a unique name in the prim name followed by “/SB”. Put a string in the description. When the button is pressed, the prim name a equal sign (=) and the descriptor is sent to all the prims in the build the HUD is connected to.
CB Color Button. Prim name is unique name followed by “/CB”. When clicked this button sends the color and texture UUID of the prim to the connected build, separated by an equal sign (=).
DC Dynamic Color. Prim name is a unique name followed by /DC. You load the first face of the button with a name overlay, and put up to 7 colors and texture maps on the underlying faces. When one is selected, it sends the button name, color and texture UUID on the selected face to the connected build separated by equal signs.
SI Single Instrument. Prim name is a unique name followed by “/SI”. Descriptor is a number an equal sign and a string. You load the button face with an icon or words. When clicked this button sends an “instrument message” to all the prims in the HUD and the connected build. Instrument messages are documented in the TestMast script. You can set up one of these buttons to furl a sail, set the throttle to a fixed speed, change the wind to a fixed direction, etc. Symbolic names for the instrument number and some value constants are understood.
DI Dropdown Instrument. This is similar to a DD button, except the descriptor has pairs of instrument=value sub-strings also separated by slashes. When one of the drop-downs is selected the corresponding pair of instrument values is sent. Example: One DI button can be used to select sails to be furled, reefed or raised full.
MB Mode Button. This button has multiple faces but does not drop down. Instead when clicked it sends the sub-string from the descriptor that corresponds to the currently visible face. The script on the build can ask the COM script to send a message to the HUD to change which face is visible (what mode it is in). Sub strings in the descriptor are separated by slashes.
HH HUD HTML Help button. When you click on this button, it copies the URL out of the description to llLoadURL and opens your browser to that page.
HC HUD Command button. When clicked, it executes the string in the description. Commands you can put in the description are:
page=n – Switch to page n of the HUD, n is 0 1 2 3 4 5.
set=button=value – Set the named drop down button to the named value
sync – Re-sync with the nearest boat.
exit – Detach from the avatar using the hud
hide=button – Hide and disable the named button
connect=n – Don't connect (n=0) or do (n=1) to boats that ask owners for OK
DH Dropdown HUD button. The selected dropdown is used to select the corresponding sub-string from the descriptor and execute it locally. Sub-strings in the descriptor are separated by a slash (/) character.
DB Dropdown Boat button. The selected dropdown is used to select a sub-string from the descriptor to send as a command to the boat COM script. Sub_strings are separated by the slash (/) character.
BS Button Slider. Click on the slider to send a short name and a number. Does not work while dragging, release and click again. Ex: Used for setting cannon powder charge (setting velocity of cannonballs). Format is:
Name: long name/BS
Desc: short_name=min_value=max_value
Sends your script a link message with num=MBFROMHUD and a string:

Button type XX

You can add new buttons that are scripted to do something that is not one of the standard button type above. For example, there are compass, spedometer and tachometer buttons that listen for and send instrument messages. The HUD does not do anything when someone clicks on these, they are assumed to be scriped to do their own work.

Sending commands to the HUD

From another script in your build, you can ask the COM script to send a list of commands with the following call:
Where if id is NULL_KEY the list is sent to all the connected HUDs.
If id is the UUID of an avatar, only that avatars HUD gets the list.
String is a bunch of commands separated by newlines. Make sure you do not exceed the maximum length of 1024 characters allowed by llRegionSayTo, counting the header of 6 characters.

Instrument Messages

You don't need to do anything special to send instrument messages to the HUD, if you send any linked message with one of the instrument messages, the COM script will relay it for you to all the HUDs which will update buttons and send the message on to instruments linked to each HUD.

However, there is a way to send instrument message only to the HUDs, to initialize them after they sync. To do this you execute a line like this:
If id is NULL_KEY the list is sent to all the connected HUDs.
If id is the UUID of an avatar, only that avatars HUD gets the list.
String is a bunch of commands separated by newlines with the format:
The INSTNUM is one of the instrument commands converted to a number. Each button in the HUD that has the INSTNUM/value pair in its description has the corresponding face made visible. The HUD also repeats the message to any linked instruments with a call like:
Make sure you do not exceed the maximum length of 1024 characters allowed by llRegionSayTo, counting the header of 6 characters.

How the Hud Communicates

To limit the number of llListen channels open in a build, there is a COM script that lives in one of the prims in the build and is the only script in the build that has this channel open. It communicates back and forth to multiple HUDs, (currently up to 8 at once). When the HUD sends a message to the build, the COM script converts it into a linked message and sends it to all the other scripts in the build. This way multiple scripts can get messages from several HUDs with only one llListen channel open. For example, a single message that means “raise the square sails” can come from a HUD, and all 14 of the sails in a tall ship will react. The sails are one example of a class of intelligent scripted objects that I call “instruments” (because it includes speedometers, tachometers and other instruments) that have their own protocol for sending linked messages to each other. The HUD and COM scripts listen for these messages and pass them on to each other. This allows instruments to be mounted on the HUD and they will work as if they were mounted on the build. For example, a throttle control on the build sends messages that make a tachometer needle rotate on the HUD. Just link the throttle to the build, the meter to the HUD and when the HUD connects to the COM everything works together.

The HUD protocol

You probably should not read any farther. This part of the document is here to remind me how I implimented the base code of the HUD. You should never send the HUD protocol messages yourself from other scripts. There are linked messages (described above) that ask the COM script to communicate messages for you to all the connected HUDs using secure llRegionSayTo calls. The purpose of the HUD protocol is to implement communications between a HUD and a build (initially boats). I want this communication to be secure and to put the least amount of load on the server. One goal was to use only one llListen channel in the HUD and in the build, and preferably a channel that is already open for other uses. I chose to add HUD commands to the Magic Bullet protocol because my boats already have that channel open for hearing damage messages, and many of my guns already had special purpose HUDs that worked on that channel. So HUDs ended up using HUNTCHAN, or channel number -5013456. All the HUDs and all the builds that use the HUDs can all communicate over one channel because most messages are sent with llRegionSayTo, and because the messages are strings that start with specific commands.

Messages in the HUD protocol

MBsync-- Sent by a HUD that wants to connect to a COM script in a build. This is sent with llWhisper to every build within a 10 meter radius. All following messages are sent with llRegionSayTo so only the connected HUD or COM script will see them.
--MBack Every COM script within 10 meters replies with this if it can connect. It only replies if the HUD is owned by the same person as the build, and if the description string in the HUD and in the COM prim match.
--MBwait If the COM script is within range, has a matching descriptor, but is owned by someone else, it responds with this. Then it pops up a dialog and asks the owner of the build to give permission to connect. If the answer is yes, then it sends the MBack.
MBack-- The HUD waits for one second to see how many COMs reply, then it picks the one that is closest and replies with MBack to confirm the connection. In the case of a MBwait, it waits for the 'yes' MBack before sending this MBack.
MBping-- Every 30 seconds, the HUD sends this message to the COM to check and see if it is still there. The COM currently does not have a timer running to check if the HUD has not sent this recently, but what can a build do if you remove your HUD?
--MBping The COM has one second to reply with the same message. If a second goes by with no reply, the HUD will start over with MBsync to try and connect again.
MBhud-- When buttons of several types are clicked on the HUD, it sends a message like this. The format is Mbhud\nbutton_name=value=description where button_name comes from the button prim name. The value is different for different types of buttons and can just be a string from the button prim descriptor, a sub-string, a color, texture UUID, etc. The description is the description from the HUD, used by cannon to determine which sub-group of cannon the HUD controls. The COM script converts this message into a linked message and sends it to all other scripts in the build. The format of these messages is:
--MBhud When this message is sent from the COM to the HUD it is followed by a list of commands to the HUD. The format of this is MBhud followed by a newline, a command, a newline, etc. Commands that are understood so far are:
sync –- The HUD starts the search to connect to a COM again
set=button_name=face –- The named button has its named face made visible
hide=button_name –- The named button is hidden and disabled
exit –- All the HUDs will detach from the avatars that are wearing them
connect=n – Don't connect (n=0) or do (n=1) to boats that ask owners for OK
control=n – Tell the HUD what to set the “boat will connect ...” button to.
MBcom-- The HUD wants to send a command to the COM script. The format of this is: MBcom\ncommand=value where command is one of the commands listed below and value is any parameter it needs. The commands currently understood are:
connect=n Refuse to connect to HUDs owned by others (n=0), ask your owner if this is OK first (n=1) or connect to any HUD withoug asking (n=2)
MBinst-- When the HUD detects an instrument sending an “instrument message” it converts it into a message sent to the COM, which converts it back into a linked message and sends it to all the scripts in the build. Also, there are button types that generate instrument messages directly. The format of this message is:
--MBinst When the COM script detects an instrument message in your build, it converts it into a message sent to the HUDs, which converts it back into a linked message and sends it to all the scripts in the HUD build. If there is a drop-down instrument button with that number value combination in its description, the appropriate face of the button will become visible. This message allows lines sent back separated by newlines. Each line is just an instrument message number, an =, and the value for that command. Each line us converted into a call like: