Planes: sides, distance and projection — documentation

A normalized plane equation, ray/segment intersections and world-point projection.

What Plane means

A plane uses Normal.Dot(point) = D. Distance and Project require a unit normal. D is the right-hand scalar, not a position vector. Points and normal in an operation must share a coordinate space.

Plane	Point	DistanceTo	Project
Normal = Up, D = 2, meaning Y = 2	(1, 5, 3)	3	(1, 2, 3)
Same plane	(0, 0, 0)	−2	(0, 2, 0)

Positive distance is toward Normal. Negating both Normal and D preserves the geometric plane and reverses the distance sign. Plane(normal, d) does not normalize its input automatically. With Normal = 2 × Up and D = 4, DistanceTo at Y = 5 returns 6; Normalized makes it the correct distance 3. Both normal and D are rescaled. A zero vector is not a valid plane normal.

View a 3D projection

Create a separate 1.0.0 C# level with an Entity3D root, add TransformRig3D.cs and attach it. Set the window/viewport to 640×420, build and press F6. The blue cube has local point (1, 1, 0) under a rotated/scaled parent. The white marker projects its GlobalPosition onto the world Y = 0 plane.

$A world point and its horizontal-plane projection$

TransformRig3D.cs

C#
using System;
using Reckfell;

public partial class TransformRig3D : Entity3D
{
    public Entity3D Pivot { get; private set; } = null!;
    public MeshInstance3D Marker { get; private set; } = null!;
    public Plane GroundPlane => new(Vector3.Up, 0);
    public Vector3 ProjectedPoint => GroundPlane.Project(Marker.GlobalPosition);

    private static MeshInstance3D Box(Vector3 size, Color color, Vector3 position)
    {
        return new MeshInstance3D
        {
            Mesh = new BoxMesh { Size = size }, Position = position,
            MaterialOverride = new StandardMaterial3D
            {
                AlbedoColor = color, ShadingMode = BaseMaterial3D.ShadingModeEnum.Unshaded
            }
        };
    }

    public override void _Ready()
    {
        AddChild(new WorldEnvironment { Environment = new Reckfell.Environment
        {
            BackgroundMode = Reckfell.Environment.BGMode.Color,
            BackgroundColor = new Color(0.035f, 0.04f, 0.05f)
        }});
        AddChild(Box(new Vector3(8, 0.05f, 6), new Color(0.10f, 0.11f, 0.13f), new Vector3(0, -0.025f, 0)));
        Pivot = new Entity3D
        {
            Position = new Vector3(1, 0, 0), Rotation = new Vector3(0, Mathf.Pi / 4, 0),
            Scale = new Vector3(1.5f, 1, 0.6f)
        };
        AddChild(Pivot);
        Pivot.AddChild(Box(new Vector3(1.6f, 0.045f, 0.045f), new Color(0.25f, 0.46f, 1), new Vector3(0.8f, 0, 0)));
        Pivot.AddChild(Box(new Vector3(0.045f, 1.5f, 0.045f), Colors.White, new Vector3(0, 0.75f, 0)));
        Pivot.AddChild(Box(new Vector3(0.045f, 0.045f, 1.5f), new Color(0.45f, 0.48f, 0.55f), new Vector3(0, 0, 0.75f)));
        Marker = Box(new Vector3(0.2f, 0.2f, 0.2f), new Color(0.25f, 0.46f, 1), new Vector3(1, 1, 0));
        Pivot.AddChild(Marker);
        AddChild(Box(new Vector3(0.25f, 0.035f, 0.25f), Colors.White, ProjectedPoint + Vector3.Up * 0.025f));
        var camera = new Camera3D { Position = new Vector3(5, 4.5f, 7), Current = true, Fov = 48 };
        AddChild(camera); camera.LookAt(new Vector3(0.7f, 0.4f, 0), Vector3.Up);
        var canvas = new CanvasLayer(); AddChild(canvas);
        bool ru = TranslationServer.GetLocale().StartsWith("ru");
        var title = new Label { Position = new Vector2(24, 20), Text = ru
            ? "Локальная точка и мировая плоскость" : "A local point and a world-space plane" };
        title.AddThemeFontSizeOverride("font_size", 22); canvas.AddChild(title);
        canvas.AddChild(new Label { Position = new Vector2(24, 58), Text = ru
            ? "Синий куб: local (1,1,0). Белая метка: проекция на Y = 0."
            : "Blue cube: local (1,1,0). White marker: projection onto Y = 0." });
        ReckfellApi.Print("TRANSFORM local=" + Pivot.ToLocal(Marker.GlobalPosition));
    }

    public static bool TryTransformNormal(Basis basis, Vector3 normal, out Vector3 result)
    {
        result = Vector3.Zero;
        if (!basis.IsFinite() || !normal.IsFinite() || normal.LengthSquared() < 0.000001f ||
            MathF.Abs(basis.Determinant()) < 0.000001f) return false;
        Vector3 transformed = basis.Inverse().Transposed() * normal;
        if (!transformed.IsFinite() || transformed.LengthSquared() < 0.000001f) return false;
        result = transformed.Normalized();
        return true;
    }
}

Obtain the cube's world position before using the world Plane. Projecting local Marker.Position onto it would mix spaces. The file's TryTransformNormal handles normal conversion under scale; it is unnecessary for an already specified world Up.

Ray and segment

IntersectsRay(from, dir) returns Vector3?; check for a value before use. For Y = 2, a ray from (0, 5, 0) downward hits (0, 2, 0); upward does not. A parallel ray returns null. This is an infinite forward ray, not a line extending both ways.

IntersectsSegment(begin, end) restricts the hit to the segment endpoints. Y = 5 to Y = 0 intersects; 5 to 4 does not. Coincident points or infinitely many coplanar points do not become a unique hit. Near-parallel directions require the implementation's numerical tolerance.

A three-point Plane depends on point order. The checked C# constructor with Zero, Right, Up produces Forward (−Z). Do not assume a sign from another format's convention. Collinear points do not define a valid plane.

These operations do not query colliders, layers, visibility or occupied world space. Use a physics query to select a gameplay surface; Plane is for geometric calculations against a known plane.