RealisticPhysics UnitConverter

Documentation

Reference for getting started, API usage, inspector integrations, settings, extending the system, and troubleshooting. The package also ships PDF and in-editor documentation under Assets/RealisticPhysics/UnitConverter/Documentation.

Getting Started

Import RealisticPhysics UnitConverter into your Unity project. Runtime conversion APIs work without scenes, components, or editor setup. Optional inspector overrides and display preferences use a settings asset.

  1. Import the package from the Unity Asset Store.
  2. For runtime conversions, add a using for the family you need (for example RealisticPhysics.UnitConversion.Length).
  3. Call UnitConverterLength.Convert, extension methods, or direct unit methods as shown in the API sections below.
  4. For editor integration, open Tools → RealisticPhysics → UnitConverter → Open Settings and configure overrides.

Assembly definition files separate runtime and editor code so you can reference only the assemblies your project needs.

Settings

Inspector overrides and display preferences are controlled through a dedicated UnitConverter settings asset.

Asset path

Assets/RealisticPhysics/UnitConverter/Settings/UnitConverterSettings.asset

Unity menu

Tools > RealisticPhysics > UnitConverter > Open Settings

Configurable options

  • Enable Unity inspector overrides globally
  • Per-component override toggles: Transform, Rigidbody, BoxCollider, SphereCollider, CapsuleCollider, CharacterController, Camera, Light, AudioSource
  • Preferred display units for Transform position, collider dimensions, Rigidbody mass, camera clip planes, light range, and audio distance

Transform override is enabled by default. Other built-in overrides are included but disabled by default to reduce conflicts with other Unity editor tools.

Inspector Overrides

UnitConverter can replace selected Unity Inspector fields with converted display values. Unity continues to store native values (meters, kilograms, and so on); the Inspector shows and edits values in your preferred units.

Supported components:

  • Transform (position)
  • Rigidbody (mass)
  • BoxCollider, SphereCollider, CapsuleCollider (size / radius / height)
  • CharacterController (height, radius, center)
  • Camera (near / far clip planes)
  • Light (range)
  • AudioSource (min / max distance)

When you edit a displayed value (for example 100 cm for position Y), UnitConverter converts back to the native unit Unity expects (1.0 m) before applying the change.

Static Converter API

Each conversion family exposes a static converter class and a unit enum. Use explicit Convert calls when you want readable, family-scoped conversion without extension syntax. 

using RealisticPhysics.UnitConversion.Length;

double centimeters = UnitConverterLength.Convert(
    1.5,
    UnitConverterLengthUnit.Meter,
    UnitConverterLengthUnit.Centimeter);

Values convert through the family base unit internally, keeping behavior consistent across API styles.

Extension Method API

Extension methods support double, float, decimal, and common integral numeric types for fluent conversion on numeric values. 

using RealisticPhysics.UnitConversion.Length;

double value = 1.5;
double centimeters = value.Convert(
    UnitConverterLengthUnit.Meter,
    UnitConverterLengthUnit.Centimeter);

Direct Methods and Namespaces

Direct unit-specific methods provide highly explicit names (for example MeterToCentimeter) under namespaces grouped by family and unit system. Import only the namespaces you need. 

using RealisticPhysics.UnitConversion.Length.Metric;

double centimeters =
    UnitConverterMetricLength.MeterToCentimeter(1.5);

Namespace examples

RealisticPhysics.UnitConversion.Length
RealisticPhysics.UnitConversion.Length.Metric
RealisticPhysics.UnitConversion.Length.Imperial
RealisticPhysics.UnitConversion.Length.Survey
RealisticPhysics.UnitConversion.Length.Nautical
RealisticPhysics.UnitConversion.Volume.ImperialUS
RealisticPhysics.UnitConversion.Volume.ImperialUK
RealisticPhysics.UnitConversion.Mass.Troy

US and UK Imperial volume units are separated because some unit names are shared but values differ.

Supported Families and Units

The package includes 97 conversion families, 1,632 units, and 40,000+ compatible conversion paths. Each family has its own unit enum and converter class, which helps prevent invalid cross-family conversions.

Categories include:

  • Physical units (length, mass, area, volume, and related quantities)
  • Electrical units (voltage, current, resistance, power, and related)
  • Digital units (data size, transfer rates)
  • Motion, pressure, energy, temperature, fluid, radiation, and lighting units
  • Utility and development-oriented unit groups

Metric, Imperial, Imperial UK, Imperial US, engineering, scientific, nautical, survey, historical, and other unit groups are organized under family-specific namespaces.

Length Examples

using RealisticPhysics.UnitConversion.Length;

// Static API: feet to meters
double meters = UnitConverterLength.Convert(
    10,
    UnitConverterLengthUnit.Foot,
    UnitConverterLengthUnit.Meter);

// Extension API: inches to millimeters
double mm = 12.0.Convert(
    UnitConverterLengthUnit.Inch,
    UnitConverterLengthUnit.Millimeter);

// Direct API (metric namespace)
using RealisticPhysics.UnitConversion.Length.Metric;
double km = UnitConverterMetricLength.MeterToKilometer(1500);

Electrical Examples

using RealisticPhysics.UnitConversion.Power;

// Convert mechanical horsepower to watts
double watts = UnitConverterPower.Convert(
    2,
    UnitConverterPowerUnit.HorsepowerMechanical,
    UnitConverterPowerUnit.Watt);

using RealisticPhysics.UnitConversion.Voltage;

double millivolts = 12.0.Convert(
    UnitConverterVoltageUnit.Volt,
    UnitConverterVoltageUnit.Millivolt);

Unity Inspector Examples

Transform — position in centimeters

  • Unity stores Position Y as 2.5 m
  • Inspector displays 250 cm when centimeters are preferred
  • Editing to 100 cm writes 1.0 m back to the component

Rigidbody — mass in pounds

  • Native mass may be stored in kilograms while the Inspector shows pounds for editing

Light — range in feet

  • Set the preferred light range unit in settings; displayed range converts on edit

See the Inspector section on the home page for interactive examples of each supported component.

Runtime Demo

A runtime demo scene is included in the package. Open it from the project to see conversion calls in a live Unity context without configuring inspector overrides. 

Assets/RealisticPhysics/UnitConverter/Demo/UnitConverterRuntimeDemo.unity

Use the demo scripts as templates for gameplay systems, simulation tooling, imported data normalization, or editor utilities that need reliable unit conversion at runtime.

Adding a New Unit

To add a unit to an existing family, extend that family’s unit enum, register the conversion factor to the family base unit, and update the family converter so static, extension, and direct APIs resolve the new unit.

  1. Add the enum member to the family’s UnitConverter*Unit type.
  2. Define the multiplier or offset relative to the family base unit in the family’s conversion table.
  3. Regenerate or update direct method wrappers if your workflow uses unit-specific APIs.
  4. Run existing family tests or spot-check conversions against known reference values.

The in-package extension guide under Documentation/Extension describes the exact file layout and naming conventions used by generated families.

Adding a New Unit Family

A new family requires a base unit, unit enum, converter class, namespaces, and optional direct-method namespaces following the same canonical base-unit pattern as existing families.

  1. Choose the family base unit (for example the SI base for that quantity).
  2. Create UnitConverterYourFamily, UnitConverterYourFamilyUnit, and organized sub-namespaces.
  3. Implement Convert using base-unit in/out conversion.
  4. Add extension methods and direct helpers consistent with other families.
  5. Register the family in assembly definitions if split across runtime assemblies.

Keep families isolated: length enums must not mix with power or mass enums, so incompatible conversions remain a compile-time concern.

Troubleshooting

Inspector override not visible

  • Confirm overrides are enabled in UnitConverter Settings.
  • Enable the specific component toggle (Rigidbody, Light, and so on).
  • Check for conflicts with other custom Inspector or editor tooling.

Wrong unit shown in Inspector

  • Verify preferred display units for that component type in the settings asset.
  • Remember Unity still stores native units; only the display layer changes.

Conversion result unexpected

  • Confirm source and target units belong to the same family enum.
  • For Imperial volume, use ImperialUS vs ImperialUK namespaces when names overlap.
  • Compare against static API and direct methods to isolate API-style issues.

Missing namespace or type

  • Add the correct using for the family or sub-system (Metric, Imperial, and so on).
  • Ensure your asmdef references the UnitConverter runtime assembly for that family.