profile

Binding profile registry — bundles of named actions / axes / chords that can be loaded from @builtin::profiles.<name> Luau modules or saved as JSON under /zero/profiles/<name>.json. Activating a profile reconfigures Zin.actions / Zin.axes / Zin.chords in one shot. The active profile is per-client session state held in memory — each session resolves it fresh from the device-appropriate default (or an explicit activate), so it is never written to the world source tree.

This is the persistence and activation layer for those three registries; Zin.map.activate applies a materialized map through it. A scheme is authored as an .inputMap of .inputBinding controls and goes live through Zin.scheme — man topics/input covers that path.

Exports

• M.register(name: string, profile: any) -> (boolean, string?) — validate + register a profile descriptor.
• M.load(name: string) -> (boolean, any?) — load + register a profile from @builtin::profiles.<name> or /zero/profiles/<name>.json.
• M.activate(name: string, opts: ActivateOpts?) -> (boolean, string?) — apply a profile's sections + set the active name for this session.
• M.current() -> string? — active profile name for this session, or nil.
• M.get(name: string?) -> any? — descriptor for the active profile or the named profile.
• M.ensureActive(fallback: string?) -> (boolean, string?) — bootstrap helper for controllers.
• M.save(name: string, opts: SaveOpts?) -> (boolean, string?) — capture current Zin.actions / Zin.axes / Zin.chords to JSON.
• M.delete(name: string) -> (boolean, string?) — remove a user profile's JSON file (built-ins refused).
• M.export(name: string, vfsPath: string) -> (boolean, string?) — write a serializable JSON snapshot to any VFS path.
• M.import(vfsPath: string, opts: ImportOpts?) -> (boolean, string) — read + register a profile JSON from any VFS path.
• M.list() -> { string } — sorted union of built-in + user profile names.
• M.onChange(cb: ChangeCallback) -> number — subscribe to activation / re-register events; returns a handle.
• M.off(handle: number) — drop a subscription.
• M._reset() — test-only: clear in-memory state.

Types:

• Profile = { name, description?, actions?, axes?, chords?, intentional_pairs? }
• ActivateOpts = { reactivate: boolean? }
• SaveOpts = { description: string?, overwrite: boolean? }
• ImportOpts = { overrideName: string?, activate: boolean? }
• ChangeCallback = (string, any) -> ()

Usage

local Profile = require("@builtin::modules.zinput.profile")

Profile.register("my-bindings", {
    name = "my-bindings",
    actions = { jump = { context = "default", bindings = { { kind = "key", code = "Space" } } } },
})
Profile.activate("my-bindings")

local h = Profile.onChange(function(name) print("active:", name) end)
Profile.off(h)

Notes

• Built-in profiles ship as Luau modules at @builtin::profiles.<name> and can include functions (gate, curve). User profiles are pure JSON at /source/profiles/<name>.json — function fields are dropped on save.
• Activation is no-op when the requested name is already active unless opts.reactivate = true.
• save / export VFS writes use the bare /source/... mount — the /zero/... prefix is read-only and silently drops writes.
• The conflicts module's _setPersistFn hook is wired here so mark/unmark of intentional pairs persists into the active user profile automatically.