macros Plugin

Use xray16/plugins/macros to fold compile-time helpers from xray16/macros.

The helper module has a real Node/Jest runtime, so source code can import it normally. During a game build, this plugin removes the import and replaces supported helper usage with Lua-friendly output.

{
  "name": "xray16/plugins/macros",
  "buildTimestamp": true,
  "fileName": true,
  "dirName": true,
  "castHelpers": true,
  "inlineHints": true
}

All options default to true. Token-driven options do nothing until the matching helper appears in source.

Configuration

buildTimestamp

Prepends a generation comment to each emitted Lua file.

-- Generated by xrf util at: <build time>

local ____exports = {}

Disable this when you need byte-for-byte reproducible output.

fileName / dirName

Replaces $filename and $dirname with compile-time string literals.

$filename becomes the source file name without an extension. $dirname becomes the containing directory name.

import { $dirname, $filename } from "xray16/macros";

export const meta = [$filename, $dirname];

For scripts/quests.ts, this emits values equivalent to {"quests", "scripts"}.

castHelpers

Expands Lua table interop helpers and nil checks.

• $fromObject, $fromArray, $fromLuaArray, and $fromLuaTable are unwrapped to their single argument.
• $isNil(value) becomes value == nil.
• $isNotNil(value) becomes value ~= nil.

import { $fromObject, $isNil, $isNotNil } from "xray16/macros";

export function run(value: unknown): unknown {
  const casted = $fromObject<number>(value);

  return [$isNil(casted), $isNotNil(casted), casted];
}

A cast helper called with anything other than one argument reports: Invalid transformer call, expected function to have exactly 1 argument.

inlineHints

Unwraps $inline and $noInline to their single argument when the inline plugin has not consumed them.

These hints are owned by the inline plugin, which forces or suppresses inlining for the wrapped target (see the inline plugin page). In the recommended plugin order, inline runs before macros and consumes the hints. This option exists for builds that run the macros plugin without the inline plugin: the hints become plain calls instead of emitted $ identifiers.

Limitations

• $ tokens are not valid Lua identifiers. Keep a feature enabled while its helper is still used.
• buildTimestamp uses the build machine clock, so output differs across builds.