interactKit

Version 1.3.2 — everything a player can walk up to and use: doors, switches, locks, containers, a barricade and invisible trigger zones, with "Press E to open" prompts that work on keyboard, gamepad and a phone's touch screen. For adventure, horror, puzzle and shooter games, and multiplayer from the ground up.

• Interactable — put it on anything. A prompt appears when the player is close enough (trigger = "proximity") or looking at it (trigger = "look") within range. holdTime = 0 is a quick press; above 0 the player holds while a fill-up runs. One interact button everywhere: E, the gamepad's west face button (X on Xbox, square on PlayStation, Y on Switch), or the on-screen Interact button on a phone.
• TriggerVolume — an invisible box or sphere that reports enter, exit and stay for every player, and can open, close or toggle what it is wired to.
• 7 doors, 7 switches, 3 locks, 4 containers, a barricade, 5 prompt styles, 3 looks — listed below.

Everything works the same way: a kind field picks the variant, a look field picks the style, targets wires it to other things by name, and one field picks the prompt style. Swapping a sliding door for a portcullis is changing kind = "sliding" to kind = "portcullis".

Install

Search ZeroMind for interactKit and install interactKit.package (or zero zeromind installAsset <guid> in the engine shell). It lands at /source/interactKit.package and brings its two dependencies with it, controlsKit and juiceKit (under /source/deps/). Keys, keycards, coins and gems are interactKit's own, so nothing else is needed.

Reach interactKit by its package name, require("~interactKit.api"), and its components with Interact.component("Door"): both work wherever the package is installed, at the top of /source or under deps/ when another kit depends on it.

Quick start

A new world's scenes/main.scene/build.luau already has a ground and a player. Add these lines at the end of its content() function:

    -- ── interactKit quick start ─────────────────────────────────────────
    local Interact = require("~interactKit.api")

    -- a door in a short wall, and a lever beside it that opens it
    Interact.spawn("door.hinged", { 0, 0, 6 }, { name = "FrontDoor", synced = true, yaw = 180,
        look = "wood", fields = { wall = 1.5 } })
    Interact.spawn("switch.lever", { 2.6, 0, 5 }, { synced = true, yaw = 180, look = "wood",
        fields = { targets = { "FrontDoor" } } })

    -- a locked chest, and the key that opens it (each player picks up their own)
    Interact.spawn("container.chest", { -3, 0, 6 }, { synced = true, yaw = 180, look = "cartoon",
        fields = { loot = "coin", lootCount = 8 }, lock = { kind = "key" } })
    Interact.spawnKey({ -3, 0, 3.5 })

Press Play. Walk to the lever on the right and press E: the door swings open and you can walk through. The chest on the left says Locked — Needs a key; walk over the key, come back, and it says Unlock. Press E and coins spill out.

synced = true makes each thing one shared object, so every player sees the same door. Without it every player gets their own copy.

No code at all: add interactKit.Door (or Switch, Container, Barricade, TriggerVolume, Interactable, Lock) to an entity in the editor and set kind, look and targets in the inspector. A device works on its own; add an Interactable beside it only to change its prompt (range, look-at, hold time, style).

The gallery scene (interactKit.gallery) has every kind, look and prompt style laid out, labelled and usable.

Styles

Doors — interactKit.Door, kind =

Moving parts carry their colliders: an open door is a doorway you walk through, a closed one is a wall.

Switches — interactKit.Switch, kind =

Locks — interactKit.Lock, kind =

A Lock sits beside any Door, Container or Switch on the same entity.

Containers — interactKit.Container, kind =

chest (lid swings up), crate (lid pops off), locker (door swings open), barrel (lid flips). The first open spills lootCount items of loot on the ground in front: coin, gem, key or keycard, with a colour as gem:red or keycard:blue (older pickupsKit look names such as fantasy_ruby are read as the nearest kind). Each piece goes to the first player to walk over it.

Items — interactKit.Item, kind =

Walk over one to pick it up. perPlayer (the default for keys) means every player takes their own copy, and each sees only their own disappear; shared items go to whoever is first. item gives a different item name, amount more than one, respawn brings it back. Every player's counts are kept in interactKit's own inventory, shared by the host, and shown in a small strip in the top-left corner of each player's screen once they carry something.

Barricade — interactKit.Barricade

Hold to nail boards across an opening one at a time; once full, hold to tear them down. It blocks the way while any board is up.

Prompt styles — promptStyle =

The whole world, one field: put interactKit.InteractSettings on any one entity and set its promptStyle (from code: Interact.setPromptStyle("ring")). One object, one field: promptStyle on its Interactable; default follows the world setting. Both apply at once, also while playing.

Looks — look =

Every door, switch, lock badge, container and the barricade comes in all three.

Wiring without code

Every Switch, Door, Container, Barricade, TriggerVolume and plain Interactable has targets: a list of entity names (or ids). What they are told:

Doors and containers take open, close, toggle; switches take on / open, off / close, toggle; anything with a Lock takes unlock and lock. playerOperable = false on a door means only wiring moves it (a portcullis behind a crank).

API

local Interact = require("~interactKit.api") — the stable public surface, together with the components below. The other modules in the package are internal.

Constants

Building

Using and wiring

Events

Reading state

Settings

Keys, keycards and effects

Already counting keys somewhere else (your own inventory, or pickupsKit installed at the top of your world)? Point the locks at it:

local Pickups = require("~pickupsKit.api")      -- your world's own copy
Interact.setInventory({
	count = function(peer, item) return Pickups.get("p" .. peer, item) end,
	give = function(peer, item, n) Pickups.add("p" .. peer, item, n) end,
})

Your own devices

Make anything a usable device with the same prompts, networking and locks:

Interact.registerDevice(entity.id, {
	family = "custom", kind = "bell", comp = myComponentPublic,
	defaults = { label = "Ring", range = 3 },
	status = function(peer) return { label = "Ring the bell" } end,
	handle = function(peer, verb, args)        -- runs on the owner
		if verb == "use" then myComponentPublic.rung += 1; return true end
		return false, "unknown verb"
	end,
	signal = function(action, args) return true end,   -- optional: wiring
})

unregisterDevice(id, record), registerInteractable(id, comp) / unregisterInteractable(id, comp), registerLock(id, { isLocked, setLocked, describe(peer), tryUnlock(peer, args) }) / unregisterLock(id, record). ensureHud() makes sure this peer's prompt HUD exists in play (devices call it for you).

Components

Set a state field in the editor for the starting state (a door that starts open, a barricade that starts boarded).

Multiplayer

• The owner decides. Any player may ask; the peer that owns the entity (the host, for scene objects) checks reach, the lock, and that the thing is still in the state the player saw, then writes the shared state. Every player animates from it, so all see the same door, lever, chest or barricade, late joiners included.
• Two players, one handle. Requests carry the state the player saw, so two players pulling the same lever at once flip it once. Holds (valve, crank, barricade, exclusive hold-to-use) are claimed by one player at a time; the other sees "In use by another player", and a claim lapses when its player goes quiet.
• Keys belong to the player who picked them up. The owner checks the count of the player who asked, so a locked door opens for the player holding the key and refuses the one who isn't.
• Effects play on every machine from the shared state change; nothing extra is sent. Channels: ik:req, ik:res, ik:evt.

Tests

tools.use("tests", "run", "interactKitTests") in edit mode — 85 tests. They cover every public call of interactKit.api (one test fails if a public call is added without a test), every kind in every look, kind swaps, wiring and every switch, per-player keys and keycards, items (per player, shared, out of reach, respawning) and the shared inventory, combination locks, loot, the barricade, trigger volumes, hold claims, simultaneous requests and remote players (stand-in bodies whose requests go through the real network handler), prompt styles and the code pad. Guard tests fail if any code reaches a dependency by folder path, adds a pickupsKit component, or times anything with CPU time, and if a taken item rebuilds or respawns its parts, reappears for the player who took it, or shows again after that player's own repeated grab.

The README quick start was played as written in a world scene holding only it: the lever opens the door, walking over the key counts it, the chest says Locked, then Unlock, and opens, and the spilled coins are collected. The gallery has been booted in a browser, where it comes up on the gallery.

Known limits

None known. A limit is listed here only when there is an open public issue a reader can look up.

How it behaves

Design choices rather than limits:

• The prompt focuses one thing at a time: looking at something in range beats being nearest to something else.
• Codes are digits only, up to 8.
• Doors swing one way, away from the side they face, and do not push players aside while closing.
• Doors, switches and the rest are built from primitive shapes. Their parts are rebuilt on every machine from kind and look and never saved into a scene.
• In edit mode things snap to their state; they animate in play.

Changes

• 1.3.2 — Faster with many usable things. Each frame the prompt HUD merged the settings and asked the status of every usable thing in the world, however far away; with a few hundred (a farm with a prompt per plant) that cost about 5 ms a frame. It now remembers how far each thing can be in focus and skips the far ones with one distance check, so the cost follows what is near the player. Prompts, focus and ranges are unchanged.
• 1.3.1 — Fixed: picking anything up made the game heavier and heavier. A taken item rebuilt all its parts every frame on every player's machine; because they hang under a shared object, that also flooded the network, so a second player fell further behind and saw doors open late or never, and could be told "already taken" for their own key. Items now build their shape once and hide with a single change; a taken item costs a clock check per frame. The player who walks over an item sees it go at once, and their own repeated grab never brings it back. The carried-items strip re-reads the inventory a few times a second instead of every frame. Two-player checks through the kit's network handler: each player keeps their own key, the key door opens for the holder and refuses the one without, a chest two players open in the same frame opens once, and every coin goes to exactly one player.
• 1.3.0 — Fixed: in a world with only interactKit installed, walking over the quick start's key did nothing, because the key was a pickupsKit pickup and pickupsKit's components cannot load from /source/deps/. Keys, keycards, coins and gems are now interactKit's own Item component, counted per player in interactKit's own shared inventory; containers spill Items; each player sees what they carry in a strip at the top left once they carry something. interactKit no longer depends on or names pickupsKit, so installing it brings only controlsKit and juiceKit (Interact.pickups is gone; setInventory connects any other inventory). New Interact.items, catalog family item. Gallery relaid out so every label reads from the spawn point, in the editor (which now opens on that view) and in play, with no label under a station's own prompt; its key and keycards are Items and the pickupsKit counter panel is gone.
• 1.2.2 — Web build hardening. Every timer (hold claims, auto-close, button pop-up, messages) now runs on getTime(), the wall clock, instead of os.clock(), which is CPU time and drifts in the browser — and would disagree between a desktop host and a web player. controlsKit's glyphs load on first use, so a dependency still downloading in a web build cannot take the kit down; prompts draw a plain lettered keycap until it arrives.
• 1.2.1 — Fixed: with only interactKit installed, its dependencies land under /source/deps/, where the folder paths it used (@root::controlsKit.prompts, "interactKit.Door") did not reach them. Dependencies are now loaded by package name (~controlsKit.prompts) and components by resolved type (Interact.component("Door"), new). The quick start uses require("~interactKit.api").
• 1.2.0 — Interact.spawnKey (keys and coloured keycards without knowing pickupsKit item names), so the quick start needs only interactKit. Full API reference. Tests cover every public call (68).
• 1.1.0 — InteractSettings: the world's prompt style in one field. Fixed a turned airlock's halves blocking its doorway; the bookcase opens to 90°. Keyboard, gamepad and touch verified for press and hold.
• 1.0.0 — first release.

Dependencies

Installed with interactKit:

• controlsKit 1.0.1 — button-prompt glyphs.
• juiceKit 1.2.2 — open / close feedback.

Not a dependency any more: pickupsKit. Up to 1.2.2 interactKit used its pickups for keys and loot, but an install puts pickupsKit under /source/deps/, where its Pickup components cannot load their own code, so keys never counted in a fresh world. interactKit's own Item replaces them, and interactKit no longer names pickupsKit anywhere, so an install does not bring it along. To have pickupsKit's counters open interactKit locks in a world that has pickupsKit installed at the top, see setInventory under API.