Skip to main content
forge-interactions is the generic “press E on a thing” system. You register an interaction definition, place instances of it in the world, and the package handles the prompt, server-side distance gating, rate limiting, and routing the trigger to a handler in another package.

​
Concepts

  • Definition. A stable interact:<name> with a prompt, a max distance, and an outcome that names a handler { pkg, export } plus static data.
  • Instance. A placed occurrence with an instance_id and a world position.
  • Trigger. Calling TriggerInteraction checks distance server-side, then invokes the outcome handler with the data and the caller’s character id.

​
Exports

ExportSignatureReturns
RegisterInteractionRegisterInteraction(def)Result
RegisterInteractionsRegisterInteractions(list)Result
CreateInteractionCreateInteraction(def_id, opts)Result, opts has instance_id, position
DestroyInteractionDestroyInteraction(instance_id)Result
SetEnabledSetEnabled(instance_id, enabled)Result
GetInteractionGetInteraction(def_id)Result
ListInstancesListInstances()Result{ data = { instances } }
TriggerInteractionTriggerInteraction(character_id, instance_id, opts)runs the outcome (distance-gated; pass from_position)
ResetCooldownResetCooldown(instance_id)Result

​
Definition + use

local fint = exports["forge-interactions"]

fint:RegisterInteraction({
  id = "interact:instructor",
  prompt = "Talk to the Instructor",
  distance = 250,
  outcome = {
    handler = { pkg = "forge-quests", export = "StartDialogue" },
    data    = { dialogue = "dlg:instructor" },
  },
})

fint:CreateInteraction("interact:instructor", {
  instance_id = "inst:instructor:" .. cid,
  position    = { x = px, y = py, z = pz },
})
The outcome handler is a { pkg, export } reference, not a raw function, because HELIX serializes export-call arguments and cannot marshal a function across states.

​
Configuration

forge-interactions ships no content; interactions are creator-defined via Config.Interactions or the register exports. Config tunes the distance slack and per-second use cap.