The X-Particles Console
The emitter head-up display (HUD) allows 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 allows 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.
- Selecting an emitter
- Selecting data to display
- Displayed data
- Custom data values
- Minimum and maximum values
- Data items - reference
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'.
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).
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.
Note that the following preferences can also be set permanently in the main X-Particles preferences:
- Text Color
- Decimal Places
- Show Color
- Time Units
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:
No filtering; the data from all particles is shown.
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.
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.
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:
The particle ID value to show data for when the filter is set to 'Single Particle'.
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'.
A text field for the list of particles to show when the filter is set to 'Particle List'.
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).
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.
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.
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.
This drop-down menu is used to control how particle colours are shown in the data grid. There are several options:
The particle colour is shown as a coloured bar like this:
Colours are shown in RGB format ranging from 0 to 255. Each component is shown separately:
As for 'RGB 0...255' but the colours are in the range 0 to 1.
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:
|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.|
|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.|
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.
|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.