Template:Tmbox/doc

The Global Mod Link System (GMLS) is a free, full-permission script system provided by the NTBI Group. Anyone can implement GMLS into their modifiable vehicle, and anyone can build mods that automatically position themselves when linked to a GMLS-compatible vehicle.

Overview

GMLS is a set of full-permissions scripts. It is intended for use in modifiable vehicles to simplify the installation of prebuilt modifications. For example, the NTBI Factory Lightbar Package uses GMLS to automatically position lightbars when linked to compatible vehicles.

Aftermarket modification manufacturers can set up GMLS by linking a copy of the modification to the desired vehicle and using the Calibration Tool to set up the Alignment Tool. Then, when an end-user links the modification to a compatible vehicle, the modification will reposition itself (and, if necessary, rescale itself) automatically. GMLS can also unlink certain prims from the vehicle for factory prim replacements.

GMLS comes with three scripts:

• NTBI GMLS Alignment Tool - Inserted into aftermarket modifications and edited by the modification manufacturer to program alignment positions and other options.
• NTBI GMLS Calibration Tool - Used to calibrate alignment positions; outputs alignment data to be placed in the Alignment Tool.
• NTBI GMLS Vehicle Sample Script - Inserted into vehicles and edited by the vehicle manufacturer to define vehicle information for use by modifications.

The NTBI Group does not maintain a list of compatible vehicles or modifications. GMLS-compatible products should clearly label themselves as such. The NTBI Group does not provide any warranty for third-party GMLS implementations.

Click here for the GMLS developer kit.

End-User Instructions

Refer to your vehicle's owner's guide for instructions on how to install GMLS-compatible equipment.

If the owner's guide does not provide instructions, the following is a general checklist for installing GMLS-compatible modifications:

1. Ensure that the vehicle is turned off, including any lighting or other components that may change any attributes while installing the modification.
2. Take a copy of your vehicle as-is. Modifications may cause damage or unlink prims accidentally. Save a copy now in case this happens!
3. Rez the modification near your vehicle.
4. Right click the modification and select "Edit".
5. With the Edit window open, hold your SHIFT key and left click the vehicle. This should select both objects at once. Make sure you select the vehicle last.
6. Press your CTRL + L keys, or click the "Link" button in the Edit window.
7. If prompted, confirm that you want to link the two objects together.
8. When linked, the modification should automatically position itself to the recommended position and resize if necessary.
9. If prompted, grant link permissions. This may unlink some prims. Make sure to delete them after.
10. If desired, you may usually move the equipment once linked.

If a modification does not use GMLS, is not compatible with your vehicle's GMLS system, or returns an error when linking using the above procedure, follow steps 1 through 6, then manually reposition the modification as needed.

Aftermarket Modification Manufacturer Instructions

Get the Alignment Tool and Calibration Tool from the GMLS developer kit.

Before continuing, make sure your mod is finished. Do not continue until you are sure you do not need to make any changes to your object.

1. Make a two copies of your object. One will be used for calibration. The other will be distributed to your end-users.
2. Place the "NTBI GMLS Alignment Tool" script in the distribution object (the one you will keep).
3. Place the "NTBI GMLS Calibration Tool" script in the calibration object (the one you will link, then delete).

For each vehicle you want your object to be compatible with:

1. Make a new copy of the calibration object. It should have the "NTBI GMLS Calibration Tool" script already in it.
2. Rez the vehicle. Make sure it is the original size!
3. Position the calibration object on the vehicle, exactly where you want it to be once installed by the end-user.
4. Link the calibration object to the vehicle.
5. Copy the script snippet line sent to local chat.
6. Open the "NTBI GMLS Alignment Tool" script in the distribution object.
7. Paste the script snippet line between the two marked lines at the top of the script. NOTE: The first part of each line is the GMLS ID of the vehicle you have calibrated to. If you see a line with the same GMLS ID, you have already calibrated to that vehicle, and only the first instance of that vehicle will be used.
8. Save the "NTBI GMLS Alignment Tool" script.

Once finished, delete any calibration objects and vehicles.

If you want the root prim of the object to retain its physics type when linked to the vehicle, change root_no_physics to FALSE. (By default, the root prim of this object will be set to physics type "none" and the physics types of child prims will remain the same.)

If you want to have the GMLS script automatically unlink prims, list their names in the remove_prims list. If you do this, you can also change remove_move_dist to change the distance unlinked prims will move up, and you can change remove_recolor to FALSE if you do not want unlinked prims to be recolored bright red for visibility.

If you do not want the object to be set to temporary when unlinking prims in the remove_prims list so that they automatically delete themselves, change make_temp to FALSE.

When finished, make sure you test your modification on each compatible vehicle to make sure it works correctly.

API

The Alignment Tool and vehicle script send the following link messages that can be used to trigger additional scripts in your modification:

• GMLS_REQUEST
  • Sent by Alignment Tool once linked. Vehicle responds with GMLS_ID if compatible. You can also send this manually once the GMLS script is finished if you need any information from GMLS_ID.
• GMLS_ID
  • Key: [gmls_id]|[root scale]|[additional information]
  • Sent by vehicle in response to GMLS_REQUEST. Note that [root scale] is not the size of the root prim of the vehicle, but rather the ratio of the current size of the root to the original size of the root. For example, [root scale] on a vehicle that was upsized to twice its original size would be <2.0, 2.0, 2.0> regardless of its actual size.
• GMLS_SUCCESS
  • Sent by Alignment Tool if the GMLS operation completed successfully and it is now safe to perform any configuration changes or whatever else on the newly linked-to vehicle.
• GMLS_FAIL
  • Sent by Alignment Tool if the GMLS operation failed either because the object the modification was just linked to is not GMLS-compatible or the vehicle has a gmls_id that the modification was not calibrated for.
• GMLS_CANCEL
  • Sent by Alignment Tool if the GMLS operation was cancelled by the user.

Vehicle Manufacturer Instructions

Get the Alignment Tool and Calibration Tool from the GMLS developer kit.

Before continuing, make sure your vehicle's root prim will not be resized before it is distributed. Do not continue until the root prim is finalized.

1. Place the "NTBI GMLS Vehicle Sample Script" script in the vehicle. If you prefer, you can also integrate this script into another script in the vehicle to save memory.
2. Edit the gmls_id string. You can use any string as long as it does not include the pipe ("|") character, but it should be limited to alphanumeric characters, underscores ("_"), and be up to 32 characters. The gmls_id must be unique for every vehicle that has a different layout of potential modification positions. For example, use different IDs for 2DR and 4DR variations of the same vehicle.
3. Edit the gmls_default_root_size vector to be the size of the root prim of the vehicle. On most viewers, you can get this value by opening the Edit window, going to the Object tab, and pushing the "C" button next to Size. WARNING: This is not optional. Failure to set this value will cause GMLS modifications to align improperly.
4. Save the "NTBI GMLS Vehicle Sample Script" script. If kept separate, you can limit the memory used by the script if you prefer.

Perform this procedure for each vehicle variation. Once finished, it is a good idea to test the GMLS settings by creating a simple object and following the Aftermarket Modification Manufacturer Instructions.

Changelog

Rev. 2

• Added make_temp option.
• Changed unlinking parts procedure so that unlinked prims are set to temporary if make_temp is enabled.

Rev. 1

• Added GMLS_SUCCESS, GMLS_FAIL, and GMLS_CANCEL link messages.
• Fixed erroring out and refusing to reposition if linked before permissions have been granted.
• Fixed unlinking parts check running before checking if vehicle is compatible in the first place.
• Fixed crosstalk when multiple GMLS modifications are rezzed at once.
• Improved vehicle detection in slow regions by extending identification time from 2 seconds to 5 seconds.

Rev. 0

• Initial public release.