Lesson 9: Understanding the Help Files…

Sorry I’m starting to slack on my blog but been busy with a few other projects.

So here’s a quick post which will hopefully be really useful for everyone to understand, I know I wish someone had explained this to me a long time ago! How to understand the maxscript help file, it’s a typical thing that most tutorials and help files are written by people who understand the code completely, which can make it difficult for a normal human being to read.

So completely at random I’ve chosen to look up the Layer Manager interface in the help.

So the first thing to understand is that “LayerManger” is the interface we’re dealing with here, Interfaces are the way to interact with certain areas of max like the layer manager, the render element manager etc and normally use ‘Methods’ to read/write values. (More on Methods in a bit…)

So with that bit of confusion we have the properties, we’re familiar with properties….

.count : integer : Read

So this is telling us our LayerManager has a count property, it’s going to yield an integer value and it’s a value that can only be Read not written.

So what we can say is…

LayerManager.count

…which should return our number of layers.

If we want to do lots of code writing with our layermanager interface, instead of having to write out that long word each time we can assign it to a smaller variable….

lm = layermanager

and thus….

lm.count

is the same as layermanager.count, it’s purely a personal thing, I like it especially when dealing with the renderelementmgr interface, to shorthand this to re, makes the scripts a lot less cluttered and easier to read.

The next property is .current, which returns an Interface value, so much like the one we’re looking at now it has properties and methods, we’ll come back to this later.

So onto the Methods….

Methods are like predefined functions for the interface, the format for using them is as followed…

myVariable = theInterface.theMethod theArgument

‘theArgurment’ depends on what parameters you need to supply, which you’ll need to look into the documentation for, just like with functions if there is no arguments you simply use a ()

myVariable = theInterface.theMethod()

So for the method below we would write this….

thelayer = layermanager.getlayer 1

and thelayer will be a layerproperties interface value which if we look up we can see has properties like name, ishidden etc… it also has methods… the name property is read-only as it requires a .setname method to change the name value, by using a method instead of just assigning a string value to the property max can check that this name is unique and thus return a true of false value, saves you having to write a bunch of code to check to see what layer names already exist before you set one.

Back to our help file…

<Interface>getlayer <integer>which

..looks fairly complicated until you understand it, <Interface> at the start of this line means that the value we’re going to return from using this ‘method function’ will be an interface that we can assign to a variable. (I need to write some more about functions and returning values to go with this really.) In this case it states the interface that it will return will be a LayerProperties MixinInterface, which we can look up in the help and see all the properties and methods that the interface has, we’ll use it a bit later.

‘<integer>which’ is saying it’s requiring an integer (whole number value) to get the ‘layerproperties interface’ value of the layer which we are querying…

The note: getLayer is 0-based, just adds a bit more complicatedness into the matter….. Most of maxscript is 1-based number, i.e… as a human being you would count a list of items saying that’s the first item I have, item number 1…. there’s the second, item number 2, number 3…. etc etc..  but to a computer this is confusing… I won’t go into the exact reasoning behind it but it’s to do with memory allocation (boring) and apparently makes a big difference in proper computing… so what you end  up with is 0-based numbering, so instead of 1,2,3,4,5 you have 0,1,2,3,4…. confused… yes I still am, you just need to do be aware of it, don’t worry about understanding it.

LayerA   1st layer
LayerB   2nd Layer
LayerC   3rd Layer
LayerD   4th Layer

in 0-based numbering becomes….

LayerA      Layer 0
Layer B     Layer 1
LayerC      Layer 2
LayerD      Layer 3

So why… do you need to know this, well here’s a simple situation where you need to know this, lets say you want to print all the layers’ names.

--run a for loop going through the number of layers
for i = 1 to layermanager.count do
(
    --assign a new variable for the layer interface we get back from using a method/
    thelayer = layermanager.getlayer (i - 1)
    --our variable thelayer is a LayerProperties interface, which has 
    --the .name property to return the name of the layer
    print thelayer.name
    --note the i minus 1
)

Because this index is 0-based and our loop is running to the number of layers, we’re going to have i values in our loop of 1,2,3,4, which as we can see above won’t work, if we request layermanager.getlayer 4 it’ll return undefined as it won’t find a layer entry, and we’ll also miss layer 0.

So hopefully that clears a little bit of that up….

Lets jump down to the lines…

<boolean>deleteLayerByName <string>name

<boolean> at the start tells us that we’re going to get a boolean (true or false) value back from using this method, the function also requires a <string> string value which it expects to be the name of the layer. So an example would be…

--using our shorthand lm variable
theResult = lm.deleteLayerByName "Backup"

The layer called “Backup” would be deleted, (make sure you have “quotation marks” for string values), there’s some additional information in the help file which states that if the layer can and has been deleted a value of true would be returned, if there was still nodes/objects on that layer then it would return false.  So to use this we could tell the user whether we’ve been able to delete the layer.

if lm.deleteLayerByName "BackUp" then
    Messagebox "Layer Was deleted"
else
    Messagebox "Layer was not deleted"

If it helps you could also write the first line as

if (lm.deleteLayerByName "BackUp") == true then

which is probably clearer for a beginner maxscripter but it’s good to get into the hang of shortening your code as much as possible.

Then finally…

<void>editLayerByName <string>name

<void> means the method we’re using is not going to return any value to us, other than OK to confirm this line has been run, so we don’t need to/can’t assign it to a variable….  so you would run it as followed….

lm.editlayerByName “BackUp”

Hopefully that makes it fairly clear on how to understand Interfaces in the the maxscript help…. Look up ‘Core Interfaces’ to see just how many there are in 3dsmax and why it’s nice to know what they do, and how to understand all the documentation, as after all who is ever going to memorise every single property and method!

I said a short post… 1180 words later….