👇Object Placement

Detailed information about the component's interface and its use.

Overview

The ObjectPlacement class manages the placement of objects within a scene in Unity. It provides tools to precisely place, rotate, and align objects based on user input or predefined settings. This component is essential for the use of this asset.

Runtime

Properties

This can all be configured in the Editor. For Runtime changes you can set these properties when needed/available:

• Instance: Singleton instance of the ObjectPlacement. Ensures only one instance is active using the Singleton pattern.

• PlacementObjectPrefab: The prefab used for placement operations. Can be set dynamically when not actively placing an object.

• PlayerCamera: The main camera used for rendering the world to the player, crucial for calculating placement positions from screen points.

• PlacementArea: Defines the area within which objects can be placed, potentially restricting placement outside a designated zone. See Placement Area for more information.

• PlacementPrefabs: Specifies a component that holds a list of placement prefabs, this will return null when component is not set up.

• AdditionalValidator: Validator invoked after internal validation has been performed with a valid result, if result is invalid this will not be invoked. Only already valid placements can be rejected by this validator. By implementing IValidatePlacement you can integrate a more complex system of your project giving it one additional validation layer.

• debugLogsEnabled: Specifies if the console logging is enabled.

• drawGizmosEnabled: Specifies if the gizmos for placement are enabled.

Public Interface

• BeginPlacement(GameObject prefab, Material[] validPlacement, Material[] invalidPlacement): Initiates the placement of a specific prefab with optional materials to indicate valid or invalid placement states.

• BeginPlacement(): Initiates the placement of current prefab and material configuration.

• CancelPlacement(): Cancels the current placement operation and removes any temporary placement objects.

• TryEndPlacement(out GameObject newInstance): Attempts to finalize the placement of the current object, returning true if successful along with the newly placed object.

• TryEndPlacement(out PlacementResult result): Attempts to finalize the placement of the current object, returning true if successful along with the result of the placement (position and rotation).

• RotateObjectYAxis(float yAngle): Rotates the currently placing object on the Y-axis by the specified angle.

• RotatePlacement(float directionalMagnitude): Rotates currently placing object on Y axis by multiplying directional magnitude parameter with rotationSpeed.

Editor

Here you can read about how to use the component inspector in Editor to set up it's configuration for your needs.

Setup

You should use this tab to configure behaviour of the component. You can reference camera and prefab directly from Editor or use component's public interface to achive this in code.

Hover over each field to read more about their use.

Setup options

Input

This input controller is optional as you can manually control the placement with your own input components.

If you choose to use the provided input components, you can choose between the old Input framework or the newInputSystem framework provided by Unity. In case you do not see the new input option, you will see a warning and to use it, you first need to add the package and set up input options in project settings.

For built-in touch screen support, you want to use InputSystem and change the cursor type.

After you pick your desired input component, customise keys/actions for your project.

Input Options

You can customise your own input by subclassing AInputControl.

Note: When using provided system, child game object named Input will be attached to the root game object with the input component.

Prefabs

You can optionally set up prefabs for the placement component.

Drag your prefab assets to this list and use input events or buttons on screen to select from them.

When cycles rotation is enabled, using Next and Back methods loop back to the start/end of the list. Disabling will prevent movement when out of range.

This behaviour is managed by PlacementPrefabs component and once set up, you can also access it in code like this:

PlacementPrefabs prefabs = ObjectPlacement.Instance.PlacementPrefabs;
// Start with 5th prefab
prefabs.SetPrefabIndex(4)
// Go to next one
prefabs.Next();
// Go to previous one
prefabs.Back();

Visuals

On visuals tab you can configure animations and optionally use the same materials for all placing objects.

Toggle options:

• Place During Animation: When enabled, placement will be possible while object is animating, but still be placed at cursor position. When this is disabled, object will have to be within the thresholds defined below.

• Position; Animate: When enabled, position change animates with specified speed.

• Rotation; Animate: When enabled, rotation change animates with specified speed.

• Apply Materials: It applies specified materials for every placing object. When disabled, you should manage changing materials by yourself, potentially using ObjectPlacementObserver to observe placement events on the object itself.

Visuals tab

Events

Optionally you can use Events tab to set up the events on Object Placement component itself.

To use the events simply click on Add events button.

Additionally ObjectPlacementObserver can be used for per-object use.

And ObjectPlacementEvents class can be used in code directly, no game object's involved.

Events tab

Note: When these events, child game object named Events will be attached to the root game object with the events component.