Forge

A window manager for Vide — rules for what may be open, when. Forge owns no rendering, no popups, no notifications. It just decides whether a window is allowed to open, and gives you a reactive Vide.Source<boolean> per window to bind however you like.

⚠️ Upgrading from Forge < 0.5.0?

Forge 0.5.0 is a complete rewrite with a different API and no code shared with the old "app manager" version (decorators, @App, @ChildApp, context providers, etc. are all gone).

If you're using an older Forge and aren't ready to migrate, pin the old version:

• npm: @rbxts/[email protected] (last pre-rewrite release)
• Repo: Loner1536/Forge at tag v0.4.6 (last pre-rewrite commit in this git history — 0.4.7/0.4.8 were published without a matching commit)

There is no automated migration path — the new API is small enough to rewrite by hand once you read below.

Install

npm install @rbxts/forge

Usage

import Forge from "@rbxts/forge";

const forge = new Forge({
	windows: {
		hud: { defaults: { open: true }, persistent: true },
		shop: { hotkey: Enum.KeyCode.B },
		buyPrompt: { parent: "shop" },
	},
	exclusive: {
		main: ["shop", "inventory"],
	},
});

forge.shop.open();
forge.shop.toggle();
Visible={forge.shop.state}

Window names, and every parent/closes/blockedBy/lane reference to another window, are typed against the config itself — typos are compile errors and everything autocompletes.

Rules per window

• parent — closing (or displacing) the parent closes this window too, recursively.
• closes — opening this window force-closes these, regardless of exclusivity.
• blockedBy — this window refuses to open while any of these are open.
• defaults.open — starting state override (e.g. a HUD that starts open).
• persistent — survives closeAll().
• hotkey — one bind or several: a Enum.KeyCode, or { hold, press } for hold-combos (e.g. controller shoulder + face button). Built on Roblox's Input Action System.
• onOpen / onClose — side-effect callbacks.

Exclusivity lanes

exclusive: {
	main: ["shop", "inventory"],               // shorthand, mode defaults to "displace"
	modal: { mode: "block", members: ["shop", "settings"] },
}

• "displace" (default) — opening a lane member closes whichever other member is open.
• "queue" — opening a lane member while another is open queues it; it opens automatically once the lane frees up.
• "block" — opening a lane member while another is open fails (open() returns false).

Handle API

Every registered window gets:

forge.<name>.open(force?)  // returns false if blocked/queued (unless force)
forge.<name>.close()
forge.<name>.toggle()
forge.<name>.state         // Vide.Source<boolean> — pass, don't call, to stay reactive

Plus manager-level methods:

forge.closeAll()               // closes everything except persistent windows
forge.reset()                  // restores every window to its defaults
forge.attachHotkeys(parent)    // binds all `hotkey`s under an Instance, returns a cleanup fn

License

MIT