.. index:: Modeling Modifiers; Particle Instance Modifier
.. _bpy.types.ParticleInstanceModifier:

**************************
Particle Instance Modifier
**************************

When a Particle Instance modifier is added to an object,
the mesh of this object will be duplicated
at the location of the particles of the selected particle system from another target object.
This means that to use this modifier, you must have at least one other object
that has a :doc:`Particles System </physics/particles/index>` on it.

Because of the correlation in which the Particle Instance modifier is
influenced by the underlying particle systems on other objects, some of the apparent effects
generated by the modifier can look and act vastly different,
depending on the underlying settings of the particle systems it is associated with.
This is worth taking account of, when it seems that the Particle Instance modifier settings
do not return the expected results.


Options
=======

.. figure:: /images/modeling_modifiers_physics_particle-instance_panel.png
   :align: right
   :width: 300px

   The Particle Instance modifier.

Object
   The target object which has a particle system associated with it.

Particle System
   Which particle system from the target *Object* to apply this modifier to.

Create Instances
   Regular
      When enabled, the modifier will use the regular (parents) particles
      to duplicate the mesh of the modified object.
   Children
      When enabled, the modifier will use the :doc:`children </physics/particles/emitter/children>` particles
      to duplicate the mesh of the modified object.
   Size
      Scale the instanced copies of the mesh by the particle size attribute.
      When this is disabled, all the copies appear the same size as the origin.

      See the particle system's :doc:`Render </physics/particles/emitter/render>`
      and :doc:`Children </physics/particles/emitter/children>` panels for particle's size options.

Show
   Unborn
      When enabled, the modifier will use the unborn particles
      to duplicate the mesh of the modified object.
   Alive
      When enabled, the modifier will use the alive particles
      to duplicate the mesh of the modified object.
   Dead
      When enabled, the modifier will use the dead particles
      to duplicate the mesh of the modified object.

Amount
   The proportion of particles to be used.
   Allows you to **randomly** skip particles to adjust the amount of instances.

   .. warning::

      The random algorithm used currently only ensures that relative amount to be respected *statistically*.
      The actual amount of instances generated will differ from the theoretical one,
      depending on the *Seed* value of the target particle system (and the *Offset* value described below, too).

      That deviation is not significant with high number of particles,
      but it will be highly noticeable with low numbers
      (e.g. with 100 particles in the target system, and an *Amount* value of ``0.1``,
      it can generate either up to 15 or 5 instances, instead of the 10 expected).

Offset
   A relative offset in the range of particles used for instantiation.
   Allows you to avoid overlapping of the used particles,
   when the same particle system is used in multiple modifier instances.

   .. tip::

      If you want to fully avoid overlaps, your *Offset* value must be at least as high as your *Amount* value.

Coordinate Space
   World, Local
      Use :term:`World Space`, or :term:`Local Space` of the target object (that the particle system is assigned to).

      - World space means that the locations of the copies of the modified mesh will depend
        on the location of the modified object **and** of the target object.
      - Local space means that the locations of the copies of the modified mesh will depend
        only on the location of the modified object.

Axis
   Specify which axis of the modified object to use as pole axis to apply
   the rotation from the instantiated particles.


Create Along Paths
------------------

By default, the instances are placed depending on the particles position in the current frame.
By enabling *Create Along Paths*, the instance of the modified object follows
deforms its shape along the particle path (or the hair strand).
This allows you to select the position along the particles path regardless of the current frame.

.. tip::

   You can adjust the particles' path (using the *Path* visualization type)
   on the :doc:`Render </physics/particles/emitter/render>` panel of the *Particle System* tab.

.. note::

   The particle system must be :doc:`baked </physics/baking>`, except for *Hair* type or *Keyed* physics.

Position
   Specify what percentage of the path that the instance fills,
   or the position on the path if the *Keep Shape* option is enabled.
Random
   Adds randomness to the *Position* value of each instance.

Rotation
   Specifies the rotation around the path.
Random
   Adds randomness to the *Rotation* value of each instance.

Keep Shape
   Enabling this prevents the instance from being deformed,
   and places it on the path according to the *Position* value.


Layers
------

With these fields you can select the Color Attribute,
which will be filled with colors based on the particles information.
These Color Attributes can be used, for example, in a shader to add variance to a material.

Index
   A Color Attribute for values based on the particles index.
Value
   A Color Attribute for random per-particle values.


Examples
========

.. figure:: /images/modeling_modifiers_physics_particle-instance_split-plane.jpg
   :align: center

   Particle Instance modifier example.

The render above shows a single plane mesh object assigned to two different vertex groups
and each of those vertex groups is assigned to a separate and independent particle system,
with each particle system being assigned to a different Particle Instance modifier.
In the case shown the Particle Instance modifiers are added to a sphere and a cube.
See `example blend-file
<https://archive.blender.org/wiki/2015/uploads/4/48/Manual_-_Modifiers_-_Particle_Instance_Modifiers_-_Split_Plane.blend>`__.

.. figure:: /images/modeling_modifiers_physics_particle-instance_create-along-paths.jpg
   :align: center

   Create Along Path example.

In this example, a single *Keyed* particle travels through four points (green planes),
on an elliptical path. The Particle Instance modifier is added to a cylinder object
and then associated with that *Keyed* particle system.

When the *Create Along Paths* is activated,
instead of the cylinder location just following the position of the particle,
the cylinder mesh is fitted to the shape of the path followed by the particle.
The mesh geometry of the object which is deformed
can have an impact on how well the deformation is carried out.
In the case of the cylinder, it has many loop cuts along its length so
that it can bend at those points to deform along the particle path.

The Particle Instance modifier *Create Along Paths* option works for hair (strand) particles
as well as with keyed particles. In this case, the mesh of the modifier will follow
the length and profile of the hair strands paths.

.. note::

   Strands, when they are generated, instantly die when created, so for the *Create Along Paths* checkbox
   to be of any use, you must also have the *Dead* checkbox enabled.
