forge-instancing creates managed instances (a dungeon, a house, a private arena) on top of HELIX’s
world isolation. You register a template, create instances from it, and move characters in and out
with access control.
Concepts
- Template. A stable
instance:<name> describing how to build an instance and where to send a
character on exit (a mandatory exit.fallback).
- Provider. How isolation is achieved.
offset (default, production-proven Z-stacking) or
dimension (gated until Studio-verified).
- Residue. The only persisted state: if a character disconnects inside an instance, a residue row
lets them be healed back to the template’s exit fallback on reconnect, so no one is ever stranded.
Exports
Templates & instances
| Export | Signature |
|---|
RegisterTemplate / RegisterTemplates | register definitions |
CreateInstance | CreateInstance(template_id, opts) |
DestroyInstance | DestroyInstance(instance_id) |
GetInstance / ListInstances | query |
EjectAll | EjectAll(instance_id) |
Membership & access
| Export | Signature |
|---|
Enter | Enter(character_id, instance_id) |
Leave | Leave(character_id) |
Invite / AcceptInvite | invite flow (TTL) |
SetAccessList | SetAccessList(instance_id, list), open|invite|list|faction|owner |
GetOrCreateOwned | GetOrCreateOwned(character_id, template_id), a per-owner instance |
GetMembers / IsInside | query membership |
local fi = exports["forge-instancing"]
local inst = fi:GetOrCreateOwned(cid, "instance:player_house")
fi:Enter(cid, inst.data.instance_id)
Configuration
forge-instancing ships no content; templates are creator-defined. The provider defaults to
offset; Config.Dimensions.Enabled stays false until the dimension provider is Studio-verified.
v0.1 implements the full logic with unit coverage. Live in-world walk (a cooked interior shell
asset and example glue) and the dimension provider are deferred.
