This page provides information on how MaxScript can be used with Phoenix FD.
Overview
During the simulation process you can directly access the simulator's content using functions exported by the plugin.
You can use these to script advanced simulation rules, or to e.g. control a simulation on a remote machine that runs using only a Simulation License.
These functions can only be called when the simulator is in the appropriate internal state. The moments of time when the content can be manipulated properly are signaled by calling several callback functions, and you can access the simulator's content only inside them. Every single Phoenix FD object has its own script code that is kept in the scene file. When the simulation starts, the script is compiled, and its callback function overrides the callback functions of any previous simulation. During the simulation, you can change the script by executing the Evaluate all command from the File menu of the script editor. If a shared script for all simulator instances is desired, you have to delete the individual scripts for each simulator and deliver the callback functions as an ordinary MAXScript file.
Callback functions
| Function | Description |
| OnSimulationBegin | Called after the initialization of the simulator is done and before first execution. |
| OnSimulationStep | Called before each simulation step, after the interaction with the scene. |
| OnSimulationEnd | Called after the end of the simulation. The simulation core would be already destroyed during this callback so it should not be accessed. |
| OnNewFrame | Called after each frame export. |
Global functions
Each of the simulation channels (temperature, velocity, smoke etc.) exists in two instances - in the simulation core and in the simulation result. The functions in this section can access both the simulation core and result. If the first argument passed to the function specifies a Phoenix FD node, then the function accesses the simulation result. If there is no explicit Phoenix FD node specified, the function accesses the simulation core. In this case the target node is delivered internally. All the functions are exported as global functions beginning with "A_".
It should be noted that the simulation core exists only during the simulation and can be accessed only in the Callback functions.
| Functions | Description |
A_SetSystem Parameters: system:<integer> Available options are: 0 - Object space 1 - World space 2 - Grid (voxel) space Return value: none | Specifies which coordinate system will be used. |
A_Inject Parameters: where:<point3> amount:<float> [temperature:<float>] [smoke:<float>] [velocity:<point3>] [RGB:<point3>] Return value : none | Injects fluid in a given point. Using this function, you can create your own procedural sources. The result of the function CAN NOT be achieved by calling one or more A_SetX functions, because they do not affect the quantity of the fluid, but only the parameters carried by the fluid. The injection of fluid in some point causes changes in the content only of the nearest 8 cells, but produces an outgoing flow in the entire grid. Nevertheless the function is not slower than the ordinary A_SetX function, because the outgoing flow appears later, when the simulation is executed. If A_GetV function is executed immediately after A_Inject in some near point, the velocity will not be changed. |
A_SetV Parameters: x:<integer> y:<integer> z:<integer> velocity:<point3> Return value : none | Sets the velocity of a cell. If a Simulator name is used, the function will write to the loaded cache, otherwise the function will write into the grid of the running simulator, if any. |
A_SetRGB Parameters: x:<integer> y:<integer> z:<integer> RGB:<point3> Return value : none | Sets the RGB of a cell. If a Simulator name is used, the function will write to the loaded cache, otherwise the function will write into the grid of the running simulator, if any. |
A_SetT Parameters: x:<integer> y:<integer> z:<integer> temperature:<float> Return value : none | Sets the Temperature of a cell. If a Simulator name is used, the function will write to the loaded cache, otherwise the function will write into the grid of the running simulator, if any. |
A_SetSm Parameters: x:<integer> y:<integer> z:<integer> smoke:<float> Return value : none | Sets the Smoke of a cell. If a Simulator name is used, the function will write to the loaded cache, otherwise the function will write into the grid of the running simulator, if any. |
A_SetFl Parameters: x:<integer> y:<integer> z:<integer> fuel:<float> Return value : none | Sets the Fuel of a cell. If a Simulator name is used, the function will write to the loaded cache, otherwise the function will write into the grid of the running simulator, if any. |
A_GetFl Parameters where:<Point3> Return Value: <float> | Gets the Fuel in a given point. If a Simulator name is used, the function will read from the loaded cache, otherwise the function will read from the running simulator, if any. |
A_GetV Parameters where:<Point3> Return Value: <point3> | Gets the Velocity in a given point. If a Simulator name is used, the function will read from the loaded cache, otherwise the function will read from the running simulator, if any. |
A_GetRGB Parameters where:<Point3> Return Value: <point3> | Gets the RGB in a given point. If a Simulator name is used, the function will read from the loaded cache, otherwise the function will read from the running simulator, if any. |
A_GetT Parameters where:<Point3> Return Value: <float> | Gets the Temperature in a given point. If a Simulator name is used, the function will read from the loaded cache, otherwise the function will read from the running simulator, if any. |
A_GetSm Parameters [node:<Simulator>] where:<Point3> Return Value: <float> | Gets the Smoke value in a given point. If a Simulator name is used, the function will read from the loaded cache, otherwise the function will read from the running simulator, if any. |
A_StartSim Parameters node:<Simulator> [cache: <String>] [startframe: <integer>] | Starts the simulation. Passing just the simulator node will start a new simulation. If you pass the path to a cache file, the effect is that of the Load button in the Simulation rollout: the simulation state will be loaded from the cache and the simulation will continue from the specified Start Frame. If you manually pass the startframe index too, it takes precedence over the Load function and the simulation will be restored from the given frame, the same way that the Restore button works. This function will decide between simulation and re-simulation depending on the state of the Particle Resimulation and Grid Resimulation switches. |
A_StopSim Parameters node:<Simulator> | Stops the simulation |
A_Wait Parameters node:<Simulator> | This function halts the execution of the script until the specified simulator has finished running. Usually this function is used along A_StartSim when you want to run certain actions after the simulation is finished. Use this function extremely carefully because it does not block the GUI of 3ds Max. |
A_CreateParticle Parameters Particle group:<string> where:<Point3> [Radius:<float>] [Velocity:<Point3>] Return Value: none | Creates particle in given position with given properties. |
A_Freeze Parameters: x:<integer> y:<integer> z:<integer> | Freezes the given cell. The frozen cell act as a solid object |
A_Unfreeze Parameters: x:<integer> y:<integer> z:<integer> | Unfreezes the given cell. Keep in mind that the simulator counts the freezing and you have to execute the same count of unfreezing operation to successfully unfreeze a cell |
A_QuickSetup Parameters: setup: <integer> Available options are: 0 - fire 9 - tap water Return Value: none | Creates a Quick Simulation with the selected object. |
A_LoadRenderPreset Parameters node: <Simulator> preset path: <String> | Loads the specified render preset file. The preset path can be a full path or use the $(dir) macro, which denotes the current scene file's directory. For example, the following will load "preset.tpr" from the current scene directory: A_LoadRenderPreset (getnodebyname "PhoenixFDFire001") "$(dir)\preset.tpr" |
A_SaveRenderPreset Parameters node: <Simulator> preset path: <String> | Saves a Phoenix FD render preset to a file with the current render and preview settings. The preset path can be a full path or use the $(dir) macro, which denotes the current scene file's directory. |
A_LoadSimPreset Parameters node: <Simulator> preset path: <String> | Loads the specified simulation preset file. The preset path can be a full path or use the $(dir) macro, which denotes the current scene file's directory. For example, the following will load "preset.tpr" from the current scene directory: A_LoadSimPreset (getnodebyname "PhoenixFDFire001") "$(dir)\preset.tpr" |
A_SaveSimPreset Parameters node: <Simulator> preset path: <String> | Saves a Phoenix FD simulation preset to a file. The preset path can be a full path or use the $(dir) macro, which denotes the current scene file's directory. |
Per-node functions
Phoenix FD provides an interface for getting grid data and loading render presets directly from the Simulator node.
The available functions are:
setCoordSys – Specifies which coordinate system will be used.
Available options are:
0 - Object space
1 - World space
2 - Grid (voxel) space
loadRenderPreset – Loads a previously saved Phoenix FD render preset from a file.
saveRenderPreset – Saves a Phoenix FD render preset to a file with the current render and preview settings.
loadSimPreset – Loads a previously saved Phoenix FD simulation preset from a file.
saveSimPreset – Saves a Phoenix FD simulation preset to a file with the current render and preview settings.
getVelocity – Gets the Velocity value in a given point.
getRGB – Gets the RGB value in a given point.
getTemperature – Gets the Temperature value in a given point.
getSmoke – Gets the Smoke value in a given point.
getFuel – Gets the Fuel value in a given point.
$PhoenixFDFire001.getFuel (Point3 15 15 15)
Global Variables
The following global variables are initialized before entry in the callback functions:
| Variable | Description |
| this:<simulator> | Points to the simulator that calls the callback function |
| t:<float> | The simulator's internal time |
| dt:<float> | The simulator's internal step |