3ds Max Plugin User's Guide

On this page:

Introduction

There was a need for some sort of documentation on how to use the plugin, this became evident to me in the last few days, when I was asked a bunch of questions on how to create simple objects for simulation and/or export. Time is short, so that is also how this guide will be - very short to the point.

I hope to cover most of the most important stuff.

Installation

Installation of the latest version should be easy enough, simply download the installer and install it into the 3ds max folder. If you are not using the installer, then the following files should be installed for full functionality: 3dsmax\plugins\physx.dlm 3dsmax\scripts\startup.ms 3dsmax\scripts\physx\*.ms 3dsmax\NxTetra.dll

If you have had a really old version installed previously, you might still have a PhysXLoader.dll or other PhysX-related dll's such as cooking in the 3dsmax folder. Please remove those manually and then install the new version. They might interfere with the operation of the new plugin (e.g. you would notice this when you try to add objects to the scene, see below, then you would get a message in the style: "found a PhysX SDK, but it is not of the correct version").

General

The most important panel to know about when working with the PhysX plugin is found under the "utilities" toolbar, and is called "PhysX control panel". It should automatically have been started when 3ds Max started, or else it's absence is an indication that the installation of the plugin did not go as planned. One way to see if the C++ part of the plugin has been correctly installed and loaded is to open the maxscript listener and type "PX" (without the quotes), that is the plugin object, through which the script parts of the plugin communicates with the PhysX SDK.

Typing "px.debugPrint()" will give you an indication of what objects are currently added to the PhysX scene. This list is not totally complete, but it can function as a help when debugging problems when starting to learn the plugin. E.g. it would be possible to see if you managed to make the plugin use the same referenced triangle mesh for several PhysX actors by looking at the number of triangle meshes currently in the simulation. For large scenes it is important that you manage to share triangle meshes (if there are instances of the same mesh). Please note that now I did not say that you should use triangle meshes for dynamic objects, that you should not.

One more, VERY IMPORTANT point is that you should never use scaling on any transforms involved in PhysX objects. If you want to change the size of e.g. a sphere, then you need to do so by changing the radius of the sphere, not by scaling it. The PhysX plugin was not built with scaling in mind and the PhysX SDK does not handle scaling at all. If you scale objects, things might look good at first, but then you will see generally strange physical behavior when simulating, and you might end up with asserts because there will be infinite number or divisions by zero after a few seconds of simulation.

Rigid Bodies

I'll give a quick guide on how to create a simple rigid body, consisting of one sphere to build an understanding of how the plugin works. As this is quick and dirty, I will give a simple list of tasks to perform. Remember that the PhysX Utility is found under "Utilities" (the hammer) and that the "PhysX panel" is found there.

1. Create a sphere

2. Go to "Utilities" and then "PhysX control panel"

3. Select the sphere

4. Press the button named "Make physical / edit"

5. Now that button will change into a drop down and a new panel will emerge

6. In the dropdown, you can specify the type of object that you are creating. This will default to "dynamic rigid body".

7. Make sure that the dropdown really says "dynamic rigid body"

8. In the new panel, you can change properties such as mass and friction

9. When you are satisfied with the properties of the rigid body you are creating, press the "add selected" button

10. Now there should have been a rigid body created (3ds max will freeze up for a short time when the SDK is being created)

11. Open the maxscript listener to see if there were any error messages or warnings

12. Try writing px.debugPrint() in the maxscript listener to list the contents of the PhysX engine

13. Go back to the PhysX panel and press "continous"

14. Now the sphere should start falling "down", default gravity direction can be set in the "Physx parameters" panel

Before you go on, you can press the "remove all" button, that will clear the PhysX scene and let you add new objects to the simulation.

If you got through all those steps, well, then you have just created a dynamic, single shape rigid body actor (NxActor). If you want to create a compound actor (a rigid body with several shapes), then you do like following (somewhat shorter list, since I am leaving stuff out that you learnt above):

1. Create two spheres (close to each other, but not in each other's center)

2. Select both and group them, then select the group

3. Press "make physical / edit" in the physx panel, and make sure that it's a "dynamic rigid body"

4. Press "add all physical", that will add all physical objects to the simulation, not just the ones you have selected

5. Press "continous". The two spheres should not interact with each other, and stay fixed relative to each other

If the two sphere push each other apart, then you did not manage to make the actor compound, but if they don't, or if you have created the spheres at a distance to each other, then you can't really tell if they are in the same actor or not, until they hit another object. Let's also create an object to simulate the ground, so that actors can fall down and come to rest on it.

First press "reset", so that objects are reset at the position where they were created. If you "add all" again after having simulated a bit, the "original" position of the objects will be the one they had when last pressing the "add all" or "add selected" buttons.

1. Create a large box "under" the dynamic objects

2. Make this box a "static rigid body"

3. Add to simulation

4. Start continous simulation, and watch the objects interact.

Triangle meshes

Triangle meshes are normally used only for static objects in the PhysX simulation. You could have a triangle mesh on a dynamic object, but then all other objects that it is in the vicinity of should be the of the other types of geometry, e.g. boxes. The PhysX SDK also has trouble automatically calculating properties such as mass and inertia tensor for dynamic triangle mesh objects.

As I noted above, you should try to make sure that the SDK can share the same triangle mesh resource whenever possible, you do this by making references in 3ds when creating copies of the same trimesh. Please note that scaling will not work here, as the PhysX plugin does not regard that, so if you want similiar-looking objects of different scales, then you also need to make several trimeshes.

A quick test on how to share a trimesh:

1. Start with a clean scene, press "remove all" on the physx panel and then new the scene

2. Create a torus with 10 segments and 10 sides

3. Select the "move tool"

4. Drag the torus to the side and drop to make a copy, but you must make the copy an "instance", otherwise mesh sharing won't work

5. Select both tori

6. Press "make physical" and make it a "static rigid body"

7. This is IMPORTANT: under "specify physics representation", select "Triangle mesh (static objects only)"

8. Add the object to the simulation

9. Now go to the maxscript listener and write "px.debugPrint()", if you were successful, there should only be one triangle mesh but with two references to it

During this session, I noticed something that really shouldn't happen - the "make physical" button stopped working. If this happens, close the "PhysX utility" by pressing the "close" button, and then issue the following command in the maxscript listener: "addRollout px_control", that will open the PhysX control panel again and now the button should be working.

Convex hull

For many dynamic rigid bodies you will want to use a type of triangle mesh, but not a real full-freedom triangle mesh type. This is called a convex hull, and it has the restriction that no sides may be concave. To create a convex hull, you can either add a simple triangle mesh object and not specify that it should be simulated as a triangle mesh (the "important" point from above), or you can make sure that you know how the convex hull will look like, by creating an explicit convex hull explicitly, through a "geometry tool" available in the PhysX Utility.

1. Create a torus, as above

2. Select the torus

3. Go to "PhysX utility", click the button "Geometry tools"

4. A new panel will open

5. At the end of that panel there is a heading "Create convex hulls"

6. Let the settings be at 32 vertices and 0,025 for hull inflation, of press the "SW" button to use the current skin width value of the SDK

7. Press "create hulls", and a new object will be created.

8. This new object covers the torus, but does not have a hole in it, as it is a convex...

9. Delete the newly created object and try different settings

Joints

Being able to joint rigid bodies together is an important feature in a physics engine, so this is of course also supported through the 3ds Max plugin. This support is implemented only for the "6 degrees of freedom joint", which is a single joint object that can be configured to work as most other joint types that are usually available in physics SDKs. Please read the user documentation for the PhysX SDK to learn more on how to setup the properties of the joint in more detail.

To create a joint between two objects, do the following:

1. Create a "kinematic rigid body", e.g. a box

2. Crate a dynamic rigid body, at a distance from the box, but at the same height (remember the direction in which objects fell during the previous lessons)

3. Go to the "Create" toolbar, and then select "helpers"

4. In the dropdown menu, there is a choice called "AGEIA PhysX", select it

5. There are three objects to choose from, select "PxJoint"

6. Click and drag to create the joint, it is created in quite a few steps, but this is so that you should be able to easily specify the degrees of freedom that the joint has. Drag so that the joint is draw approximately as a half sphere, this will give the ball approximately that area to move within

7. Then edit the properties of the joint

8. The most important properties are the two first: Body0 and Body1, this is where you need to make references to your rigid bodies

9. Click the button next to "Body0" and select the box

10. Select the dynamic sphere as "Body1"

11. Go back to the physx control panel

12. Add all objects to the simulation

13. Simulate continously. Now the sphere shouldn't be able to fall anywhere, instead it should rotate around the box

14. Play around with the settings in the joint panel. When you have changed settings, you need to re-add the joint though, so press "add all" before simulating to see how the joint behaves

Fluid

Fluids are not created with the built-in 3ds Max objects as are mostly used for the rigid bodies that you created above, but instead two special objects are used. These can be found in the "Create" toolbar, under "helpers" and then in the dropdown menu: "AGEIA Physx" (same menu as the joint object from above).

I will go through the steps of creating a simple fluid that will spray some fluid particles into the air, but again - if you want to learn in detail how to set the properties of the fluid, you need to read the user documentation for the PhysX SDK.

Create a simple fluid, with one emitter:

1. Go to "Create" toolbar

2. Select "helpers" and then "AGEIA PhysX"

3. Create a "PxFluid" object. The positioning of this object is not very important, but it decides when the fluid particles will be drawn, so position it where you are planning to put the emitter later

4. Since this is a very simple example, we won't make any more settings in the fluid object

5. Create a PxEmitter

6. You need to bind the emitter to the fluid, edit the properties of the emitter

7. Click the button after "Fluid:" and then select the fluid object

8. Then go to the PhysX control panel

9. Click "add all"

10. Simulate continously, and there should be a small chain of particles falling down from the emitter

Now you can play around with the fluid and emitter settings. Most of the settings are direct copies of what can be done from within the PhysX SDK, so have a look at that documentation if you are wondering how you should set the properties. Some settings are hard to get right, and setting them badly might make the simulation go very slow.

Fluid drains

If you want to create a "fluid drain", this is a shape that when fluid particles hit it, they are removed from the simulation, you do:

1. Create a rigid body with e.g. a box, this will be the fluid drain shape

2. Create a fluid as above, with an emitter

3. Edit the fluid properties, at the bottom there is a list of "fluid drains"

4. Click "add drain" and select the box

5. Now you have a drain, add or remove drains as you like.

Drains can be shared amongst fluids. You do not have to create specific actors to work as drains either, if you e.g. had a floor already, you could use that as drain.

Fluid connected to a rigid body

It is possible to create fluid emitters that are moved around together with an actor, to do so:

1. Edit the properties of the emitter

2. Click the button next to "Frame reference" and then select a rigid body

The fluid emitter will now follow the selected rigid body when it moves around in the world.

Fluid compartment

There is a setting called "fluid compartment" in the fluid settings panel. This is a simple way of creating fluids in different compartments (basically different scenes). 0 is the default scene, or the default compartment actually. If you want a fluid to be created in another compartment, then select a different number and then add the fluid. You can't first add a fluid to one compartment and then change the number of the compartment easily though. If you want to change the compartment number of a simulated fluid, you should first "remove all" then change compartment number and then "add all".

Cloth

Cloths can also be simulated in PhysX, and it is rather easy to make a cloth in the 3ds Max plugin:

1. Create e.g. a plane, (each vertex will become a cloth particle, so select a suiting number of segments)

2. Convert the plane into a mesh object (you can create the cloth without doing so, but you will not see the simulation inside of 3ds Max if the geometry is not an editable mesh)

3. Go to the physx control panel and make the plane physical

4. Select "Cloth" as how the object should be simulated

5. Then you will get another panel below, than the one normally there for rigid body object, where you can speciy settings for the cloth

6. Then "add all"

7. Simulate

This is basically all that needs to be done, please (as always in this tutorial) read more about cloth in the PhysX documentation.

SoftBody

Actually cloth can have volume, through the pressure settings (only works if the cloth is describing a closed volume though), otherwise all the objects that we have been creating are rigid. The softbody is a type of actor that is built of tetrahedra and where the simulation gives the objects a feeling of the objects being soft.

It is rather difficult to create a good softbody mesh, but there are some tools in the plugin to try and help in this. I will give an example that should work, and then you need to experiment with that example as a stepping stone.

1. Create a geosphere (this is a more stable choice for softbody than a normal sphere)

2. Go to the PhysX Utility and open the "geometry tools" panel

3. Select the geosphere

4. Press the "build mesh" button (with "create editable mesh" and "create iso surface" selected, subdiv 10 and simplification 0,5)

5. Now you will get a new sphere, which is a bit larger than the old one

6. Select the new sphere

7. Go to the physx control panel

8. Make physical

9. Select "SoftBody"

10. Add all

11. Then simulate, but currently you can't see the progress of the simulation inside of 3ds Max. However, you can see it in the VRD, see below how to use that for wathching the simulation.

VRD Connection

The 3ds Max plugin has been instructed to try and connect to the AGEIA PhysX VRD (visual remote debugger) when the SDK object is being created. So if you want to look at your simulation inside of the VRD, you can do the following:

1. Start the VRD

2. Remove all physics objects from the scene (this will also release the SDK)

3. Add all physics objects

4. Start the simulation, now you should see the progress in the VRD

Please note: You can currently not drag objects around inside the VRD, this will crash the plugin. This is due to the plugin iterating over all objects in the PhysX scene and trying to find the corresponding 3ds Max object, and when you drag in the VRD a small actor is inserted to work as a drag anchor. This is simply a bug, and should be fixed.

Export

This is easy, compared to some of the other tasks. Guess what, time for another step-by-step walkthrough:

1. Start out with a clean scene (or make sure to start with an empty PhysX scene, by clicking "remove all")

2. Create all the objects you want to export

3. Click "add all physical"

4. Select the type of asset you want to create, the default is XML

5. Click "export to"

6. You will get a file dialog, choose the location and filename

7. Click "save"

8. Depending on the scene size and complexity, it will take some time to write the export file. Normally this is not long enough to notice though.

9. Finished

I hope this tutorial will help you in some ways, at least it should help in getting started with the plugin.