A3D_GetSurfaceRotation

Find the rotation that stands an object on a surface, such as a crate on a slope.

The object turns by heading around its own up axis first, as its facing angle, and its up axis then follows the normal. A3D_RayCastNormal gives the normal of a surface.

native bool:A3D_GetSurfaceRotation(
    Float:normalX,
    Float:normalY,
    Float:normalZ,
    &Float:rx,
    &Float:ry,
    &Float:rz,
    Float:heading = 0.0
);

Parameters

Parameter	Description	Default
Float:normalX	Normal of the surface on the X axis.
Float:normalY	Normal on the Y axis.
Float:normalZ	Normal on the Z axis.
&Float:rx	Rotation on the X axis.
&Float:ry	Rotation on the Y axis.
&Float:rz	Rotation on the Z axis.
Float:heading	Facing angle of the object, in degrees.	0.0

Returns

• true when the rotation was written.
• false when the normal has no length.

Remarks

The object first turns by heading around its up axis, as a facing angle, and its up axis then tilts onto the normal by the shortest way. On flat ground the result is 0.0, 0.0 and the heading. On a slope the object leans with the ground and still faces the heading as closely as it can.

Example

Puts a crate on the ground under a point, leaning with the slope.

stock PlaceCrate(Float:x, Float:y, Float:z, Float:heading) {
    new
        Float:hitX,
        Float:hitY,
        Float:hitZ,
        Float:normalX,
        Float:normalY,
        Float:normalZ,
        Float:rx,
        Float:ry,
        Float:rz
    ;

    if (!A3D_RayCastNormal(x, y, z, x, y, z - 50.0, hitX, hitY, hitZ, normalX, normalY, normalZ, .flags = A3D_COLLIDE_MAP)) {
        return INVALID_OBJECT_ID;
    }

    A3D_GetSurfaceRotation(normalX, normalY, normalZ, rx, ry, rz, heading);

    return CreateObject(1271, hitX + normalX * 0.35, hitY + normalY * 0.35, hitZ + normalZ * 0.35, rx, ry, rz);
}

Related

• A3D_RayCastNormal: Find the first thing a segment hits, and the direction its surface faces there.
• A3D_GetLookRotation: Find the rotation that turns the front of an object, its Y axis, to a point, such as a camera or a turret.
• A3D_SetRotation: Turn a physics object to a new rotation at once.