A SimpleObject is a kind of geometry primitive object that is defined by a tri-mesh, such as box, sphere, cone, and so on. In other words, all the Standard and Extended primitives in 3ds max. In scripting a SimpleObject plug-in, you supply a handler for building this mesh and 3ds max automatically handles scene display, hit-testing, ray intersection, rendering, modifier applicability, etc. A scripted SimpleObject plug-in is declared by specifying the <superclass> as simpleObject.
Scripted SimpleObject plug-ins require a create tool.
A SimpleObject plug-in must not perform any scene related actions such as creating scene nodes or building modifier stacks. It should basically only be adjusting its parameters in the mouse tool handlers and constructing a mesh in the buildMesh handler. Attempting to create scene nodes or applying modifiers in a SimpleObject plug-in will cause all kinds off strange interactions with the in-progress scene node creation.
A SimpleObject plug-in has a predefined local variable mesh. This variable contains the underlying mesh of the object being created. The mesh local variable is accessible in any of the plug-in's handlers, but is typically only built in the buildMesh handler. You can either modify the existing TriMesh value in place, using the TriMesh methods, or construct a new TriMesh value and assign it to the mesh plug-in local variable. The TriMesh methods and properties are described in Editable Mesh.
Example:
plugin simpleObject tower_plugin_def
name:"Tower"
classID:#(145345,543211)
category:"Scripted Primitives"
(
parameters main rollout:params
(
height type:#worldUnits ui:height default:0
width type:#worldUnits ui:width default:0
depth type:#worldUnits ui:depth default:0
)
params "Two Faces Parameters"
(
spinner height "Height" type:#worldunits range:[-1000,1000,0]
spinner width "Width" type:#worldunits range:[-1000,1000,0]
spinner depth "Depth" type:#worldunits range:[-1000,1000,0]
)
on buildMesh do
(
setMesh mesh \
verts:#([0,0,0],[width,0,0],[width,depth,0],[0,depth,0]) \
faces:#([3,2,1], [1,4,3])
extrudeFace mesh #(1,2) (height * 0.5) 40 dir:#common
extrudeFace mesh #(1,2) (height * 0.5) 50 dir:#common
)
tool create
(
on mousePoint click do
case click of
(
1: nodeTM.translation = gridPoint
3: #stop
)
on mouseMove click do
case click of
(
2: (width = gridDist.x; depth = gridDist.y)
3: height = gridDist.z
)
)
)
In this script a new primitive called Tower is defined. It constructs a (very) simple tower form; the first drag sets the base and the second drag sets the height. It contains three animatable rollout parameters, height, width and depth, that set the object's basic bounds. The key components here are the create tool and the on buildMesh handler and they work together in a fairly simple way. The create tool sets the values of the parameters and the on buildMesh handler constructs a mesh based on those parameter values.
The create tool can also access and set the position of the node that is being created to contain the new object through the Matrix3 value in the pre-defined mouse tool local variable nodeTM. In this case, the position portion of the node's TM is set to the initial mouse down world position. The on mouseMove handler sets the width and depth during click 2 and the height during click 3.
The on buildMesh handler constructs the desired mesh in the TriMesh value in the pre-defined plug-in local variable mesh. Typically, it does this by building the mesh from scratch each time the handler is called. In the example above, the mesh is initially set to a simple, two-face rectangular plane (via setMesh()) and then the 2 faces are extruded up and scaled-down twice to get the simple tower.
The mesh plug-in local variable is accessible in any of the plug-in's handlers, but is typically only built in the on buildMesh handler. You can either modify the existing TriMesh value in place using the TriMesh methods, or construct a new TriMesh value and assign it to the mesh plug-in local variable. The TriMesh created must be valid or a 3ds max crash may occur. All face, vertex, material ID, and texture vertex arrays allocated must be filled in the handler.
There are three additional event handlers that may be implemented for a scripted SimpleObject:
on OKtoDisplay do <boolean_expr>
If the OKtoDisplay event handler is implemented, <boolean_expr> should return true or false depending on whether it is OK to display the current mesh. This is useful in situations where a mesh might be in some degenerate state for particular parameter settings and so should not be displayed in the viewports. The default implementation is true. Note, empty meshes are OK to display.
on hasUVW do <boolean_expr>
If the hasUVW event handler is implemented, <boolean_expr> should return true or false depending on whether UVW coordinates are present on the mesh. In many primitive objects, a Generate Mapping Coords checkbox is provided for the user to control UVW coordinate generation and the hasUVW handler expression would return the state of this checkbox. The default implementation returns true or false depending on whether the mesh has texture vertices present or not. At present, only a single map channel is supported.
on setGenUVW <onOff> do <expr>
The setGenUVW event handler is called when 3ds max wants the plug-in to automatically generate mapping coordinates, as happens when you first render an object that has a material applied, but not mapping coordinates. It is called with a switch argument <onOff> which is true or false to turn on or off the mapping coordinates. If your plug-in is managing mapping coordinates, it should implement this handler and generate mapping coordinates when called with a true argument. For example:
on setGenUVW onOff do
(
genMapCoords = onOff
if genMapCoords and gen_mapping_coords()
)
where gen_mapping_coords() is a function that applies mapping coordinates to the mesh, returning true if the mapping was successful, false if not.
Here's another example that creates a mesh by first building other temporary objects and using mesh booleans to build the final mesh:
Example:
plugin simpleObject squareTube
name:"SquareTube"
classID:#(63445,55332)
category:"Scripted Primitives"
(
local box1, box2
parameters main rollout:params
(
length type:#worldUnits ui:length default:1E-3
width type:#worldUnits ui:width default:1E-3
height type:#worldUnits ui:height default:1E-3
)
rollout params "SquareTube"
(
spinner height "Height" type:#worldUnits range:[1E-3,1E9,1E-3]
spinner width "Width" type:#worldUnits range:[1E-3,1E9,1E-3]
spinner length "Length" type:#worldUnits range:[-1E9,1E9,1E-3]
)
on buildMesh do
(
if box1 == undefined then
(box1 = createInstance box; box2 = createInstance box)
box1.height = height; box2.height = height
box1.width = width; box2.width = width * 2
box1.length = length; box2.length = length * 2
mesh = box2.mesh - box1.mesh
)
tool create
(
on mousePoint click do
case click of
(
1: nodeTM.translation = gridPoint
3: #stop
)
on mouseMove click do
case click of
(
2: (width = abs gridDist.x; length = abs gridDist.y)
3: height = gridDist.z
)
)
)
In this example, the parameters and rollouts are handled in a similar manner to the first example, but the buildMesh handler generates the mesh in an indirect way. The final object is in the form of a rectangular pipe, a box with a box hole through the middle. Two plug-in locals (box1 and box2) are made to contain Box base objects whose size parameters are set according to the plug-in's parameters, box2 is the outer box, box1 is the hole. The final mesh is made by boolean subtraction of box1 from box2. In this case, a separate new mesh is created and assigned to the mesh plug-in local variable, in contrast to the first example which modified the object's original mesh directly. Either technique is OK.
The createInstance() method is used to directly create the box base objects. This method creates the geometry associated with the specified object, but does not create a node. This method is used since SimpleObject plug-in must not perform any scene related actions such as creating scene nodes or building modifier stacks.
See also