# Place On Surface

{% embed url="<https://youtu.be/CVNpI5NYRII>" %}

Use this as both a creative tool for building scenes, as well as an animation behavior to dynamically place objects. More than just working with terrains, objects may also be placed on colliders of all types using raycasts. &#x20;

{% hint style="success" %}
To add Place On Surface, right-click an object in the Timeflow view and select:

#### Add Automation > Place On Surface

{% endhint %}

<figure><img src="https://2067910529-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FC3dOuetlQfYgK5FPUKgn%2Fuploads%2F6jqy3QZaBEr8dnoDlpFh%2Fimage.png?alt=media&#x26;token=3156c6e6-7743-4ac3-9a09-ca13ca83f2cf" alt=""><figcaption></figcaption></figure>

Place On Surface has two read-only channels, one for the final placed position and another for rotation. The latter is optional and may be hidden if not in use.

## Place On Surface Editor

Select the object to view its settings in the Inspector.

<figure><img src="https://2067910529-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FC3dOuetlQfYgK5FPUKgn%2Fuploads%2FVvEy0AcxaTrIdMDWfvGA%2Fimage.png?alt=media&#x26;token=2dd2ba01-bb41-4a91-8629-8d48cfdbc40a" alt=""><figcaption></figcaption></figure>

For common features, please refer to [Menu Bar](https://axongenesis.gitbook.io/timeflow/user-guide/timeflow-editor/menu-bar) and [Update Settings](https://axongenesis.gitbook.io/timeflow/user-guide/timeflow-editor/update-settings).

### Editor vs Runtime

If you are using Place On Surface in the editor only, the runtime mode can be set in the menu bar to [Editor Only](https://axongenesis.gitbook.io/timeflow/user-guide/timeflow-editor/menu-bar#editor-and-runtime-modes). This destroys the component at runtime but preserves it in edit mode.

<figure><img src="https://2067910529-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FC3dOuetlQfYgK5FPUKgn%2Fuploads%2F8ZRfJCl3caReHwXXqb9T%2Fimage.png?alt=media&#x26;token=95bae5ab-95ef-4cce-a565-0d2f24cc5a9c" alt=""><figcaption></figcaption></figure>

### Refresh All

Use this button to bulk update all instances of Place On Surface throughout the scene.

{% hint style="info" %}
Use Refresh All after making changes to a terrain or the scene layout to update all placed items. This only affects Place On Surface instances currently active.
{% endhint %}

## Placement Mode

Objects may be placed either using Raycast or Sample Terrain Height.&#x20;

<figure><img src="https://2067910529-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FC3dOuetlQfYgK5FPUKgn%2Fuploads%2Fluy9aaIgiGx7q52LXZUO%2Fimage.png?alt=media&#x26;token=b65aa08a-9784-4129-9c0c-807710a9bc8d" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}
Please note that all placements are calculated and applied in world space.&#x20;
{% endhint %}

### Sample Terrain Height

This mode samples the height of the terrain using Unity's [built-in method](https://docs.unity3d.com/ScriptReference/Terrain.SampleHeight.html). If placement is only on terrains and the surface orientation isn't needed (i.e. the object doesn't need to rotate to the surface) then this mode is a more optimal choice than using Raycast.

<figure><img src="https://2067910529-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FC3dOuetlQfYgK5FPUKgn%2Fuploads%2FGXbh9T4iosDJ3tc9ztRE%2Fimage.png?alt=media&#x26;token=4c2b3749-aced-430b-8758-ebb6c28f9f95" alt=""><figcaption><p>This mode has a simpler setup with fewer options.</p></figcaption></figure>

### Raycast

Raycasting provides the best results since it can compute rotation and includes all terrains and colliders (according to the [Layer Mask](#layer-mask)). However raycasting is computationally intensive so should be used sparingly.&#x20;

<figure><img src="https://2067910529-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FC3dOuetlQfYgK5FPUKgn%2Fuploads%2F79RbiJ3WoIXt5IZmf4nH%2Fimage.png?alt=media&#x26;token=b04e3fc3-874e-4742-b6b1-e13c76af8023" alt=""><figcaption><p>The frequency of the raycast may be changed in the <a href="../../../user-guide/timeflow-editor/update-settings">Update Settings</a>. </p></figcaption></figure>

{% hint style="info" %}

#### Optimization

When using Raycast mode, it is recommended to change the update method to [Fixed Update](https://axongenesis.gitbook.io/timeflow/user-guide/timeflow-editor/update-settings#fixed-update), so that it updates according to the framerate for physics. This reduces the number of raycasts overall and improves performance.&#x20;
{% endhint %}

For more information, see [Raycast](https://docs.unity3d.com/ScriptReference/Physics.Raycast.html) and [Fixed Timestep](https://docs.unity3d.com/Manual/class-TimeManager.html) in the Unity documentation.

### Layer Mask

Restricts placement to only include terrains and colliders on the specified layers. This option is only available when using Raycast mode.

<figure><img src="https://2067910529-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FC3dOuetlQfYgK5FPUKgn%2Fuploads%2F8Dxge0BVY80xTnVVH5jg%2Fimage.png?alt=media&#x26;token=684bd445-25de-4dcc-99c1-fee45c4f77fd" alt=""><figcaption></figcaption></figure>

{% hint style="danger" %}

#### Avoid Same Object Collisions

If the current object being placed is on the same layer as the [Layer Mask](#layer-mask), this may result in the object detecting itself (if it has a collider) which leads to a runaway condition causing the object to fly off into space.&#x20;

To prevent this from happening, be sure the current object is on a different layer than the [Layer Mask](#layer-mask) or simply remove collider components from the object if they are not in use.
{% endhint %}

Please refer to the Unity documentation for [Layers and Layer Masks](https://docs.unity3d.com/Manual/layers-and-layermasks.html).

<figure><img src="https://2067910529-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FC3dOuetlQfYgK5FPUKgn%2Fuploads%2FvBW2fq6d6bcH4JegrTsB%2Fimage.png?alt=media&#x26;token=f2cbb805-aeef-44d1-a9bf-ed8b0da97f4c" alt=""><figcaption></figcaption></figure>

### Raycast Direction&#x20;

Sets the direction of the ray, originating from the current position plus any offsets. This field expects a normalized value (all vectors adding up to 1). Normalization is automatically applied to ensure the length of the ray is consistent.&#x20;

### Use Transform

Enable this to orient the raycast direction towards another object in the scene. This is helpful to make an object follow the contours of an object from all angles.

<figure><img src="https://2067910529-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FC3dOuetlQfYgK5FPUKgn%2Fuploads%2FBGgwCRFtmIUZvyJ3sI0O%2Fimage.png?alt=media&#x26;token=ba085db9-a186-4087-9fd1-81cacbe646f2" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}

#### Projecting Objects Onto Surfaces

Rays may be cast in any direction making it possible to place objects on surfaces from any angle simply by changing the Raycast Direction. This can also be used to make an object stick to another or to traverse the surfaces of multiple objects.
{% endhint %}

### Raycast Offset

Offsets the starting point of the raycast along the direction vector.

{% hint style="info" %}
Each raycast is like an arrow shot into the scene, detecting the first object hit. To ensure that the raycast starts at a far enough distance away from the target, an offset is often needed.&#x20;
{% endhint %}

{% hint style="info" %}
The X and Z axis offsets can also be used in special cases where the raycast needs to be shifted off center from the current position.
{% endhint %}

### + Terrain Height

If Terrain Height is enabled (recommended) the raycast is automatically offset by the height of the terrain so that the ray is always projected from a higher point. Otherwise, if the ray starts too low, it misses the terrain altogether and fails to place the object.&#x20;

{% hint style="danger" %}

#### Failing to Place

Since the raycast origin is based on the object position, once placed it might fail on the subsequent update since the starting point is now on or possibly below the terrain.

As a remedy, the Terrain Height option is enabled by default. However, it may also be necessary to add an additional offset manually depending on the unique conditions of your scene. If placement is failing, the offset and distance may need adjustment.&#x20;
{% endhint %}

{% hint style="success" %}
Terrain Height can be disabled as an optimization if it isn't needed. Using only the offset and distance are often sufficient and the terrain height sampling can be skipped.
{% endhint %}

### Raycast Distance

Sets the total length of the raycast. Only objects within this distance from the raycast origin may be detected. Placement occurs on the first collider or terrain hit. Adjust the distance according to the scale and needs of your scene.

## Apply to Transform

Placement may be placed on the same object (current transform) or applied to the transform of another object. Which setup you use depends on the desired results.

<figure><img src="https://2067910529-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FC3dOuetlQfYgK5FPUKgn%2Fuploads%2F8okoIFnXpISFzJaDOqRm%2Fimage.png?alt=media&#x26;token=2c7ca138-7cbd-4161-b50d-cd8bcbead71c" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}

#### Separate Transforms (placer vs item placed)

Applying results to a separate transform means that the current transform remains in place and is unaffected by placement. Since the origin of the raycast is based on the current transform, this can make placement more stable and avoid runaway conditions. This setup is also more conducive to using Place On Surface as a construction tool.
{% endhint %}

### Use Rigidbody

If enabled, placement is applied to the rigidbody component instead of the transform. This method of moving the object produces the same results visually, however allows the object to correctly interact with physics.

{% hint style="info" %}
Physics only works at runtime, so enter Play Mode to see final results. In edit mode, the transform is used instead as a proxy.
{% endhint %}

{% hint style="success" %}
When using rigidbody for movement, it is recommended to use [Fixed Update](https://axongenesis.gitbook.io/timeflow/user-guide/timeflow-editor/update-settings#fixed-update). This reduces the number of raycasts and improves performance.
{% endhint %}

{% hint style="warning" %}
A rigidbody component is required to use this feature. If one is not found, a warning is shown with the option to fix the issue by adding a new rigidbody component. A collider may still be needed if you wish the object to interact with others.
{% endhint %}

## Position

Enables positioning for all or individual axes to constrain placement to a specific axis or plane.&#x20;

<figure><img src="https://2067910529-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FC3dOuetlQfYgK5FPUKgn%2Fuploads%2FsWuGaS7703QP00YlvEv1%2Fimage.png?alt=media&#x26;token=857a9fe1-4da5-4a84-be11-538fd18bb413" alt=""><figcaption></figcaption></figure>

### Smooth Time

Applies temporal smoothing based on the time seconds. Use the Max field to set the max value of the slider.

{% hint style="success" %}
A small smoothing value is recommended for animation to avoid jitter.
{% endhint %}

{% hint style="info" %}
Smoothing is only applied while playing in Timeflow. When rewinding or jumping in time, position is applied directly to avoid odd placement results.
{% endhint %}

{% hint style="warning" %}
Larger smoothing values will likely result in objects passing through surfaces and a lag in the animation overall. &#x20;
{% endhint %}

### Height Offset

Adds an offset to the placement position on the Y axis.&#x20;

<figure><img src="https://2067910529-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FC3dOuetlQfYgK5FPUKgn%2Fuploads%2FMdE4pU1xF7C4kz8Z3kUo%2Fimage.png?alt=media&#x26;token=b87537dd-f1ce-4263-a96f-924561c6187d" alt=""><figcaption></figcaption></figure>

{% hint style="success" %}
Use this to set the height of an object where it is resting at ground level. This is often the case for objects with centered pivot points and characters with a hip or root offset.&#x20;
{% endhint %}

### World Limits

Enable limits to constrain the placement of an object within a bounding region in world coordinates.

<figure><img src="https://2067910529-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FC3dOuetlQfYgK5FPUKgn%2Fuploads%2FzsqakJDjWjRTB7JrjpeV%2Fimage.png?alt=media&#x26;token=8c7eb26b-2414-47da-9d06-4bd120582c65" alt=""><figcaption><p>X and Z are disabled automatically by the Enable Position states as shown in the example earlier.</p></figcaption></figure>

{% hint style="info" %}
Position limits are only enforced on each axis checked and according to [Enable Position](#apply-position).
{% endhint %}

## Rotation

<figure><img src="https://2067910529-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FC3dOuetlQfYgK5FPUKgn%2Fuploads%2F2uPTViGEqkPxPLNlIzxr%2Fimage.png?alt=media&#x26;token=2679d918-435d-4d6d-8494-ccd59cb6e5e7" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
The rotation channel is hidden from the Timeflow view if the Rotation mode is None.&#x20;
{% endhint %}

### Face Surface Hit

If enabled, the object orients to look at the point on the surface hit. Otherwise if off, the rotation matches the surface normal. This option is useful for projecting objects onto the surface of other objects, orienting to the projection angle rather than surface.&#x20;

### Smooth Time

Applies temporal smoothing over the specified time (in seconds). A longer time results in slower rotation, while a small time value responds more quickly.

{% hint style="success" %}
Smooth mode is recommended for animation otherwise noticeable jitter may occur using Direct placement.&#x20;
{% endhint %}

{% hint style="info" %}
Smoothing is only applied while playing in Timeflow. Whenever rewinding or skipping time, rotation is applied directly to avoid anomalies with smoothing.
{% endhint %}

## Gizmos

If enabled and using Raycast mode, the current direction and length is displayed using the display color selected.

<figure><img src="https://2067910529-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FC3dOuetlQfYgK5FPUKgn%2Fuploads%2FTbqdWhXFcmEYqP73SY8Z%2Fimage.png?alt=media&#x26;token=b2d1b8c6-6ff8-4c5b-b59e-e60d5362ed26" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
Note that the Gizmos color is the same as the channel color in the Timeflow view.
{% endhint %}

### Debug Ray

Draws lines in the color chosen precisely where raycasts are performed in 3D space. Each line remains visible for the duration specified.&#x20;

<figure><img src="https://2067910529-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FC3dOuetlQfYgK5FPUKgn%2Fuploads%2FezkFTjHdTuztkCHvL3Jj%2Fimage.png?alt=media&#x26;token=2c540d85-cf83-4346-8660-e105c0555bc7" alt=""><figcaption><p>Raycasts are drawn in red while playing the timeline. The thicker cyan line is the current direction and length.</p></figcaption></figure>

{% hint style="success" %}
This is a helpful investigation tool when placement isn't working as expected. Use Duration to set how long (in seconds) each ray remains visible in the Scene View.
{% endhint %}

## Additional Notes

### Fixed Update

Since raycasting is a physics feature, it is advised for optimal performance to use Fixed Update, set in the [Update Settings](https://axongenesis.gitbook.io/timeflow/user-guide/timeflow-editor/update-settings). This reduces the number of raycasts to the frame rate defined by [Fixed Timestep](https://docs.unity3d.com/Manual/class-TimeManager.html) in Project Settings under Time.

<figure><img src="https://2067910529-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FC3dOuetlQfYgK5FPUKgn%2Fuploads%2FXH4SjgVvDLNfiIJsec0X%2Fimage.png?alt=media&#x26;token=21e47b2f-b2ff-4a5e-827b-739b682f7005" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}
Any other Timeflow behaviors on the same object should also be set to Fixed Update if they affect placement, such as when animating the object's position or rotation.
{% endhint %}

### Using Explicit Update

To place an object just once and prevent it from automatically updating, the update mode for the Place On Surface behavior may be set to Explicit in the [Update Settings](https://axongenesis.gitbook.io/timeflow/user-guide/timeflow-editor/update-settings).

<figure><img src="https://2067910529-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FC3dOuetlQfYgK5FPUKgn%2Fuploads%2FheZl0ovRDusRJ9Dq3Reb%2Fimage.png?alt=media&#x26;token=d559ea9b-a318-4e18-bdaa-67fa9cbc8091" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
Setting update to Explicit means that Place On Surface will not recalculate until you press the [Refresh](https://axongenesis.gitbook.io/timeflow/user-guide/timeflow-editor/menu-bar#refresh) button.
{% endhint %}