The X-Particles Console

The emitter head-up display (HUD) enables the display of certain particle data. However, only one data item can be seen at a time, from a limited subset of the available data, and even a relatively small number of particles can hugely slow down the viewport playback.

The X-Particles Console enables you to see several data items at once for one, several, or all particles. It is extremely fast and will not slow down the viewport even with large particle numbers.

Getting help

Context-sensitive help is not available for this object. You can open this help page from the object itself by opening the 'Help' menu and choosing 'Online Help'.

Interface

The console's interface initially looks like this:

At the top of the window there are two tabs. The data is shown in the 'Particle Data' tab. By default this is empty since no emitter has been provided and only the two default data items - the particle ID number (PID) and particle age are shown.

Selecting an emitter

To display any particle data you first need to select an emitter. You can do this by dragging an emitter from the object manager into the 'Emitter' link field. Alternatively, if an emitter is selected in the object manager, you can click the 'Get Active Emitter' button and the console will find the selected emitter and set the link for you.

If you have more than one emitter in the scene, then selecting a different emitter in the object manager will automatically change the linked emitter to the newly selected one. This isn't always desirable, so if the 'Lock Emitter' switch is checked, changing the selected emitter in the object manager will have no effect. This switch is on by default.

Note that the 'Lock Emitter' switch does not prevent you from dragging in a new emitter or from using the 'Get Active Emitter' button. It only prevents changes caused by choosing another emitter in the object manager.

Selecting data to display

You can customise the data to show on the 'Options' tab, which looks like this:

To show the data, drag an emitter into the 'Emitter' field and play a few frames. The window then might look like this:

You can see each data item displayed on a single line for each particle. Note that the PID is the same number you would see in the HUD if you turned on the 'Show Particle Index' switch in the emitter's 'Display' tab.

Be aware that during playback the display may not be updated and you only see changes in the displayed data once you pause or stop the playback. This depends on the 'Update' option setting (see below).

Displayed Data

There are two ways to change the data to be displayed.

The Options tab

There are several rows of checkboxes which are the data items to display. For example, the above screenshot shows the data selected to be the particle ID number (PID), Position, Age, and Speed. The options tab would then look like this:

The meaning of these data items is listed below. You can use the 'Show All' button to display all the data items, or 'Hide All' to show none of them.

Note that if you change the data to display using the Options tab you MUST click the button 'Update Grid' to activate those changes in the particle data display.

The Data to Display menu

This is found at the top left of the window. You can turn the various options on or off in the menu. For the example shown above the menu would look like this:

If you use the menu the grid is automatically updated and there's no need to click the 'Update Grid' button.

It is more convenient to use the menu to show or hide individual data items but easier to use the Options tab if you have several data items to change at once.

Custom Data Values

As well as the 'standard' particle data, you can display any custom data you may have added in the emitter (see the emitter Extended Data tab page for details of adding custom data).

The console can show up to two of your custom data items (you may have added more, but only two can be shown in the console). Displaying custom data is simple: turn on the Custom Data 1 and/or Custom Data 2 switch then enter the ID number and name of the custom data into the corresponding 'ID' and 'Name' fields in this section.

For details of how to use the ID and name parameters to identify custom data, see the Custom Data page.

Note that the console can display all custom data types except the matrix type. If your custom data is a matrix, you will only see the string '[Matrix]' in the console.

Preferences

Note that the following preferences can also be set permanently in the main X-Particles preferences:

  • Text Color
  • Decimal Places
  • Show Color
  • Time Units

Text Color

The colour to use in the particle data display. Only used for the actual particle data items.

Filter Particles By

By default, the console displays the data for all particles. This is the case when this drop-down menu is set to 'None'. The menu options are:

None

No filtering; the data from all particles is shown.

Single Particle

The data for one single particle is shown. The particle is selected by entering its particle ID number in the 'Particle ID' field. If that particle does not exist - that is, it hasn't been created yet, or it has been killed - no data will be shown in the display.

Number of Particles

The console will display the data for the number of particles given in the 'Max. Particles' field (this is the 'Particle ID' field renamed).

Note that if you enter (for example) '10' in this field, data from the first 10 particles in the particle array will be shown. If any of those first 10 particles die, they will be replaced by another particle, if one is generated. If no more particles are generated, the remaining particles close up to fill the gap. So in this mode you may see the list of particle IDs change, if particles are being deleted.

Particle Range

In this mode the particles whose ID numbers fall in the range specified by the 'Range Min.' and 'Range Max.' fields ('Range Min.' is the renamed 'Particle ID' field).

In this mode if any particles are deleted they will not be replaced in the data display unless there are more particles whose ID numbers fall in the given range.

Particle List

Suppose you want to compare results from three specific particles - those with ID values of 3, 56, and 1028. Having to scroll up and down a long list is not very helpful, so instead you can enter a list of particles so that data from only the ones you specify are shown.

To do this, enter the list into the 'Particle List' text field. The list must consist of a list of particle ID numbers separated by commas. The separator MUST be a comma - no other character will do.

For the above example, the list would look like this:

Particle ID

The particle ID value to show data for when the filter is set to 'Single Particle'.

Max. Particles

The maximum number of particles to show data for when the filter is set to 'Number of Particles'.

Range Min., Range Max.

The range of particles to display, using their ID numbers, when the filter is set to 'Particle Range'.

Particle List

A text field for the list of particles to show when the filter is set to 'Particle List'.

Decimal Places

The number of decimal places to show in the data grid for each item. The Cinema 4D default value is three, but this is often unnecessary. In the X-Particles Console the default value is two. You can change this to between zero and three (Cinema 4D cannot show more than three decimal places).

Update

This drop-down menu controls when the grid is updated with the particle data. There are two options:

On Animation Stop

This is the default setting. In this mode, the console will not be updated during an animation until you stop playback. Then it will be updated. This is faster than updating the console each frame, so will not slow the playback.

Each Frame

With this option the console is updated each frame. While more convenient, it will take longer and may slow the playback if a lot of data needs to be refreshed.

Time Units

For 'Age' and 'Lifespan' data items, the result can be displayed either as frames or seconds. You can change between them by using this menu.

Show Color

This drop-down menu is used to control how particle colours are shown in the data grid. There are several options:

As Color

The particle colour is shown as a coloured bar like this:

RGB 0...255

Colours are shown in RGB format ranging from 0 to 255. Each component is shown separately:

RGB 0...1

As for 'RGB 0...255' but the colours are in the range 0 to 1.

HSV

As for the RGB options but in hue/saturation/value format.

Note that once again, if you change any of these options you must click the button 'Update Grid' to activate the changes in the particle data display.

Minimum and maximum values

Sometimes, you need to see the lowest and highest values of a particular data item. It's not practical to scroll through a long list trying to pick these out, so the console can do it for you. Simply double-click anywhere in the relevant column or on the column header, and a small box will appear like this:

Note that these are the values for all particles from the linked emitter, not just the ones shown in the data grid.

Minimum and maximum values are available for all data items with these exceptions:

  • Spin Enabled (as this is a simple boolean)
  • Colour, when the colour is shown as a colour bar
  • For custom data, only integers, floating point numbers and time values

Data items - reference

These are the various data items you can display:

Name Data type Comment
PID Integer The particle's ID number. It is recommended that you always show this data item.
Position Vector The particle's position in the 3D world.
Velocity Vector The velocity comprises particle direction and speed in one vector; the magnitude of the vector is the speed. You can opt to normalise the vector, in which case only the direction is shown.
Rotation Vector The particle's rotation in HPB format. By default it is [0,0,0] if particle rotation is not enabled.
Spin Vector The particle's spin, that is, by how much it rotates each frame. By default it is [0,0,0] if particle rotation is not enabled.
Age Float/Integer Particle age in either seconds or frames (depending on the setting in the preferences).
Lifespan Float/Integer Particle lifespan in either seconds or frames (depending on the setting in the preferences).
Editor Display Integer A value representing the editor display of the particle. All possible values are shown in the file oxparticle.h in the 'res/description' folder.
Color Vector The particle colour.
Radius Float Particle radius in scene units.
Speed Float Particle speed in scene units per second. Note that this is the same as the magnitude of the Velocity vector.
Group ID Integer The group the particle belongs to. If the particle does not belong to any specific group, or if there are no groups in the scene, this value is zero.
Mass Float Particle mass.
Distance Float The distance in scene units the particle has travelled since birth.
Spin Enabled Boolean Not currently used. This is an internal flag which has no meaning in this context.
Density Float The particle density (only used when the SPH Fluid object is affecting the particle).
Temperature Float Particle temperature value.
Fuel Float Particle fuel value.
Fire Float Particle fire value.
Smoke Float Particle smoke value.
Expansion Float Particle expansion value (used by the X-Particles Domain object).
UVW Vector Particle UVW value. Only used when emitting from an object with UVs.
Vertex Integer Used by the X-Particles Particle Deformer. This value is the vertex assigned to each particle. Its value is -1 unless emitting from an object's vertices and the switch 'One Particle Per Source Element' is enabled.
Vertex Weight Float Used by the X-Particles Particle Deformer. This value is the vertex weight of the vertex assigned to each particle. It will always show the value 1 unless a vertex map has been applied to the object and the tag dragged into the 'Selection' field in the emitter's object tab.
Custom Data 1 Various These are custom data values added in the emitter's Extended Data tab and perhaps subsequently altered by a Custom Data modifier or action.
Custom Data 2 Various A second custom data item.
Flags Bit field The internal flags used by the emitter and other objects to control the particle behaviour. There are 32 flags and all 32 are displayed. For their meaning, see the separate table below.
Fluid Density Float The fluid density at the particle location. It requires a PBD Fluid object in the scene.
Fluid Surface Float How close to the surface of a fluid a particle is. Note that this is not an actual distance setting. Higher values indicate that the particle is close to the surface. It requires a Fluid FX object in the scene.
Granular Integer The 'granularity' of a particle, which is directly related to the number of neighbouring particles. Granularity levels are therefore lower nearer the edges of the fluid since the number of neighbours is lower. It requires a Fluid FX object in the scene.

 

Particle flags

Each particle can have up to 32 possible flags. These are shown in the console like this:

(Only some flags are shown here for reasons of space.) If a flag is set, an asterisk (*) is displayed; if not, the flag is clear.

The meaning of the various flags is shown in the table below. Note that not all are useful in this context but are shown anyway for completeness. Those whose value is not applicable or cannot be seen in the console are shown in italics.

Flag number Name Meaning
F0 XPARTICLE_FLAGS_TRAIL If set, trails are enabled for this particle. The particle doesn't necessarily have a trail, but it can do so. If the flag is clear, trails will not be present on the particle. The flag is set by default but is cleared by the Change Trails action when set to 'Don't Generate Trail'.
F1 XPARTICLE_FLAGS_USEGRAD Only set if the particle colour is set to 'Gradient (Parameter)'. This can be done in the emitter or in the group the particle belongs to. Otherwise, the flag is clear.
F2 XPARTICLE_FLAGS_FREEZE Set if particle movement is frozen by a freeze action or modifier. See also flags F9 and F10.
F3 XPARTICLE_FLAGS_STICK This flag is set by the Cover/Target modifier when the particle has been assigned a target position to stick to on an object. The flag is cleared when the particle has stuck to the target. See also flags F4 and F14.
F4 XPARTICLE_FLAGS_ISSTUCK Set when a particle has stuck to the target position assigned by a Cover/Target modifier. Flag F3 will then be cleared.
F5 XPARTICLE_FLAGS_COLLIDED* Set when a particle has just collided with an object. However, the flag is cleared after any internal processing so in the console it will always show as clear.
F6 XPARTICLE_FLAGS_STICKSOURCE Set when the switch 'Stick Particle to Source Object' in the emitter is turned on.
F7 XPARTICLE_FLAGS_SCALED Set when a particle has been scaled by a Mograph effector (but not by a Scale or other modifier).
F8 XPARTICLE_FLAGS_RESAMPLE Set when the particle's group changes and the particle colour must be resampled (e.g. when the colour is obtained from a gradient or shader).
F9 XPARTICLE_FLAGS_FREEZE_SPIN As for flag F2 but spin is frozen.
F10 XPARTICLE_FLAGS_FREEZE_SCALE As for flag F2 but scale is frozen.
F11 XPARTICLE_FLAGS_TP_DISCON When the emitter is set to generate Thinking Particles and then an UnlinkTP modifier or action disconnects the X-Particle from the Thinking Particle, this flag is set.
F12 XPARTICLE_FLAGS_ROTATED As for flag F7 but when the particle has been rotated by the effector. Note that rotations must be enabled in the emitter for the effector to rotate particles and therefore set this flag.
F13 XPARTICLE_FLAGS_DONESPAWN Set if the 'Spawn Once Only' is set in a Spawn modifier and the modifier has caused the particle to spawn. It prevents the modifier from spawning from any particle in which this flag is set.
F14 XPARTICLE_FLAGS_DOSTICK If set, a Cover/Target modifier will stick a particle to a target position on an object. It is always set if the modifier is in Cover mode but is always clear if it is in Target mode (since particles do not stick to the object in that mode).
F15 XPARTICLE_FLAGS_ALIVE* Set if a particle is alive. This will always be set in the console since dead particles which have not yet been removed from the particle array are not shown.
F16 XPARTICLE_FLAGS_BORN* Set when a particle has been newly created then cleared once it has been initialised. For this reason the console will never show this flag set.
F17 XPARTICLE_FLAGS_DIE* Set when a particle is about to be removed. The flag is set then the particle is deleted, so the console will never show this flag set.
F18 XPARTICLE_FLAGS_GROUP_CHANGED* Set when a particle's group has been changed, then cleared once internal processing has been carried out. For this reason the console will never show this flag set.
F19 XPARTICLE_FLAGS_NEW* Same as for flag F16.
F20 XPARTICLE_FLAGS_NOSTUCKACTION If set, a particle stuck to an object by a Cover/Target modifier will only carry out actions specified by the modifier when stuck once. The flag is set if the 'Repeat Actions' parameter in the modifier is set to 'No Repeat'.
F21 XPARTICLE_FLAGS_INVISIBLE If set, the particle is not visible in the viewport. The flag is set by the Change Emitter action with 'Visibility' set to 'Invisible'.
F22 XPARTICLE_FLAGS_SKIP_FINAL* Internal use only, not useful in this context.
F23 XPARTICLE_FLAGS_VOXEL* Used by the X-Particles material when rendering volumetrics. Not useful in this context.
F24 XPARTICLE_FLAGS_PPCOLLISION* As for flag F5 but for particle-particle collisions.
F25 XPARTICLE_FLAGS_PPOLYCOLLISION* As for flag F5 but for particle-particle collisions.
F26 XPARTICLE_FLAGS_POLY_PRIMECOLLISION* As for flag F5.
F27 XPARTICLE_FLAGS_PP_PRIMECOLLISION* As for flag F5 but for particle-particle collisions.
F28 XPARTICLE_FLAGS_DEFORMED As for flags F7 and F12 but for the particle position.
F29 XPARTICLE_FLAGS_STREAMER Set by the Tendril modifier when a streamed particle is generated. This flag is tested, for example, by the Trail object to determine if trails should be created for streamed particles.
F30 XPARTICLE_FLAGS_MARKED_DIE* As for flag F17.
F31 XPARTICLE_FLAGS_FILL* Set by the emitter if a particle is a Fill particle used in the X-Particles material. Since these particles are only generated at render time, this flag will never be set in the console.

Flags marked with '*' are not useful in the console either because they have no meaning outside of the emitter or some other object, or because their values will either be shown as set or always clear. They are included anyway for completeness.