Skip to content

Example: Math Library#

A walkthrough of examples/math_helpers_lib.cpp — a library plugin that exports reusable math functions.

Full Source#

#include <xenon/SDK.hpp>

XENON_LIBRARY_INFO(
    "math_helpers_lib",
    "Xenon",
    "Shared math utils",
    "1.0",
    "math_helpers"
)

extern "C" float lerp(float a, float b, float t)
{
    return a + (b - a) * t;
}

extern "C" float clamp_f(float value, float min_val, float max_val)
{
    if (value < min_val) return min_val;
    if (value > max_val) return max_val;
    return value;
}

extern "C" float remap(float value, float from_min, float from_max,
                        float to_min, float to_max)
{
    float t = (value - from_min) / (from_max - from_min);
    return to_min + (to_max - to_min) * t;
}

extern "C" float ease_in_quad(float t)
{
    return t * t;
}

extern "C" float ease_out_quad(float t)
{
    return t * (2.0f - t);
}

extern "C" float distance_2d(float x1, float y1, float x2, float y2)
{
    float dx = x2 - x1;
    float dy = y2 - y1;
    return sqrtf(dx * dx + dy * dy);
}

Breakdown#

XENON_LIBRARY_INFO#

XENON_LIBRARY_INFO(
    "math_helpers_lib",   // internal name
    "Xenon",              // author
    "Shared math utils",  // description
    "1.0",                // version
    "math_helpers"        // service name
)

This is different from XENON_PLUGIN_INFO:

  • No display name, hero ID, or flags
  • The provides field is set to "math_helpers" — this is the service name that dependent plugins reference
  • The host recognizes this as a library and bridges its exports

Exported Functions#

Every function is extern "C" with a clean name. This is important because:

  1. extern "C" prevents C++ name mangling — the WASM export name matches the function name exactly
  2. The --library build flag uses --export-all, so these functions become WASM exports
  3. The host registers them under lib_math_helpers.* for dependent plugins

No Entry Points#

Library plugins typically don't implement on_render, on_menu, etc. They only export utility functions. The XENON_LIBRARY_INFO macro generates on_get_info which is all the host needs.

The Import Header#

For other plugins to call these functions, you provide an import header at include/xenon/libs/math_helpers.hpp:

#pragma once

extern "C"
{
    __attribute__((import_module("lib_math_helpers"), import_name("lerp")))
    float lib_math_helpers_lerp(float a, float b, float t);

    __attribute__((import_module("lib_math_helpers"), import_name("clamp_f")))
    float lib_math_helpers_clamp_f(float value, float min_val, float max_val);

    __attribute__((import_module("lib_math_helpers"), import_name("remap")))
    float lib_math_helpers_remap(float value, float from_min, float from_max,
                                  float to_min, float to_max);
}

namespace xenon::math
{
    inline float Lerp(float a, float b, float t)
    {
        return lib_math_helpers_lerp(a, b, t);
    }
    inline float Clamp(float value, float min_val, float max_val)
    {
        return lib_math_helpers_clamp_f(value, min_val, max_val);
    }
    inline float Remap(float value, float from_min, float from_max,
                        float to_min, float to_max)
    {
        return lib_math_helpers_remap(value, from_min, from_max, to_min, to_max);
    }
}

The import_module("lib_math_helpers") attribute tells the WASM linker to generate an import from the lib_math_helpers module — which the host bridges to the library's exports at runtime.

Build#

build.bat --library examples\math_helpers_lib.cpp

Output: output/math_helpers_lib.wasm

Warning

You must use --library for library plugins. A standard build only exports lifecycle functions and won't export lerp, clamp_f, etc.

See Also#