MAXScript Exposure

All Stoke MX properties and methods are exposed to MAXScript. In fact, the complete User Interface and Simulation logic are controlled by MAXScript.

Disclaimer

The Stoke MAXScript exposure is subject to change without notice. The following documentation reflects the current implementation of the Stoke MAXScript Interfaces. Thinkbox Software reserves the right to modify the implementation and the documentation in the future as needed without guarantee for compatibility with existing scripts.

Components Overview

StokeMX.DLO

StokeBase GeometryClass object

  • The StokeMX.DLO plugin implements a StokeBase Geometry Class 3ds Max object which has no UI.
  • The StokeBase implements the viewport playback and memory caching, Krakatoa Modifiers (Magma, Delete) support and drawing options (Dots, Vectors).
  • The StokeBase object is then extended by a Stoke Geometry Scripted Plugin which implements ParamBlocks to store the majority of simulation-related properties and objects.

ReflowGlobal Interface

  • The StokeMX.DLO also exposes a global interface called StokeGlobalInterface.
  • This interface provides properties and methods controlling the Simulation engine.
  • Evaluating showInterface ReflowGlobal in the MAXScript Listener will produce the following output:
showInterface StokeGlobalInterface
  Interface: StokeGlobalInterface
   Properties:
    .HomeDirectory : TSTR by value : Read
    .Attributions : TSTR by value : Read
    .Version : TSTR by value : Read
    .Licensed : bool : Read
    .ViewportType : enum : Read
       ViewportType enums: {#legacy|#nitrous}
    .PointSizeSupported : bool : Read
    .LoggingLevel : enum : Read|Write
       LoggingLevel enums: {#none|#error|#warning|#progress|#stats|#debug}
    .MaxDebuggerIterations : integer : Read|Write
    .MaxMarkerCount : integer : Read|Write
   Methods:
    <void>ShowLicenseDialog()
    <Interface>CreateAdvector <string>Type
    <Interface>CreateIDAllocator()
    <Interface>CreateReflowField <node>Node
    <Interface>CreateDummyReflowField()
    <Interface>CreateParticleVelocityField <node>Node <float>Spacing Min:<point3> Max:<point3> BoundsPadding:<integer> RemoveDivergence:<bool>
       Min default value: [0,0,0]
       Max default value: [0,0,0]
       BoundsPadding default value: 5
       RemoveDivergence default value: true
    <Interface>CreateAdditiveVelocityField <Interface array>Fields
    <Interface>CreateKrakatoaGenerator <node>Node JitterRadius:<float> IgnoreIDs:<bool>
       JitterRadius default value: 0.0
       IgnoreIDs default value: false
    <Interface>CreateGeometryGenerator <node>Node Mode:<string> VolumeSpacing:<float> SelectionType:<string> VertexJitterRadius:<float>
       Mode default value: "Surface"
       VolumeSpacing default value: 10.0
       SelectionType default value: "FaceSelection"
       VertexJitterRadius default value: 0.0
    <Interface>CreateFumeFXGenerator <node>Node
    <Interface>CreateParticleSet <string array>ExtraChannels
    <void>AdvectParticleSet <Interface>ParticleSet <Interface>Advector <Interface>VelocityField <float>TimeStepSeconds
    <void>UpdateAgeChannel <Interface>ParticleSet <float>TimeStepSeconds
    <void>UpdateAdvectionOffsetChannel <Interface>ParticleSet <Interface>Advector <Interface>VelocityField <float>TimeStepSeconds
    <void>ApplyAdvectionOffsetChannel <Interface>ParticleSet
    <void>MagmaEvaluateParticleSet <Interface>ParticleSet <maxObject>Magma <time>EvaluationTime <Interface>ErrorReporter
    <void>WriteParticleSet <Interface>ParticleSet <string>FilePath
    <void>BeginRenderMode <node array>NodeList
    <void>EndRenderMode <node array>NodeList
    <enum>GetSourceType <node>Node
       GetSourceType enums: {#invalid|#particles|#geometry|#fumefx
    <enum>GetVelocityType <node>Node
       GetVelocityType enums: {#invalid|#particles|#fumefx|#phoenix|#force|#field
    <void>SetTempDirectory <string>Directory
    <bool>IsEmberField <node>Node
    <Interface>CreateMXSField <node>Node StackIndex:<integer>
       StackIndex default value: 0
    <void>WriteFXDFile <string>FilePath <node>Node <point3>WSBoundsMin <point3>WSBoundsMax <float>Spacing StackIndex:<integer>
       StackIndex default value: 0
    <void>WriteField3DFile <string>FilePath <node>Node <point3>WSBoundsMin <point3>WSBoundsMax <float>Spacing StackIndex:<integer>
       StackIndex default value: 0
    <void>WriteOpenVDBFile <string>FilePath <node>Node <point3>WSBoundsMin <point3>WSBoundsMax <float>Spacing StackIndex:<integer>
       StackIndex default value: 0
   Actions:
OK

The properties and methods of this Interface are documented further on this page.

StokeUI.MS

  • The StokeUI.MS implements the Stoke Scripted Plugin extending the StokeBase class.
  • It also implements to UI-side simulation logic including the SIMULATE, STOP and RESUME buttons’ event handlers and the callback functions called by the Simulator to update data and the UI.
  • Finally, it implements the MacroScript used to create Stoke objects via a toolbar or menu ActionItem. This MacroScript speeds up access to the Stoke object and also supports faster creation by adding selected objects to the Stoke Distribution and Velocity Field lists.

StokeSimulator.MS

  • The StokeSimulator.MS implements a StokeSimulator MAXScript Struct encapsulating the Simulator logic and the main simulation loop.
  • This separation allows other scripted tools to perform simulations without residing inside the StokeUI.MS. For example, the StokePartitioning.MS script (see below) can perform simulations without the Stoke object being selected or active in the Command Panel.

StokePartitioning.MS

  • The StokePartitioning.MS script implements a scripted tool for saving multiple variations of the same Stoke object with varying Random Seeds.
  • It includes Deadline Partitioning submission support.

StokeGlobalInterface Properties And Methods

Properties

StokeGlobalInterface.HomeDirectory

  • This read-only property contains the Windows path where the StokeMX.DLO was loaded from, up two folders.
  • For example, if the DLO was located under C:Program FilesThinkboxStoke MX3dsMax2013, the propery will point at C:Program FilesThinkboxStoke MX
  • This property is used to locate other components like .MS scripts and icons during the loading process.

StokeGlobalInterface.Attributions

  • This read-only property contains the text of the software attribution message.

StokeGlobalInterface.Version

  • This read-only property contains a String with the Version Number of the Stoke MX build.
  • It is used mainly to display the version in the Help rollout.

StokeGlobalInterface.Licensed

  • This read-only property contains a boolean value which is True of a Stoke MX license could be obtained, and False if no Stoke license could be found.

StokeGlobalInterface.ViewportType

  • This read-only property conrains a name enum value according to the Viewport drawing engine.
  • Possible values are
    • #legacy - running pre-Nitrous legacy DirectX, OpenGL or Software display drivers.
    • #nitrous - running Nitrous graphics.

StokeGlobalInterface.PointSizeSupported

  • This read-only boolean property contains
    • true when the viewport supports point size controls (Nitrous DirectX 9 drivers in 3ds Max 2015 and higher).
    • false when the viewport supports only fixed-size points drawing.

StokeGlobalInterface.LoggingLevel

  • This property lets you get and set the Logging Level of Stoke MX.
  • The Logging is currently performed by outputting to the Listener.
  • Possible values are:
    • #none
    • #error
    • #warning
    • #progress
    • #stats
    • #debug

StokeGlobalInterface.MaxDebuggerIterations

  • Get/set the number of iterations in the Magma Debugger.
  • Default is 10,000 iterations.
  • For each iteration, all output values of all nodes are collected, so higher iteration limits result in higher memory usage and slower Debugger evaluation.

StokeGlobalInterface.MaxMarkerCount

  • Get/set the maximum number of viewport markers to be drawn for an object.
  • The Automatic Reduction will kick in to ensure the number of markers is always less than the limit.

Methods

<void>StokeGlobalInterface.ShowLicenseDialog()

  • This method will open the Stoke MX License Dialog.

<Interface>StokeGlobalInterface.CreateAdvector <string>Type

  • Calling this method will return an Advector interface.
  • The Type argument can be “RK2”, “RK3” or “RK4”, but the current StokeMX build is set to use “RK2” since it is the fastest and the results of the three Advectors are usually very similar.
  • The Advector Interface exposes one method - AdvectParticle. It can be used to advect a particle position with a given particle velocity using a velocity field within a specified time interval:
a = StokeGlobalInterface.CreateAdvector "RK2"
<MixinInterface:Advector>
showInterface a
  Interface: Advector
   Properties:
   Methods:
    AdvectParticle ParticlePosition ParticleVelocity VelocityField TimeStepSeconds
   Actions:
OK

<Interface>StokeGlobalInterface.CreateIDAllocator()

  • Calling this method will return a new IDAllocator Interface.
  • This Interface should be assigned to the .IDAllocator property of Particle Generators. It is responsible for assigning IDs to new particles created by the Particle Generators.
  • The IDAllocator Interface exposes one method - AllocateIDs.
idSource = StokeGlobalInterface.CreateIDAllocator()
<MixinInterface:IDAllocator>
showInterface idSource
  Interface: IDAllocator
   Properties:
   Methods:
    <INT64>AllocateIDs <INT64>NumIDs
   Actions:
OK

<Interface>StokeGlobalInterface.CreateReflowField <node>Node

  • Calling this method will return a new ReflowField Interface.
  • The argument must be a valid Velocity Field source, but NOT a particle system or other Stoke objects (which are handled by the CreateParticleVelocityField() method).
  • Valid sources are Force SpaceWarps, FumeFX and SIM Ember grids.
  • The ReflowField Interface exposes one property - .VelocityScale which defines the Velocity Scale of the field and defaults to 1.0.
  • The ReflowField Interface exposes two methods - UpdateToTime() and EvaluateVelocity().
  • UpdateToTime() updates the source to the specified time in order to produce the velocity field at that time.
  • EvaluateVelocity() can be used to query the velocity of the field at a given point in space.
rf = StokeGlobalInterface.CreateReflowField $FumeFX001
<MixinInterface:ReflowField>
showInterface rf
  Interface: ReflowField
   Properties:
    .VelocityScale : float : Read|Write
   Methods:
    <void>UpdateToTime <time>Time
    <point3 by value>EvaluateVelocity <point3>Position
   Actions:
OK

<Interface>StokeGlobalInterface.CreateDummyReflowField()

<Interface>StokeGlobalInterface.CreateParticleVelocityField <node>Node <float>Spacing Min:<point3> Max:<point3> BoundsPadding:<integer> RemoveDivergence:<bool>
Min default value: [0,0,0] Max default value: [0,0,0] BoundsPadding default value: 5 RemoveDivergence default value: true
  • Calling this method will return a new ReflowField Interface based on the Particle object passed as first argument.
  • The second argument defines the voxel grid size.
  • The optional arguments allow the definition of the min. and max. bounds of the grid, the padding of the grid beyond the automatically determined size, and the divergence removal.

<Interface>StokeGlobalInterface.CreateAdditiveVelocityField <Interface array>Fields

  • Calling this method will combine additively the ReflowField interfaces passed as array argument and will return a new ReflowField Interface with the resulting new velocity field.
<Interface>StokeGlobalInterface.CreateKrakatoaGenerator <node>Node JitterRadius:<float> IgnoreIDs:<bool>
JitterRadius default value: 0.0 IgnoreIDs default value: false
  • Calling this method will create a Particle Generator from a Particle source including Krakatoa PRT objects, Particle Flow, Thinking Particles or Legacy Particles, and will return a new ParticleGenerator Interface.
pg = StokeGlobalInterface.CreateKrakatoaGenerator $
<MixinInterface:ParticleGenerator>
showInterface pg
  Interface: ParticleGenerator
   Properties:
    .RandomSeed : integer : Read|Write
    .GeneratorRate : INT64 : Read|Write
    .DiffusionConstant : float : Read|Write
    .InitialVelocityField : Interface : Read|Write
    .IDAllocator : Interface : Read|Write
    .InitialLifespan : point2 by value : Read|Write
    .AvailableChannels : TSTR by value array : Read
   Methods:
    <void>UpdateToTime <time>Time
    <void>GenerateNextParticles <Interface>ParticleSet <float>TimeStepSeconds
   Actions:
OK
<Interface>StokeGlobalInterface.CreateGeometryGenerator <node>Node Mode:<string> VolumeSpacing:<float> SelectionType:<string> VertexJitterRadius:<float>
Mode default value: “Surface” VolumeSpacing default value: 10.0 SelectionType default value: “FaceSelection” VertexJitterRadius default value: 0.0
  • Calling this method will create a new Particle Generator from the specified geometry mesh and return a ParticleGenerator Interface.

<Interface>StokeGlobalInterface.CreateFumeFXGenerator <node>Node

  • Calling this method will create a new Particle Generator from the specified FumeFX grid and return a ParticleGenerator Interface.

<Interface>StokeGlobalInterface.CreateParticleSet <string array>ExtraChannels

  • Creates a new empty particle set with the standard channels, plus the channels specified.

<void>StokeGlobalInterface.AdvectParticleSet <Interface>ParticleSet <Interface>Advector <Interface>VelocityField <float>TimeStepSeconds

  • Advects all particles in a particle set, using the specified advection scheme and velocity field.

Arguments:

  • ParticleSet: The ParticleSet Interface instance to advect.
  • Advector: The instance of the Advector Interface that implements the advection scheme.
  • VelocityField: The instance of the ReflowField Interface that implements the velocity field affecting the particles.
  • timeStepSeconds: The time (in seconds) that the particles are affected by the velocity field.

<void>StokeGlobalInterface.UpdateAgeChannel <Interface>ParticleSet <float>TimeStepSeconds

<void>StokeGlobalInterface.UpdateAdvectionOffsetChannel <Interface>ParticleSet <Interface>Advector <Interface>VelocityField <float>TimeStepSeconds

<void>StokeGlobalInterface.ApplyAdvectionOffsetChannel <Interface>ParticleSet

<void>StokeGlobalInterface.MagmaEvaluateParticleSet <Interface>ParticleSet <maxObject>Magma <time>EvaluationTime <Interface>ErrorReporter

<void>StokeGlobalInterface.WriteParticleSet <Interface>ParticleSet <filename>FilePath

  • Saves a particle set to file.

Arguments:

  • ParticleSet: The IParticleSet instance to save to disk, cast as a FPInterface*.
  • FilePath: Path to file to save to disk

<void>StokeGlobalInterface.BeginRenderMode <node array>NodeList

  • Some 3ds Max objects have different viewport and render settings. This function (and its pair EndRenderMode) will set a collection of nodes and all of their dependencies to be in render mode.
  • NOTE: You MUST call EndRenderMode with the same node list to reverse the effects of this call. Failure to do so will cause undefined behavior.

Arguments:

  • NodeList: The list of nodes to put into render mode. All of the dependecies of these nodes will also be put into render mode.

<void>StokeGlobalInterface.EndRenderMode <node array>NodeList

  • The pair of ‘BeginRenderMode’, which reverts the changes.

Arguments:

  • NodeList: The list of nodes to exit render mode. This must be the same list as passed to ‘BeginRenderMode’.
<enum>StokeGlobalInterface.GetSourceType <node>GetSourceType
GetSourceType enums: {#invalid|#particles|#geometry|#fumefx}
  • Returns an enumeration describing the appropriate factory function from ReflowGlobal Interface to use when creating a particle generator from the specified source.

Arguments:

  • GetSourceType: The node to inspect.
<enum>StokeGlobalInterface.GetVelocityType <node>Node
GetVelocityType enums: {#invalid|#particles|#fumefx|#phoenix|#force|#field}

<enum>StokeGlobalInterface.SetTempDirectory <filepath>Directory

  • Sets the temporary directory used when writing particle files to a network location.
  • When writing to non-local storage locations, a particle file is first written to the temp directory then moved to the target destination. For local drives, the temporary file is written directly to the destination folder.
  • The argument is the path to the temporary directory to use. If undefined, the default directory will be used.
  • This allows you to set a faster storage medium for temporary files (e.g. an SSD drive) instead of writing to the default temp. directory (typically on the C: drive).
  • Because the PRT saving process is currently CPU-bound due to the compression algorithm used, this has little to no effect on the performance at this point.

<bool>StokeGlobalInterface.IsEmberField <node>Node

<Interface>StokeGlobalInterface.CreateMXSField <node>Node StackIndex:<integer>
StackIndex default value: 0
<void>StokeGlobalInterface.WriteFXDFile <string>FilePath <node>Node <point3>WSBoundsMin <point3>WSBoundsMax <float>Spacing StackIndex:<integer>
StackIndex default value: 0
<void>StokeGlobalInterface.WriteField3DFile <string>FilePath <node>Node <point3>WSBoundsMin <point3>WSBoundsMax <float>Spacing StackIndex:<integer>
StackIndex default value: 0
<void>StokeGlobalInterface.WriteOpenVDBFile <string>FilePath <node>Node <point3>WSBoundsMin <point3>WSBoundsMax <float>Spacing StackIndex:<integer>
StackIndex default value: 0