How do I understand the function definitions in this document?

MAXScript FAQ > How do I understand the function definitions in this document?

The above topic explains the general syntax used in the MAXScript Online Reference, but practice has shown that many users have difficulties applying the function definitions to actual code.

Below are some guidelines to help you understand the syntax.

Here is a typical function definition taken from the Meshop Face Methods:

meshop.detachFaces <Mesh mesh> <facelist> delete:<boolean=true> asMesh:<boolean=false>

Detaches the specified faces.

If delete is true , the faces are deleted after being detached. If delete is false , the faces are not deleted.

If asMesh is true , the faces are detached and returned as a Mesh value. If asMesh is false , the faces are detached as an element in the mesh and a value of OK is returned.

First of all, this function is part of a structure called meshop. A structure can be used to group related functions. This function has been implemented using the SDK, but you can organize your own MAXScript functions by putting them into a structure, too. See Defining Local Functions in Structures for more info.

The name of the function is detachFaces. It is written in bold because according to the Syntax Definitions in This Document topic, bold denotes code written "as is". Actually, the name of the structure (meshop) would have to be in bold too, but this would make it more difficult to read the documentation. Now you can easily spot any function or keyword by quickly browsing a page and looking for bold letters.

Next, two arguments (parameters) to the function are described. These two arguments are compulsory and the function will issue an error message if the parameters are not supplied or the classes of the provided values do not match the requirements.

<Mesh mesh> defines a rule. Any text written inside of <> describes what should be used in place of the rule. In this case, it tells you to replace the rule with a mesh object.

The next rule, <facelist>, tells you to provide a list of faces. A face list can be either a regular Array containing indices of the faces to affect, for example #(1,3,10,11,12,13,14,15), or a bitArray with bits set for any face to be affected, for example, #{1,3,10..15}.

Then, two optional parameters are described. While the order of the first two parameters is significant (the function always expects the mesh to be the first and the facelist to be the second parameter), optional named parameters can come in any order - they are recognized by their name.

NOTE:

In the syntax definitions of this document, optional parameters are written inside of [] brackets. Typically, when defining a function, any named parameters are optional. This is why in some function definitions, optional parameters might not have been listed inside of [] brackets.

When a value is not provided for an optional parameter, the special value of unsupplied will be sent to the function instead. The function will check whether the value is supplied or not and replace an unsupplied value with a default value. To learn more about unsupplied values, see What is the difference between 'undefined' and 'unsupplied' values? and Unsupplied Value topics.

In the case of the delete: parameter, the definition tells you that the name of the parameter should be written as is, and a boolean value ( true or false ) is expected after the colon ' : '. A value of true will be assumed by default if the parameter is not supplied.

Finally, the asMesh: parameter is also optional and will be false by default if not supplied.

A TYPICAL CALL TO THIS FUNCTION WOULD LOOK LIKE:

meshop.detachFaces $MyMesh02 #{1..25}

In this case, the function is being told to detach faces with indices from 1 to 25 from the EditableMesh object named "MyMesh02". The faces will be deleted by default from the original mesh and a new element inside of MyMesh02 will be created because the two optional parameters will be used with default values.

IF YOU CHANGE THE LINE TO

meshop.detachFaces $MyMesh02 #{1..10,40..55} delete:false

the faces with indices from 1 to 10 and from 40 to 55 will be cloned to element inside of the mesh - a new element will be created (asMesh is false by default), but the original faces will not be deleted from the mesh.

IF YOU CHANGE THE CODE AGAIN TO

newMesh = meshop.detachFaces $MyMesh02 #(1,2,3,4,5,10,11,15) delete:false asMesh:true

then this time the faces with indices described by the regular array will be cloned to a new TriMesh without being deleted from the original object. The function will return the TriMesh value and will store it into the newMesh user variable. See the second example provided for this function in the Meshop Face Methods topic for more info on using the returned TriMesh value to create a new object.