MonoPrimitives 0.9.1

MonoPrimitives

Immediate-mode 2D and 3D primitive drawing for MonoGame, plus the small set of helpers a fast prototype usually needs — camera, input, easing, color, noise, and collision/raycast tests — so you don't have to pull in a handful of separate external libraries for those.

Built for prototypes: simulations (boids, cellular automata, predator-prey, pandemic models, terrain), generative art, and small retro-style game demos. Not a game engine, and not aimed at shipping a full commercial game.

Install

dotnet add package MonoPrimitives

Or scaffold a whole starter project (Camera2D, letterboxed 1080p virtual resolution, MSAA, input, a RenderContext bundle) with the dotnet new template — not yet published as its own package, so install it from a clone of this repo for now:

dotnet new install ./templates/PrimitiveBase
dotnet new primitivebase -n YourGame

One NuGet package, one assembly, one DLL — 2D and 3D both come with it, no separate sub-packages to resolve. Internally it's still organized into three namespaces so nothing is duplicated between them:

Quick start

using MonoPrimitives.Primitives2D;

private Primitive2DBatch _batch;

protected override void LoadContent()
{
    _batch = new Primitive2DBatch(GraphicsDevice);
}

protected override void Draw(GameTime gameTime)
{
    _batch.Begin();
    _batch.FillCircle(new Vector2(400, 300), 50, Color.Red);
    _batch.DrawRectangle(100, 100, 200, 80, Color.White, Color.Black, thickness: 4);
    _batch.End();
    base.Draw(gameTime);
}

using MonoPrimitives.Primitives3D;

private Primitive3DBatch _batch;
private Camera3D _camera;

protected override void LoadContent()
{
    _batch = new Primitive3DBatch(GraphicsDevice);
    _camera = new Camera3D(
        position: new Vector3(6, 6, 6),
        target: Vector3.Zero,
        up: Vector3.Up,
        fovy: 50f
        );
}

protected override void Draw(GameTime gameTime)
{
    _batch.Begin(_camera);
    _batch.FillSphere(Vector3.Zero, 1f, Color.Red);
    _batch.End();
    base.Draw(gameTime);
}

Every shape follows the same Fill<Shape> (solid) / Border<Shape> (outline, grows inward) / Draw<Shape> (both) pattern, in both 2D and 3D.

Documentation

Each class has its own guide — start with whichever one covers what you're touching, or see Guide/README.md for a "brand new here" reading order:

Drawing

• Primitive2DBatch — every 2D shape (rectangles, circles, ellipses, capsules, polygons, sectors/rings, splines), gradients, shadows, rounded/chamfered corners.
• Primitive3DBatch — every 3D shape (cubes, spheres, cylinders, capsules, torus, planes, heightmaps), flat-shading lighting, splines.
• DebugFont5x7 — a built-in bitmap debug font, 2D and 3D (billboarded).

Camera & viewport

• Camera2D & Viewport — pan/rotate/zoom, bounds, follow, shake, and the ViewportAdapter2D family (letterboxing/scaling for resolution independence).
• Camera3D — the 3D counterpart: 5 behaviour modes, free-fly/orbit/first-/third-person controllers.

Input

• PrimitiveInput — keyboard/mouse/gamepad polling, vibration, typed text, and raw KeyboardState/MouseState/GamePadState access for anything not wrapped.

Collision

• Collision2D — every 2D overlap/ray check by shape.
• PolygonUtil — IsConvex (does my polygon qualify for SAT?) and Triangulate (ear clipping, for your own mesh/collision/nav data).
• Collision3D — sphere/box/capsule/plane/triangle/quad overlap and raycasts.

Math & utilities

• MathUtil — Remap/DeltaAngle/LerpAngle/PingPong, the scalar helpers MathHelper doesn't have.
• Easing — 31 tweening curves for one-shot animations with a known duration.
• Noise — seedable Perlin noise, fBm, ridge, and turbulence.
• RandomUtil — seedable distribution sampling (Gaussian, Poisson, Binomial, uniform disc/sphere, weighted picks).
• Color — a curated color palette plus hex/HSV conversion and adjustment.
• Trail — a fading position-history trail, 2D and 3D.
• UnitCircleLut / TrigLut — the trig-free lookup tables the shape batches are themselves built on, for your own curved geometry.
• VectorExtensions — angle/rotation/approach/clamp helpers on MonoGame's own Vector2, plus Vector3Extensions (3D) in the same guide.
• RectangleF — a float-precision counterpart to MonoGame's integer-only Rectangle.
• RingBuffer — a generic fixed-capacity ring buffer for your own history/log/sample-window need.
• ObjectPool — a generic object pool for anything spawned/discarded often enough to want reuse over reallocation.

App helpers

• FrameLimiter — sleep+spin frame pacing, more precise than IsFixedTimeStep alone.
• FastTexture — raw-GL texture upload, 2.5-2.7x faster than SetData for frequent updates.
• FpsCounter — rolling-average FPS measurement.
• ScreenshotUtil — one-call back-buffer capture to .png/.jpg.
• TextureUtil — procedural texture generation (solid/gradient/checkerboard/from Noise) plus resize/crop/flip/tint/combine transforms.
• Cooldown — a simple countdown struct for attack cooldowns, spawn timers, input debouncing.
• WindowUtil — minimize/maximize/restore, opacity, window icon, multi-monitor info, clipboard text, and captured-cursor mouse-look.

For the project's own internals (architecture map, conventions, the reasoning behind non-obvious choices), see Design/README.md.

Examples

• samples/MonoPrimitives.Sample — a visual-regression gallery of every 2D and 3D shape, camera-controlled.
• examples/test/ — one focused demo per non-drawing component: collision, input, viewport adapters, noise, particle trails, text.
• examples/demos/ — small complete games built on the library (Breakout, Tetris, Asteroids in 2D and 3D, a platformer, Snake, a boids simulation).

What this isn't

• No physics resolution — collision checks detect overlaps, they never resolve them.
• No texture/model loading, no window management — that's MonoGame's own Game/content pipeline.
• No scene graph — every draw call is immediate; nothing is retained between frames.

Inspiration

This library borrows ideas from several places rather than inventing its own conventions from scratch:

• Apos.Shapes — Fill/Border/Draw per shape, the core naming convention the whole drawing API is built on, comes from here: Apos.Shapes uses that exact three-verb split (FillCircle/BorderCircle/DrawCircle, and so on for every shape it has).
• raylib — the other biggest influence, drawn on more than the rest: Camera3D's movement/rotation math is a direct port of rcamera.h, and Collision3D's GetRayCollision* naming and result struct follow raylib's own collision module.
• raylib-cs — its C# bindings keep raylib's own function names as-is (DrawCircleV, DrawRectangleV) but swap raylib's custom math types for .NET's own System.Numerics.Vector2/Vector3 — the same instinct behind this library using MonoGame's own Vector2/Vector3/Color rather than defining its own.
• MonoGame.Extended — Camera2D/ViewportAdapter2D's design (letterbox/scaling viewport adapters composed with a camera) follows its OrthographicCamera/ViewportAdapter shape.
• Godot — several individual methods are confirmed against Godot's own equivalents where raylib has no answer: PrimitiveInput.GetAxis's tie-to-zero behavior matches Input.get_axis, DebugFont5x7's cylindrical text billboarding matches Label3D's default billboard mode, RandomUtil.NextWeightedIndex matches RandomNumberGenerator.rand_weighted_pick.
• libGDX — PolygonUtil.Triangulate matches its EarClippingTriangulator, and CoverViewportAdapter2D fills the same gap as its Scaling.fill mode (uniform scale, crop the overflow, never show bars) — a real third viewport-fit option neither raylib nor MonoGame.Extended's own adapters covered.
• Processing / p5.js — the underlying philosophy: draw a shape with one call, no setup ceremony, fast enough to iterate on an idea in a sketch rather than a project. Noise's API shape (seedable, sample-anywhere) is the same idea as Processing's own noise().

None of the above are dependencies — MonoPrimitives only depends on MonoGame itself. They're referenced here as the design lineage, not as libraries this one wraps or requires.

Status

Published on NuGet, pre-1.0 — the API can still change between minor versions as gaps get closed. See Design/ROADMAP.md for known gaps and deliberate deferrals, and CHANGELOG.md for what changed in each version.

License

MIT — see LICENSE.