.. index:: Modeling Modifiers; Array (Legacy) Modifier
.. _bpy.types.ArrayModifier:

***********************
Array (Legacy) Modifier
***********************

The *Array* modifier creates an array of copies of the base object, with each copy being offset from
the previous one in any of a number of possible ways. Vertices in adjacent copies can be merged if they are nearby,
allowing smooth :doc:`Subdivision Surface </modeling/modifiers/generate/subdivision_surface>`
frameworks to be generated.

This modifier can be useful when combined with tileable meshes for quickly developing large scenes.
It is also useful for creating complex repetitive shapes.

Multiple Array modifiers may be active for an object at the same time
(e.g. to create complex three-dimensional constructs).


Options
=======

.. figure:: /images/modeling_modifiers_generate_array_panel.png
   :align: right
   :width: 300px

   The Array modifier.

Fit Type
   Controls how the length of the array is determined. There are three choices,
   activating respectively the display of the *Curve*, *Length* or *Count* settings explained below:

   Fit Curve
      Generates enough copies to fit within the length of the curve object specified in *Curve*.
   Fit Length
      Generates enough copies to fit within the fixed length given by *Length*.
   Fixed Count
      Generates the number of copies specified in *Count*.

.. note::

   - Both *Fit Curve* and *Fit Length* use the local coordinate system size of the base object, which means that
     scaling the base object in Object Mode will not change the number of copies generated by the modifier.
   - *Fit Curve* uses the local coordinate system length of the curve, which means that scaling the curve in
     Object Mode will not change the number of copies generated by the modifier.
   - :ref:`Applying <bpy.ops.object.transform_apply>` the scale can be useful for both.


Relative Offset
---------------

Factor X/Y/Z
   Adds a translation equal to the object's bounding box size along each axis, multiplied by a scaling factor,
   to the offset. X, Y and Z scaling factors can be specified.

   .. figure:: /images/modeling_modifiers_generate_array_offset-relative.png

      Relative offset (0.5, 1.0 and 1.5) examples.


Constant Offset
---------------

Distance X/Y/Z
   Adds a constant translation component to the duplicate object's offset.
   X, Y and Z constant components can be specified.


Object Offset
-------------

Adds a transformation taken from an object (relative to the current object) to the offset.
It is good practice to use an empty object centered or near to the initial object.
E.g. by rotating this empty a circle or helix of objects can be created.

.. figure:: /images/modeling_modifiers_generate_array_offset-object.png

   Object offset example.


Merge
-----

If enabled, vertices in each copy will be merged with vertices
in the next copy that are within the given *Distance*.

First and Last Copies
   If enabled **and** *Merge* is enabled, vertices in the first copy will be merged with vertices
   in the last copy, again if they are within *Distance* range. This is useful for circular objects.

   .. list-table:: First and Last Copies merge example.

      * - .. figure:: /images/modeling_modifiers_generate_array_first-last-off.png

             Subdivision discontinuity caused by not merging vertices between first and
             last copies (*First and Last Copies* off).

        - .. figure:: /images/modeling_modifiers_generate_array_first-last-on.png

             Subdivision discontinuity eliminated by merging vertices between first and
             last copies (*First and Last Copies* on).

Distance
   Controls the merge distance for *Merge* and *First and Last Copies*.


UVs
---

Offset U/V
   Shifts UVs of each new duplicate by a settable amount.


Caps
----

Cap Start, End
   This allows either endpoints of the array to have a different mesh subsisted.

   For the *start*: as if it was in position -1, i.e. one "array step" before the first "regular" array copy.
   For the *end*: as if it was in position *n* + 1, i.e. one "array step" after the last "regular" array copy.

   When *Merge* is activated, the *cap* vertices within the *Distance* threshold will be merged.

   .. note::

      The start/end cap objects currently do not support the *First and Last Copies* option.


Hints
=====

Offset Calculation
------------------

The transformation applied from one copy to the next is calculated as the sum of the three
different components (*Relative*, *Constant* and *Object*),
each of which can be enabled/disabled independently of the others. This allows, for example,
a relative offset of (1.0, 0.0, 0.0) and a constant offset of (0.1, 0.0, 0.0),
giving an array of objects neatly spaced along the X axis with a constant 0.1
unit between them, whatever the original object's size.


Examples
========

.. figure:: /images/modeling_modifiers_generate_array_example-mechanical-chain.png

   A chain created from a single link.
   `Sample blend-file <https://archive.blender.org/wiki/2015/index.php/File:Dev-ArrayModifier-Chain01.blend>`__.

.. figure:: /images/modeling_modifiers_generate_array_example-organic-tentacle.jpg

   A tentacle created with an Array Modifier followed by a Curve Modifier.

   The segment in the foreground is the base mesh for the tentacle; the tentacle is capped by two
   specially-modeled objects deformed by the same Curve object as the main part of the tentacle.
   `Sample blend-file <https://archive.blender.org/wiki/2015/index.php/File:Manual-Modifier-Array-Tentacle01.blend>`__.


Fractal
-------

.. list-table::

   * - .. figure:: /images/modeling_modifiers_generate_array_example-fractal-1.jpg
          :width: 320px

          Multi-level array animated with motion blur.

     - .. figure:: /images/modeling_modifiers_generate_array_example-fractal-2.png
          :width: 320px

          Fractal created with multiple arrays.
          `Sample blend-file <https://archive.blender.org/wiki/2015/index.php/File:Dev-ArrayModifier-Fractal01.blend>`__.
