jbFunctions

A library of miscellaneous handy MAXscript functions.



Installation

Simply copy jbFunctions.ms into your Max plugins directory, or another directory that is listed in your plugin.ini file.

This script only contains support functions for other scripts, and does nothing useful in and of itself.

The latest version of these functions can always be downloaded from www.johnburnett.com.



Documentation

Each function in this documentation has a description, and a list of arguments. Code samples are formatted like:

doSomething <arg1> %<arg2> [arg3:default]

Required arguments are surrounded by < >.

Optional named arguments are surrounded by [ ], and list their default value, if omitted.

If a passed argument is directly updated (as in the case with most array functions), then the argument is marked with a preceding "%". This is just for documentation clarity, and should not be included in any function calls.



Using The Functions

If you use one of the included functions in one of your own scripts, you can ensure that users have the proper jbFunctions version installed by wrapping your script in the following if statement:

if (
	local requiredVer = XXX
	local str, failed = FALSE
	if (jbFunctionsCurrentVersion == undefined) then (
		failed = TRUE; str = "This script requires jbFunctions to run properly."
	) else if (requiredVer > jbFunctionsCurrentVersion()) then (
		failed = TRUE; str = "The installed version of jbFunctions is out of date."
	)
	if (failed) then (
		str += "\n\nYou can get the latest version at http://www.johnburnett.com/.\n\nWould you like to connect there now?"
		if (QueryBox str title:"Error") then ( try (ShellLaunch "http://www.johnburnett.com/" "") catch () )
		FALSE
	) else ( TRUE )
) then (
... -- your script body goes here
)

Important: replace "XXX" in the "local requiredVer = XXX" line above with the value returned by jbFunctionsCurrentVersion() at the time you write the script. This way, your script becomes "locked" to require the version of jbFunctions you're currently using.

If your script is a macroscript, the script body would be wrapped inside the above if statement, and the macroscript definition (the "macroScript myMacro category:"MyCategory"" lines) would go around all of the above.



Disclaimer and Distribution

This script is provided as FREEWARE, and cannot be sold. This script cannot be bundled with any commercial package without express written permission from the author. You MAY distribute this script provided that it is complete with all files in the original archive, and no profit is made from the distribution.

You MAY take portions of this script and include them in your own script. Credit to the original author would be appreciated.

While this script has been used heavily in a production environment, and should be reasonably bug free, there may (read: ARE) still be bugs present. By using this product, you agree to exempt the author from any responsibility for the damages your computer or your data may incur through the use of this script.

This is an unsupported product so use it at your own risk!



Contact

Any bugs, comments, suggestions, etc. are more than welcome, and can be sent to me at john@johnburnett.com.