BorrowedTorch.SceneGizmo 1.2.2

Prefix Reserved
dotnet add package BorrowedTorch.SceneGizmo --version 1.2.2
                    
NuGet\Install-Package BorrowedTorch.SceneGizmo -Version 1.2.2
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="BorrowedTorch.SceneGizmo" Version="1.2.2" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="BorrowedTorch.SceneGizmo" Version="1.2.2" />
                    
Directory.Packages.props
<PackageReference Include="BorrowedTorch.SceneGizmo" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add BorrowedTorch.SceneGizmo --version 1.2.2
                    
#r "nuget: BorrowedTorch.SceneGizmo, 1.2.2"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package BorrowedTorch.SceneGizmo@1.2.2
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=BorrowedTorch.SceneGizmo&version=1.2.2
                    
Install as a Cake Addin
#tool nuget:?package=BorrowedTorch.SceneGizmo&version=1.2.2
                    
Install as a Cake Tool

BorrowedTorch.SceneGizmo

A world-orientation gizmo for MonoGame: the small X / Y / Z widget in the corner of an editor viewport that turns with the camera, so you can always read which way world space is facing. Hovering a tip highlights its axis, and clicking one hands you that axis to snap the view to, like the axis gizmo in Unity or Blender.

Install

dotnet add package BorrowedTorch.SceneGizmo

Targets net10.0-windows. Depends on BorrowedTorch.Camera 2.5.1 or later. It does not bring MonoGame: reference the MonoGame your game runs on - DesktopGL, WindowsDX or BorrowedTorch's compute fork, any release from 3.8.1.303 on. (1.0.0 brought the old compute fork, MonoGame.Framework.Compute.WindowsDX.NoMemoryLeak, with it.)

Quick start

using BorrowedTorch.SceneGizmo;
using Microsoft.Xna.Framework.Input;

// LoadContent: one gizmo per graphics device. The colors are optional.
_gizmo = new OrientationGizmo(GraphicsDevice)
{
    AxisXColor = new Color(220, 70, 70),
    AxisYColor = new Color(90, 210, 90),
    AxisZColor = new Color(80, 140, 230),
    AxisLetterColor = new Color(245, 245, 245)
};

// Update: refresh the hover highlight, and let a click on a tip snap the camera.
var mousePosition = Mouse.GetState().Position;

_gizmo.UpdateHover(_camera, mousePosition);

if (clickedThisFrame && _gizmo.TryPickAxis(_camera, mousePosition, out var axis))
    _freeCameraController.SnapTo(-axis); // the clicked axis should point at the viewer, so look down its negative

// Draw: after the scene, so the widget sits on top of it.
_gizmo.Draw(_camera);

// UnloadContent
_gizmo.Dispose();

_camera is a BorrowedTorch.Cameras.Camera. The gizmo reads its View matrix, so it shows the orientation as of the camera's last Update.

API

Member Meaning
OrientationGizmo(GraphicsDevice) Creates the effect and the vertex buffers. Dispose it with the device.
AxisXColor, AxisYColor, AxisZColor Arm and knob colors of the three axes. Negative arms are drawn at 40% brightness.
AxisLetterColor Color of the X / Y / Z letters on the positive tips.
UpdateHover(camera, mousePosition) Sets the hover highlight from the cursor. Call once per frame before Draw, and pass the position even when the cursor is elsewhere: that clears the highlight.
TryPickAxis(camera, mousePosition, out axis) The signed unit axis (Vector3.UnitX, -Vector3.UnitZ, ...) whose tip lies within 14 px of the cursor, or false. The frontmost tip wins when two overlap, and the cursor has to be inside the widget's square.
Draw(camera) Draws the widget in the top-right corner of the current viewport, over whatever is already there.
Dispose() Releases the effect.

Mouse positions are in pixels of the viewport current at the time of the call, the same GraphicsDevice.Viewport that Draw places the widget in, so pick with the viewport you draw with.

How it works

  • Placement. A 110 px square, 12 px in from the top-right corner of the current viewport. It is drawn through its own viewport with a fixed orthographic projection, so it never scales with the window.
  • Orientation. The main camera's view matrix with its translation replaced: the gizmo origin sits 4 units straight ahead and turns exactly as the camera does, wherever the camera is, floating origin included.
  • Geometry. Six arms from the origin, built every frame as camera-facing quads in view space. Positive arms are full length and carry a knob and a letter; negative arms are shorter and dimmed. Letters lie in the screen plane, so they stay upright when the camera rolls.
  • Order. Depth testing is off so the widget floats above the scene. The quads are sorted far to near on the CPU instead and go to the GPU as a single draw call. Letters are biased slightly toward the viewer so they sit on their own knob, and an arm in front of a letter hides it.
  • State. The viewport and the blend, depth-stencil and rasterizer states are saved and restored around the draw. The vertex buffers are reused, so there is no per-frame garbage.

Conventions

MonoGame's right-handed frame: +X right, +Y up, and the camera looks down -Z. The axis TryPickAxis returns is the world axis of the tip under the cursor, so to look at the scene along it, snap the camera to face its negative.

Building and testing

From the BorrowedTorch.SceneGizmo folder, which holds the solution:

dotnet test

The xUnit suite in BorrowedTorch.SceneGizmo.Tests covers the layout, picking, the quad builder and the painter's sort, and needs no graphics device.

License

MIT

Product Compatible and additional computed target framework versions.
.NET net10.0-windows7.0 is compatible. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
1.2.2 55 11/18/2026
1.2.1 53 11/18/2026
1.2.0 53 11/18/2026
1.1.0 101 11/14/2026
1.0.0 130 10/16/2026