jbLib

Description:

jbLib is a MaxScript extension that contains a collection of new functions for use in MaxScript.

The current version is 7. This is defined in a global read-only variable jbLibVersion, which you can use to check that jbLib.dlx is installed and up-to-date for your script. If you use these functions, it is encouraged that you wrap your script in an if statement that does these checks, and gracefully bails if they fail. ie:

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

Important: replace "XXX" in the "local requiredVer = XXX" line above with the current value of jbLibVersion at the time you write the script. This way, your script becomes "locked" to require the jbLib version 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.

Functions:

ApplyVertexColors <collapsedMesh> <lightModel> <doMix> <castShadows> <useMaps>

Equivalent to the built in "Apply Vertex Colors" utility, but modifies the mesh object itself instead of adding a modifier.
Returns TRUE on success, otherwise FALSE.
collapsedMesh must be a collapsed editable mesh node, with no modifiers applied.
lightModel is an integer, where 0 is "Scene Lights" and 1 is "Diffuse".
See the Max documentation on the "Apply Vertex Colors" utility for an explaination of the arguments.
Required jbLibVersion: 1

DeleteDirectory <pathName>

Deletes the given directory (which must be empty). TRUE on success, otherwise FALSE.
Required jbLibVersion: 6

ElementFromFace <meshObject> <faceIndex>

Returns a bitarray with all the bits set that are in the same element as the given face index.
Required jbLibVersion: 1

EscapeHit

Returns TRUE if the escape key has been hit since the last time function has been called, otherwise FALSE.
This lets you bypass maxscript's default escape handler and write scripts that can abort on their own when escape is hit.
Note: this will return TRUE even if max does not have window focus.
Note 2: be careful with this one, since it's easy to accidentally set "escapeEnable" to FALSE, and forget to call this function inside your main loop, at which point max will appear to have crashed (since you can't break out of the loop by holding escape).
Required jbLibVersion: 4
Example usage:


		escapeEnable = FALSE

		do (

			-- your code here

		) while NOT EscapeHit()

		escapeEnable = TRUE

EvalTextureColorPoint <texture> <XYZ> <UVW>

Gets the color of any Max texture for the given position/uvw coordinates.
XYZ and UVW are Point3 values. UVW "usually" ranges between [0,0,0] (at the lower left of the texture) to [1,1,0] (at the upper right of the texture).
Note: not both coordinates will always be used.
i.e. If the texture is a Noise texmap using World coordinates, the UVW coordinates are ignored
Conversely, if the Noise is using UVW mapping, the XYZ coordinates are ignored.
However, textures can have sub-textures, so both coordinates may be used in the different sub-textures.
Lastly, this function simply point samples the texture, and doesn't support "fancier" textures like (say) the raytrace texture.
Required jbLibVersion: 2

GetClosestVertex <meshObject> <point3>

Returns the index of the closest vertex in the meshObject to the given point3.
Required jbLibVersion: 1

GetHitDistances <meshObject> <point3 p1> <point3 p2>

Given a mesh, this will return a sorted array of distances to all the intersection points between two given points in world space (p1 and p2).
A bit like IntersectRay, but returns all hit points along the "ray" instead of just the front-most.
Note: backfacing faces ARE included as well.
Required jbLibVersion: 4

GetRegistrySetting <rootKeyName> <keyPath> <valueName>
SetRegistrySetting <rootKeyName> <keyPath> <valueName> <value>

Gets/Sets a value to the Windows registry. Yes, beware.
rootKeyName can be one of:

#HKEY_CLASSES_ROOT
#HKEY_CURRENT_CONFIG
#HKEY_CURRENT_USER
#HKEY_LOCAL_MACHINE (Get only)
#HKEY_USERS (Get only)

keyPath is the full path to the key in question. (ie. "Software\\Microsoft\\Internet Explorer")
valueName is the name of the value in question (ie. "Download Directory")
value is the value to be set (ie. "C:\\MyDownloads")
The return value for Get is the value in question, or undefined if it doesn't exist.
The return value for Set is true on success.
In both functions, a descriptive exception will be raised and printed to the listener if something goes wrong.
Suggested usage would therefore wrap the Get/Set calls in a try()catch() block.
Note: the only supported registry value type right now is REG_SZ (standard strings).
Required jbLibVersion: 5

GetSpaceWarpForce <spaceWarpNode> <point3>

Returns the force the given spacewarp node is exerting at the given point in space.
Use SpaceWarpSupportsForce to check if the given spacewarp will work or not.
Typically will work only with spacewarps that are designed to work with particle systems.
Required jbLibVersion: 1

GetUNCPath <filenamePath>

Returns a UNC style path given a filename string, or undefined if the path can't be converted (ie. is a local drive).
Required jbLibVersion: 1

IsActive <atmospheric | effect>

Returns TRUE if the atmospheric/effect is active, otherwise FALSE.
Only available in Max3 (built into Max4+) Required jbLibVersion: 3

IsParticleSystem <node>

Returns true if the given node is a particle system.
Required jbLibVersion: 1

MoveFile <oldName> <newName>

Moves the given file (both oldName and newName must be full paths, including the filename). TRUE on success, otherwise FALSE.
Required jbLibVersion: 6

scanlineRenderEx struct

Constains extra variables that get/set values in the render dialog for the scanline renderer. Note: some are write-only.

antiAliasing (boolean)
shadows (boolean)
mapping (boolean)
filterMaps (boolean)
forceWireframe (boolean)
autoReflect (boolean)
imageMotionBlur (boolean)
objectMotionBlur (boolean)
wireThickness (float, write only)
autoReflectLevels (integer, write only)
objectBlurDuration (float, write only)
objectBlurSubdivisions (integer, write only)
objectBlurSamples (integer, write only)
imageBlurDuration (float, write only)

Required jbLibVersion: 7

SpaceWarpSupportsForce <spaceWarpNode>

Returns TRUE if the spacewarp works with the GetSpaceWarpForce function.
Required jbLibVersion: 2

Known Bugs/Limitations:

EvalTextureColorPoint could easily have bugs. But it's handy, so I'm including it.

foo@footools.com