# aim3D

[Built-ins](README.md)

Canonical ID: `scene3d.aim`. Nederlands: `richt3D`.

Asks which object the camera is pointing at. Imagine a straight, invisible line going forward from the camera. This **ray** tests every object within `maximumDistance`, including objects whose solidity is off. The function returns the nearest object's name, or empty text `""` if it hits nothing.

If two hits are equally far away, the object created first wins: this is **insertion order**. A ray starting inside an object hits it at distance zero. A nearer wall can therefore hide a farther target from this question. The test uses the mathematical shapes, so you do not need to draw a frame first. See [3D words and camera rules](../guides/scene3d.md).

## Signature

```text
aim3D(maximumDistance)
```

## Arguments

| Parameter | Type | Requirement |
|---|---|---|
| `maximumDistance` | Number | Finite, greater than 0 and at most 1,000. |

## Return value

`Text`.

## Example

```pliro
# language: en
clear3D("black")
box3D("target", 1, 1, 1)
camera3D(0, 0, 3)
let hit = aim3D(10)
if hit != "":
    color3D(hit, "red")
say hit
draw3D()
```

Prints `target` and colors the hit object red.

## Notes and common mistakes

Use the function name for your source language. Its [canonical ID](../concepts/canonical-identity.md) is a shared documentation label; you do not type that ID as a call. Giving your own variable or function the same name can hide the built-in. Supply the documented [arguments](../concepts/parameters-and-arguments.md) and value types. Pliro reports mismatches when checking can detect them, or when the call runs.

A **host** is the app or environment running your program. To see a drawing, it needs a **renderer**, the part that draws on screen. The [command-line](../concepts/command-line.md) command `pliro run` shows text but does not draw these graphics. The [host support table](../guides/hosts.md) explains which effects work in the IDE, browser, native app, and phone preview. A native build reports an unsupported capability instead of leaving it out.

In 3D, +Y points up. **Yaw** is the left-or-right angle; at zero the camera faces -Z. The world holds at most 256 objects. Changes appear when you call `draw3D`. An invalid call leaves the world unchanged. Editing requires an existing object name; creating objects and removing an absent name are exceptions. Use the [portable color names or hex codes](../guides/colors.md); transparent colors are unavailable here. Version 1 of the phone preview's communication format does not carry 3D scenes. See the [3D guide](../guides/scene3d.md) for the coordinate rules.

## Related entries

[clear3D](clear3D.md) · [box3D](box3D.md) · [sphere3D](sphere3D.md) · [cylinder3D](cylinder3D.md) · [position3D](position3D.md) · [Programming guides](../guides/scene3d.md) · [Host support](../guides/hosts.md) · [Calls and arguments](../syntax/calls.md)