c4d.modules.thinkingparticles.TP_MasterSystem

class c4d.modules.thinkingparticles.TP_MasterSystem
The master system is the main TP engine class.
There can only be one master system per document.

Parent Class:

Overview

TP_MasterSystem.AllocParticle

Allocates a particle.

TP_MasterSystem.AllocParticles

Allocates num particles and stores their particles IDs.

TP_MasterSystem.FreeParticle

Allocates num particles and stores their particles IDs.

TP_MasterSystem.FreeAllParticles

Frees all particles.

TP_MasterSystem.AllocParticleGroup

Allocates a new particle group.

TP_MasterSystem.FreeParticleGroup

Frees a particle group, removing it from the list.

TP_MasterSystem.SetPGroupHierarchy

Performs a hierarchy action on a particle group.

TP_MasterSystem.GetRootGroup

Returns the root group.

TP_MasterSystem.GetParticleGroups

Returns the particle groups in ingroup, specified by mode.

TP_MasterSystem.GetGroupParticleCount

Calculates the number of particles in the ingroup group.

TP_MasterSystem.GetParticles

Retrieve a list of all particles Id.

TP_MasterSystem.GetVirtualObjects

Creates the virtual object hierarchy for a particle group, i.e. an object group containing all particles. Used by the ParticleGeometry object.

TP_MasterSystem.GetGroupInfo

Retrieves the group information for a group.

TP_MasterSystem.GetGroupFromInfo

Retrieves a group from the information in info.

TP_MasterSystem.UpdateGroup

Updates a group at a given time difference since the last update.

TP_MasterSystem.NumParticles

Retrieves the number of allocated particles.

TP_MasterSystem.Alive

Retrieves the alive bit of a particle.

TP_MasterSystem.IsBorn

Retrieves the is-born bit of a particle.

TP_MasterSystem.IsDie

Retrieves the is-die bit of a particle.

TP_MasterSystem.EntersGroup

Retrieves the enters-group bit of a particle.

TP_MasterSystem.Group

Retrieves the group of a particle.

TP_MasterSystem.Position

Retrieves the position of a particle.

TP_MasterSystem.Velocity

Retrieves the velocity of a particle.

TP_MasterSystem.Mass

Retrieves the mass of a particle.

TP_MasterSystem.Spin

Retrieves the spin of a particle.

TP_MasterSystem.Size

Retrieves the size of a particle.

TP_MasterSystem.Scale

Retrieves the scale of a particle.

TP_MasterSystem.Age

Retrieves the age of a particle.

TP_MasterSystem.Life

Retrieves the lifetime of a particle.

TP_MasterSystem.Alignment

Retrieves the alignment matrix of a particle.

TP_MasterSystem.Randomseed

Retrieves the random seed of a particle.

TP_MasterSystem.Transform

Retrieves the transformation matrix of a particle.

TP_MasterSystem.Flags

Retrieves the transformation matrix of a particle.

TP_MasterSystem.DTFactor

Retrieves the delta time factor of a particle.

TP_MasterSystem.Color

Retrieves the color of a particle.

TP_MasterSystem.SetPosition

Retrieves the delta time factor of a particle.

TP_MasterSystem.SetVelocity

Sets the velocity for a particle.

TP_MasterSystem.SetMass

Sets the mass for a particle.

TP_MasterSystem.SetSpin

Sets the spin for a particle.

TP_MasterSystem.SetAge

Sets the age for a particle.

TP_MasterSystem.SetLife

Sets the age for a particle.

TP_MasterSystem.SetGroup

Inserts a particle into another group.

TP_MasterSystem.SetSize

Sets the size for a particle.

TP_MasterSystem.SetScale

Sets the size for a particle.

TP_MasterSystem.SetAlignment

Sets the alignment matrix for a particle.

TP_MasterSystem.SetRandomseed

Sets the alignment matrix for a particle.

TP_MasterSystem.SetCollision

Sets the collision handling information for a particle.

TP_MasterSystem.SetDTFactor

Sets the delta time factor for a particle.

TP_MasterSystem.SetColor

Sets the color for a particle.

TP_MasterSystem.SetPData

Sets the data channel value for a particle:

TP_MasterSystem.GetPData

Sets the data channel value for a particle:

TP_MasterSystem.AddDataChannel

Adds a new data channel.

TP_MasterSystem.RemoveDataChannel

Removes a data channel.

TP_MasterSystem.NumDataChannels

Retrieves the data channel count.

TP_MasterSystem.DataChannelType

Retrieves the data type of a data channel.

TP_MasterSystem.DataChannelName

Retrieves the name of a data channel.

TP_MasterSystem.DataChannelUniqueID

Retrieves a unique ID for a data channel that’s independent of its index.

TP_MasterSystem.DataChannelID

Retrieves the index of a data channel from its unique ID.

TP_MasterSystem.GetOperatorID

Retrieves an ID for op

TP_MasterSystem.GetDirty

A dirty counter for the master system.

TP_MasterSystem.SetDirty

Increments the dirty counter, i.e. tells anyone using GetDirty() that something has changed.

TP_MasterSystem.CheckCollision

Finds the node responsible for collision, the one that called SetCollision(),

Members

TP_MasterSystem.AllocParticle(self)

Allocates a particle.

Return type

int

Returns

The particle ID of the allocated particle, or NOTOK if the allocation failed.

TP_MasterSystem.AllocParticles(self, num)

Allocates num particles and stores their particles IDs.

Note

The count of allocated particles might be unequal to num due to the limit in the settings Max Particles.
Change it to increase the count of allocatable particles.
../../../../_images/tp_mastersystem_maxparticles.png
Parameters

num (int) – The number of particles to allocate.

Return type

List[int]

Returns

The list with the allocated particle IDs.

TP_MasterSystem.FreeParticle(self, pid)

Allocates num particles and stores their particles IDs.

Note

Normally this should not be used.
Instead you should use SetLife() with a negative time, so that the particle in question dies immediately.
Parameters

pid (int) – Particle ID of the particle to free. Particle ID.

Raises

IndexError – If pid is out of range : 0<=pid<NumParticles().

TP_MasterSystem.FreeAllParticles(self)

Frees all particles.

Note

Normally this should not be used.
Instead you should use SetLife() with a negative time, so that the particle in question dies immediately.
TP_MasterSystem.AllocParticleGroup(self)

Allocates a new particle group.

Warning

Must be freed with FreeParticleGroup(), or inserted into the list with SetPGroupHierarchy().

Return type

c4d.modules.thinkingparticles.TP_PGroup

Returns

The new particle group.

TP_MasterSystem.FreeParticleGroup(self, group)

Frees a particle group, removing it from the list.

Parameters

group (c4d.modules.thinkingparticles.TP_PGroup) – The group to free.

TP_MasterSystem.SetPGroupHierarchy(self, parent, group, mode)

Performs a hierarchy action on a particle group.

Parameters
  • parent (c4d.modules.thinkingparticles.TP_PGroup) – Parent parameter.

  • group (c4d.modules.thinkingparticles.TP_PGroup) – Group to act on.

  • mode (int) –

    Action:

    TP_INSERT_NONE

    Not used.

    TP_INSERT_UNDERFIRST

    Insert group as first child of parent.

    TP_INSERT_UNDERLAST

    Insert group as last child of parent.

    TP_INSERT_BEFORE

    Insert group before parent.

    TP_INSERT_AFTER

    Insert group after parent.

TP_MasterSystem.GetRootGroup(self)

Returns the root group.

../../../../_images/tp_mastersystem_rootgroup.png
Return type

c4d.modules.thinkingparticles.TP_PGroup

Returns

The root group.

TP_MasterSystem.GetParticleGroups(self, ingroup, mode, subgroups=True)

Returns the particle groups in ingroup, specified by mode.

Parameters
  • ingroup (c4d.modules.thinkingparticles.TP_PGroup) – In-group parameter.

  • mode (int) –

    Mode:

    TP_GETPGROUP_ALL

    All groups.

    TP_GETPGROUP_WITHPARTICLES

    Groups with particles.

    TP_GETPGROUP_SELECTED

    Selected groups.

  • subgroups (bool) – If this is True sub groups are included.

Return type

List[c4d.modules.thinkingparticles.TP_PGroup]

Returns

The root group.

TP_MasterSystem.GetGroupParticleCount(self, ingroup, subgroups=True)

Calculates the number of particles in the ingroup group.

Parameters
Return type

int

Returns

The number of particles.

TP_MasterSystem.GetParticles(self, all=False)

Retrieve a list of all particles Id.

Parameters

all (bool) – If True all particles added, otherwise only alive particle.

Returns

List[int]

Return type

A list with all particles ID.

TP_MasterSystem.GetVirtualObjects(self, ingroup, inRender=True, subgroups=True, hh=None)

Creates the virtual object hierarchy for a particle group, i.e. an object group containing all particles. Used by the ParticleGeometry object.

Parameters
  • ingroup (c4d.modules.thinkingparticles.TP_PGroup) – In-group parameter.

  • inRender (bool) – True if this is for rendering, otherwise the objects are built for the editor view.

  • subgroups (bool) – If this is True sub groups are included.

  • hh (Optional[object]) –

    A hierarchy helper for the operation.
    Usually passed through from a calling function, for example from ObjectData.GetVirtualObjects() or a Python generator main().

Return type

Optional[c4d.BaseObject]

Returns

Virtual object or None if there was an error.

TP_MasterSystem.GetGroupInfo(self, group)

Retrieves the group information for a group.

Parameters

group (c4d.modules.thinkingparticles.TP_PGroup) – Group to get the information for.

Return type

c4d.BaseContainer

Returns

The group information for the group.

TP_MasterSystem.GetGroupFromInfo(self, info)

Retrieves a group from the information in info.

Parameters

info (c4d.BaseContainer) – The information to search for.

Return type

Optional[c4d.modules.thinkingparticles.TP_PGroup]

Returns

The retrieved group or None if no group matched.

TP_MasterSystem.UpdateGroup(self, group, timeDelta)

Updates a group at a given time difference since the last update.

Note

Use a default timeDelta of 0 to update at the current time.

New in version R16.050.

Parameters
Return type

bool

Returns

True if the update was done successfully, otherwise False.

TP_MasterSystem.NumParticles(self)
Retrieves the number of allocated particles.
All particles IDs are less than this value.
Return type

int

Returns

Number of particles.

TP_MasterSystem.Alive(self, pid)

Retrieves the alive bit of a particle.

Parameters

pid (int) – Particle ID.

Raises

IndexError – If pid is out of range : 0<=pid<NumParticles().

Return type

bool

Returns

True if the particle is alive, otherwise False.

TP_MasterSystem.IsBorn(self, pid)

Retrieves the is-born bit of a particle.

Parameters

pid (int) – Particle ID.

Raises

IndexError – If pid is out of range : 0<=pid<NumParticles().

Return type

bool

Returns

True if the particle was just born, otherwise False.

TP_MasterSystem.IsDie(self, pid)

Retrieves the is-die bit of a particle.

Parameters

pid (int) – Particle ID.

Raises

IndexError – If pid is out of range : 0<=pid<NumParticles().

Return type

bool

Returns

True if the particle just died, otherwise False.

TP_MasterSystem.EntersGroup(self, pid)

Retrieves the enters-group bit of a particle.

Parameters

pid (int) – Particle ID.

Raises

IndexError – If pid is out of range : 0<=pid<NumParticles().

Return type

bool

Returns

True if the particle just entered a group, otherwise False.

TP_MasterSystem.Group(self, pid)

Retrieves the group of a particle.

Parameters

pid (int) – Particle ID.

Raises

IndexError – If pid is out of range : 0<=pid<NumParticles().

Return type

Optional[bool]

Returns

The group that the particle currently is in, otherwise None.

TP_MasterSystem.Position(self, pid)

Retrieves the position of a particle.

Parameters

pid (int) – Particle ID.

Raises

IndexError – If pid is out of range : 0<=pid<NumParticles().

Return type

c4d.Vector

Returns

Particle position.

TP_MasterSystem.Velocity(self, pid)

Retrieves the velocity of a particle.

Parameters

pid (int) – Particle ID.

Raises

IndexError – If pid is out of range : 0<=pid<NumParticles().

Return type

c4d.Vector

Returns

Particle velocity.

TP_MasterSystem.Mass(self, pid)

Retrieves the mass of a particle.

Parameters

pid (int) – Particle ID.

Raises

IndexError – If pid is out of range : 0<=pid<NumParticles().

Return type

float

Returns

Particle mass.

TP_MasterSystem.Spin(self, pid)

Retrieves the spin of a particle.

Parameters

pid (int) – Particle ID.

Raises

IndexError – If pid is out of range : 0<=pid<NumParticles().

Return type

float

Returns

Particle spin.

TP_MasterSystem.Size(self, pid)

Retrieves the size of a particle.

Parameters

pid (int) – Particle ID.

Raises

IndexError – If pid is out of range : 0<=pid<NumParticles().

Return type

float

Returns

Particle size.

TP_MasterSystem.Scale(self, pid)

Retrieves the scale of a particle.

Parameters

pid (int) – Particle ID.

Raises

IndexError – If pid is out of range : 0<=pid<NumParticles().

Return type

c4d.Vector

Returns

Particle scale.

TP_MasterSystem.Age(self, pid)

Retrieves the age of a particle.

Parameters

pid (int) – Particle ID.

Raises

IndexError – If pid is out of range : 0<=pid<NumParticles().

Return type

c4d.BaseTime

Returns

Particle age.

TP_MasterSystem.Life(self, pid)

Retrieves the lifetime of a particle.

Parameters

pid (int) – Particle ID.

Raises

IndexError – If pid is out of range : 0<=pid<NumParticles().

Return type

c4d.BaseTime

Returns

Particle lifetime.

TP_MasterSystem.Alignment(self, pid)

Retrieves the alignment matrix of a particle.

Parameters

pid (int) – Particle ID.

Raises

IndexError – If pid is out of range : 0<=pid<NumParticles().

Return type

c4d.Matrix

Returns

Particle alignment matrix.

TP_MasterSystem.Randomseed(self, pid)

Retrieves the random seed of a particle.

Parameters

pid (int) – Particle ID.

Raises

IndexError – If pid is out of range : 0<=pid<NumParticles().

Return type

c4d.Matrix

Returns

Particle random seed.

TP_MasterSystem.Transform(self, pid)

Retrieves the transformation matrix of a particle.

Parameters

pid (int) – Particle ID.

Raises

IndexError – If pid is out of range : 0<=pid<NumParticles().

Return type

c4d.Matrix

Returns

Particle transformation matrix.

TP_MasterSystem.Flags(self, pid)

Retrieves the transformation matrix of a particle.

Note

These are private. Use the functions like Alive() instead.

Parameters

pid (int) – Particle ID.

Raises

IndexError – If pid is out of range : 0<=pid<NumParticles().

Return type

c4d.Matrix

Returns

Particle flags.

TP_MasterSystem.DTFactor(self, pid)

Retrieves the delta time factor of a particle.

Parameters

pid (int) – Particle ID.

Raises

IndexError – If pid is out of range : 0<=pid<NumParticles().

Return type

float

Returns

Particle flags.

TP_MasterSystem.Color(self, pid)

Retrieves the color of a particle.

New in version R16.038.

Parameters

pid (int) – Particle ID.

Raises

IndexError – If pid is out of range : 0<=pid<NumParticles().

Return type

c4d.Vector

Returns

Particle color.

TP_MasterSystem.SetPosition(self, pid, p)

Retrieves the delta time factor of a particle.

Parameters
  • pid (int) – Particle ID.

  • p (c4d.Vector) – New particle position.

Raises

IndexError – If pid is out of range : 0<=pid<NumParticles().

TP_MasterSystem.SetVelocity(self, pid, p)

Sets the velocity for a particle.

Parameters
  • pid (int) – Particle ID.

  • p (c4d.Vector) – New particle velocity.

Raises

IndexError – If pid is out of range : 0<=pid<NumParticles().

TP_MasterSystem.SetMass(self, pid, mass)

Sets the mass for a particle.

Parameters
  • pid (int) – Particle ID.

  • mass (float) – New particle velocity.

Raises

IndexError – If pid is out of range : 0<=pid<NumParticles().

TP_MasterSystem.SetSpin(self, pid, axis, speed)

Sets the spin for a particle.

Parameters
  • pid (int) – Particle ID.

  • axis (c4d.Vector) – Rotation axis.

  • speed (float) – Rotation speed

Raises

IndexError – If pid is out of range : 0<=pid<NumParticles().

TP_MasterSystem.SetAge(self, pid, age)

Sets the age for a particle.

Parameters
  • pid (int) – Particle ID.

  • age (c4d.BaseTime) – New particle age.

Raises

IndexError – If pid is out of range : 0<=pid<NumParticles().

TP_MasterSystem.SetLife(self, pid, life)

Sets the age for a particle.

Parameters
  • pid (int) – Particle ID.

  • life (c4d.BaseTime) – New particle lifetime.

Raises

IndexError – If pid is out of range : 0<=pid<NumParticles().

TP_MasterSystem.SetGroup(self, pid, group)

Inserts a particle into another group.

Parameters
Raises

IndexError – If pid is out of range : 0<=pid<NumParticles().

TP_MasterSystem.SetSize(self, pid, size)

Sets the size for a particle.

Parameters
  • pid (int) – Particle ID.

  • size (float) – New particle size.

Raises

IndexError – If pid is out of range : 0<=pid<NumParticles().

TP_MasterSystem.SetScale(self, pid, scale)

Sets the size for a particle.

Parameters
  • pid (int) – Particle ID.

  • scale (c4d.Vector) – New particle scale.

Raises

IndexError – If pid is out of range : 0<=pid<NumParticles().

TP_MasterSystem.SetAlignment(self, pid, align)

Sets the alignment matrix for a particle.

Parameters
  • pid (int) – Particle ID.

  • align (c4d.Matrix) – New particle alignment matrix.

Raises

IndexError – If pid is out of range : 0<=pid<NumParticles().

TP_MasterSystem.SetRandomseed(self, pid, seed)

Sets the alignment matrix for a particle.

Parameters
  • pid (int) – Particle ID.

  • seed (int) – New particle random seed.

Raises

IndexError – If pid is out of range : 0<=pid<NumParticles().

TP_MasterSystem.SetCollision(self, pid, collision)

Sets the collision handling information for a particle.

Parameters
  • pid (int) – Particle ID.

  • collision (int) – Collision ID. This is GetOperatorID() for the node responsible for the collision handling.

Raises

IndexError – If pid is out of range : 0<=pid<NumParticles().

TP_MasterSystem.SetDTFactor(self, pid, dt)

Sets the delta time factor for a particle.

Parameters
  • pid (int) – Particle ID.

  • dt (float) – New particle delta time factor.

Raises

IndexError – If pid is out of range : 0<=pid<NumParticles().

TP_MasterSystem.SetColor(self, pid, color)

Sets the color for a particle.

New in version R16.038.

Parameters
  • pid (int) – Particle ID.

  • color (c4d.Vector) – New particle color.

Raises

IndexError – If pid is out of range : 0<=pid<NumParticles().

TP_MasterSystem.SetPData(self, pid, chan, value)

Sets the data channel value for a particle:

pid = 1
chan = 0
ms.SetPData(pid, chan, "Hello World!")
Parameters
Raises
Return type

bool

Returns

True on success, otherwise False.

TP_MasterSystem.GetPData(self, pid, chan)

Sets the data channel value for a particle:

pid = 1
chan = 0
value = ms.GetPData(pid, chan, "Hello World!")
Parameters
  • pid (int) – Particle ID.

  • chan (int) – Channel index.

Raises
Return type

Any

Returns

Depends on the type of the channel.

TP_MasterSystem.AddDataChannel(self, type, str)

Adds a new data channel.

Parameters
  • type (int) – Channel data type.

  • str (str) – Channel

Return type

bool

Returns

True if successful, otherwise False.

TP_MasterSystem.RemoveDataChannel(self, chan)

Removes a data channel.

Parameters

chan (int) – Channel index.

Raises

IndexError – If chan is out of range : 0<=chan<NumDataChannels().

Return type

bool

Returns

True if successful, otherwise False.

TP_MasterSystem.NumDataChannels(self)

Retrieves the data channel count.

Return type

int

Returns

Number of data.

TP_MasterSystem.DataChannelType(self, chan)

Retrieves the data type of a data channel.

Parameters

chan (int) – Channel index.

Raises

IndexError – If chan is out of range : 0<=chan<NumDataChannels().

Return type

int

Returns

Data type of channel chan.

TP_MasterSystem.DataChannelName(self, chan)

Retrieves the name of a data channel.

Parameters

chan (int) – Channel index.

Raises

IndexError – If chan is out of range : 0<=chan<NumDataChannels().

Return type

str

Returns

Number of data.

TP_MasterSystem.DataChannelUniqueID(self, chan)

Retrieves a unique ID for a data channel that’s independent of its index.

Parameters

chan (int) – Channel index.

Raises

IndexError – If chan is out of range : 0<=chan<NumDataChannels().

Return type

int

Returns

Unique ID of channel chan.

TP_MasterSystem.DataChannelID(self, unique_id)

Retrieves the index of a data channel from its unique ID.

Parameters

unique_id (int) – Channel ID.

Return type

int

Returns

Data channel index.

TP_MasterSystem.GetOperatorID(self, op)

Retrieves an ID for op

Parameters

op (c4d.modules.graphview.GvNode) – A node.

Return type

int

Returns

ID for op.

TP_MasterSystem.GetDirty(self)
A dirty counter for the master system.
This can be used to see if anything has changed. Use SetDirty() to increment the counter.
Return type

int

Returns

Dirty counter. Is incremented when something changes in the system.

TP_MasterSystem.SetDirty(self)

Increments the dirty counter, i.e. tells anyone using GetDirty() that something has changed.

Note

This has to be used whenever an operator affects particle shapes, like the ObjectShape operator does.

TP_MasterSystem.CheckCollision(self, collision, pid, t, pos, vel, dt)

Finds the node responsible for collision, the one that called SetCollision(), and tells it to evaluate the passed collision parameters.

Note

Normally Thinking Particles evaluates this function automatically for registered collisions.

Parameters
  • collision (int) – The collision ID. This is GetOperatorID() for the node responsible for the collision.

  • pid (int) – The particle ID: 0 <= pid < NumParticles()

  • t (float) –

    Time to evaluate the collision at.
    Collisions are detected between t - dt and t.

  • pos (c4d.Vector) – Assigned the new position of the object if there is a collision.

  • vel (c4d.Vector) – Assigned the new velocity of the object if there is a collision.

  • dt (float) – The time since the last evaluation, i.e. the time to look backwards for collisions.

Return type

Tuple[bool, Dict[“axis”: c4d.Vector, “speed”: float], float]

Returns

A tuple filled in this order:

  • True if there was a collision, otherwise False.

  • dict with the next entries:

    • ”axis”: Rotation axis.

    • ”speed”: Rotation speed.

  • The collision time, if there was a collision. This is generally less than t.