Mathfs: Freya Holmér's Unity math library, and where it deliberately breaks from Mathf

A personal library published with no compatibility promises

FreyaHolmer/Mathfs opens with an unusually candid description of what it is: the math functionality the author writes and uses in her own personal projects, shared so other people can use it too. The second bullet sets the terms of service for the whole repository. She will recklessly edit and adapt things without too much thought into backwards compatibility.

That is not a warning about sloppy code, it is a statement about versioning policy. Paired with the note that commits carrying version tags should be relatively stable while other commits may not be, it tells you to install a tag rather than track the branch if you cannot absorb a breaking change on a random Tuesday. The repository itself is not archived and the most recent push is dated 2026-07-31, so the library is still being worked on.

The other hard constraint is the language version. Minimum Unity is currently 2021.2, because the code uses newer C# features. The README suggests an IDE can auto-downgrade if you are stuck on something older, which is a reasonable fallback but not a supported configuration.

The scale suggests real production use: 2,751 stars and 191 forks against only 3 open issues. A library with that ratio of adoption to reported problems is usually either very stable or very small in surface area, and in this case it is both a focused geometry library and one person doing the work.

Three installation routes, and the one to pick

The README documents three ways in. A plain install means cloning or downloading the repository and dropping it somewhere in your Unity project's Assets folder, which works and gives you no version control story at all. The Unity Package Manager route adds a line to `Packages/manifest.json`, and it offers two variants. Pinning a tag is the recommended one:

"com.acegikmo.mathfs": "https://github.com/FreyaHolmer/Mathfs.git#0.1.0",

Removing the `#0.1.0` suffix pulls the latest commit, which the README flags as potentially unstable. Given the stated policy of editing without worrying about backwards compatibility, that distinction is the whole ballgame. The third route goes through OpenUPM, where the package is named `com.acegikmo.mathfs` and the README gives the CLI form:

openupm add com.acegikmo.mathfs

Once installed, everything is reachable through one namespace: you write `using Freya` at the top of your script and the library's types and extension methods come into scope. One namespace for curves, trajectories, polygons, circles, vectors, colours and smoothing means a single line of using to remember, and it also means name collisions with your own types show up loudly rather than silently.

Radians, unclamped lerp, and the missing Smoothstep

The Changes section at the bottom of the README is the part to read twice, because Mathfs deliberately diverges from Unity's Mathf and your existing habits will transfer badly if you skip it.

First, all angles are in radians and no method takes degrees. Unity's Mathf is mixed on this, with a lot of its trigonometric functions taking degrees, so a function name that looks familiar can change units on you.

Second, `Lerp` and `InverseLerp` are unclamped by default, and the clamped behaviour has moved into `LerpClamped` and `InverseLerpClamped` as the explicit special cases. The library also evaluates the interpolation with a more numerically stable formula than the one in Mathf. That is a genuine improvement at the edges, where Unity's version can lose precision, but it means unclamped lerp is now the thing you get by accident.

Third, `Smoothstep` is gone, replaced by `LerpSmooth` and `InverseLerpSmooth`. The README explains the split: LerpSmooth is how Smoothstep was implemented internally, while InverseLerpSmooth is the inverse that Unity's Mathf never provided. So the rename separates two ideas that used to share one name.

The fourth change is the one most likely to surface as an exception in production. `Min` and `Max` with arbitrary or array inputs throw on an empty input instead of returning 0. Returning zero for an empty array was always a guess, and this library makes the guess an error instead.

Trajectory math that solves for the projectile

The trajectory section is the strongest argument for the library, because these are the formulas you would otherwise derive yourself and then debug. Every function takes gravity as an input, which means nothing is hardcoded to a particular planet.

You can ask for displacement, that is a point in the trajectory, given gravity, angle, speed and time. You can invert it: `GetLaunchSpeed` from gravity, angle and lateral distance, and `GetLaunchAngles` from gravity, speed and lateral distance, which is the one that returns two solutions and needs a branch between them. Then there are the scalar queries, `GetMaxRange` from gravity and speed, `GetHeightPotential` from gravity, current height and speed, and the reverse of that last one, `GetSpeedFromHeightPotential`.

Having both directions available is the point. A designer can specify a target and ask what speed is required, or specify a speed and ask what angle lands on the target, without you deriving the quadratic each time. For a game where a character jumps to a marked location, that is exactly the shape of the question being asked.

The curve and spline list sits next to it and is equally broad: Bezier in quadratic, cubic and generalized forms, Hermite, Catmull-Rom, B-Spline in uniform cubic and generalized non-uniform variants, NURBS, and trajectory splines in cubic and generalized form. That covers procedural path following, editor gizmos and animation curves without reaching for a separate spline package.

Polygon, triangle and circle helpers for 2D work

The remaining feature list is organised by shape, which makes it easy to check whether the library covers the case you have. For polygons: area and signed area, an `IsClockwise` test, winding number, and a containment test. The signed variants and the winding number are the interesting ones, because they let you tell inside from outside without constructing geometry every frame.

Triangle math covers area and signed area from three points or from base and height, a containment test, the right-angle trigonometric set for opposite, adjacent, hypotenuse and angle, the incenter and centroid, incircle and circumcircle, and smallest angle. Incenter and circumcenter are the operations that turn up constantly in procedural generation and mesh work.

Circle math has the constructors that are usually written by hand: `FromTwoPoints` for the smallest circle passing through both, and `FromThreePoints` for the unique circle through three. It also carries every radius, area and circumference conversion in both directions, which is small but genuinely useful when you are mixing a physics radius with a text label size.

On top of that sit two-dimensional angle helpers like `AngToDir` and `DirToAng`, vector extension methods for ninety-degree rotation and rotation around a point, quadratic and linear root finders, remap functions, smoothing functions including `Smooth01` and `SmoothCos01`, and extension methods on colour such as `WithAlpha` and `MultiplyRGB`. The 2D intersection tests close the list, covering all combinations of ray, line segment, line and circle.

The package metadata does not match the README's stated minimum

One inconsistency is worth flagging before you commit. The README says the minimum Unity version is currently 2021.2, because the code uses newer C# features. `package.json` in the repository root declares `"unity": "6000.0"`, which is the Unity 6 line. It also carries version 1.0.0 while the README recommends pinning `#0.1.0`, and the package description differs slightly from the README's.

None of that is necessarily wrong. A package manifest's unity field can be set conservatively for the Unity Registry, and a 1.0.0 manifest version paired with a 0.1.0 git tag is common when the two versioning schemes are not kept in step. But the combination means you cannot rely on either file alone to predict what you will get, so pinning a tag in `Packages/manifest.json` remains the safer move.

The package metadata does confirm the other useful details: MIT licensing with the text in `LICENSE.txt`, documentation pointing back at the repository, and the author listed as Freya Holmér. The tree is small, just `Runtime/`, `Editor/`, `package.json` and the licence, which is consistent with a focused library rather than a framework.

Editorial conclusion

Mathfs is worth reaching for when your Unity project needs geometry that Mathf never had, since trajectory solving, curve evaluation, polygon winding and circle construction are the kind of code people otherwise rewrite badly in every project. The catch is stated plainly on the README and it matters: the library does not match Unity's Mathf conventions, angles are radians everywhere, lerp is unclamped by default, Smoothstep is renamed and empty min/max calls throw instead of returning zero. Install by pinning the `#0.1.0` tag through the package manager rather than tracking the master branch, then read the Changes section of the README before you start calling functions that share a name with a Mathf one.

Frequently asked questions

Official sources

1. FreyaHolmer/Mathfs on GitHub
2. Issues
3. License: MIT
4. README