@zilibobi/forge-vfx 2.2.3

package/LICENSE

@@ -0,0 +1,82 @@
+SPDX-License-Identifier: VFX-DL-1.1
+
+Preamble.
+Disclaimer: nothing stated in this preamble is legal advice.
+
+This is a simple license that allows anyone to use the emit module in their Roblox games.
+
+1. You cannot use the module in anything that isn't a Roblox game. For example, it means
+that you cannot create a plugin using this module.
+
+2. You are allowed to use the module commercially in your games.
+
+3. You are free to share the module with other developers so they can use it in their games,
+as long as the license is retained.
+
+4. You can modify and share the module as long as you follow the terms of the license. All
+derivates of the module must have the same license.
+
+5. If you break the terms and conditions of the license, you are required to stop the use and
+distribution of the module immediately.
+
+End of preamble.
+
+VFX Forge Developer License (VFX-DL) Version 1.1
+
+Copyright (c) 2025 zilibobi
+
+1. Definitions.
+   - "Module" means the source code and any compiled form of the Emit Module.
+   - "You" means any individual or organization exercising the rights granted herein.
+   - "Derivative Work" means any work based upon or incorporating the Module.
+   - "Roblox Experience" means a user-facing game or simulation that runs on the
+   Roblox platform, created using Roblox Studio and played via the Roblox client.
+
+2. Grant of Rights.
+   Permission is hereby granted, free of charge, to You to use, reproduce,
+   prepare Derivative Works of, publicly display, publicly perform, sublicense,
+   and distribute the Module, **solely when embedded in the runtime environment of
+   a Roblox Experience** (including playtesting in Roblox Studio), and **not** when
+   loaded by any Roblox Studio plugin or other developer tool, running in any context
+   that has access to API methods or permissions unavailable to runtime scripts within
+   Roblox Experiences (excluding the Roblox Studio command bar feature, when used for
+   the purpose of viewing finished effects). You may distribute the Module or Derivative
+   Work to other developers, provided they use it only within the permitted runtime
+   context described above.
+
+3. Conditions.
+   a. Copyleft.
+       Any Derivative Work, including modified or extended versions of the Module, that
+       You distribute must be licensed under the exact same terms as this VFX-DL.
+   b. Redistribution.
+       You must include a copy of this license text with any distribution of the Module or Derivative Work.
+   c. No Other Contexts.
+       You may not embed, load, or distribute the Module within any Roblox Studio
+       plugin, editor extension, command-line tool, test harness, or any code running
+       under Studio outside of normal game runtime.
+
+4. Disclaimer of Warranty.
+    The Module is provided "AS IS," without warranty of any kind, express or implied,
+    including but not limited to the warranties of merchantability, fitness for a
+    particular purpose, and noninfringement.
+
+5. Limitation of Liability.
+    In no event shall the authors or copyright holders be liable for any claim,
+    damages, or other liability arising from, out of, or in connection with the
+    Module or the use or other dealings in the Module.
+
+6. Termination.
+    If You violate the terms of this License, Your rights under this VFX-DL will
+    terminate automatically. Upon termination, You must cease all use and distribution
+    of the Module and any Derivative Works.
+
+7. Versioning.
+    This license applies to Version 1.0 of the VFX-DL. Future versions may be published
+    by the copyright holder.
+
+8. Commercial use.
+    This License permits commercial use within the scope defined in Section 2.
+
+9. Trademarks and branding.
+    Nothing in this License grants permission to use the trade names, trademarks, service marks,
+    or product names of the Licensor.

package/README.md

@@ -0,0 +1,45 @@
+![Banner](/forge-banner.png)
+
+<div align="center">
+  <a href="https://docs.zilibobi.dev/vfx-forge"><img alt="View Documentation" src="https://img.shields.io/badge/Documentation-View?style=for-the-badge&label=View&color=c4a7e7"></a>
+  <a href="https://discord.gg/Qme9KPN3pF"><img alt="Join Discord" src="https://img.shields.io/discord/1401872327162986626?logo=discord&style=for-the-badge&color=c4a7e7&logoColor=ffffff&label=Join%20Discord"></a>
+</div>
+
+# Emit Module
+
+The is the official repository for the emit module provided by the <a href="https://devforum.roblox.com/t/3867553">VFX Forge</a> Roblox plugin.
+
+## License
+The emit module is licensed under a custom source-available copyleft license which **<mark>only allows usage within Roblox games</mark>**. That said, feel free to contribute and report bugs.
+
+## Installation
+
+#### Wally (Luau)
+
+```sh
+ForgeVFX = "zilibobi/forge-vfx@2.2.3"
+```
+
+#### npm (TypeScript)
+
+```sh
+npm i @zilibobi/forge-vfx@latest
+```
+
+#### Manual
+
+Check the [releases page](https://github.com/zilibobi/forge-vfx/releases/latest) for prebuilt .rbxm files.
+
+## Usage
+
+The module needs to be initialized before emitting any effects.
+After that it is also exposed inside `shared.vfx`.
+
+```luau
+local ReplicatedStorage = game:GetService("ReplicatedStorage")
+
+local vfx = require(ReplicatedStorage.ForgeVFX)
+
+vfx.init()
+vfx.emit(workspace.Effect)
+```

package/out/index.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Result returned from emitting VFX effects
+ */
+export interface EmitResult {
+  /**
+   * Promise that resolves when the effect has finished playing
+   */
+  Finished: Promise<void>;
+}
+
+/**
+ * Initialize the Forge VFX system.
+ */
+export function init(): void;
+
+/**
+ * Clean up and shut down the Forge VFX system.
+ * Destroys all caches and disconnects event handlers.
+ */
+export function deinit(): void;
+
+/**
+ * Emit VFX effects from the provided instances.
+ * Supports ParticleEmitters, Beams, Trails, Models, and tagged effects.
+ * @param instances One or more Roblox instances to emit effects from
+ * @returns Result object with a Finished promise
+ */
+export function emit(...instances: Instance[]): EmitResult;
+
+/**
+ * Emit VFX effects with a scale multiplier.
+ * @param scale Scale multiplier for the effect
+ * @param instances One or more Roblox instances to emit effects from
+ * @returns Result object with a Finished promise
+ */
+export function emit(scale: number, ...instances: Instance[]): EmitResult;
+
+/**
+ * Emit VFX effects with a specific render depth.
+ * @param depth Render priority depth for the effect
+ * @param instances One or more Roblox instances to emit effects from
+ * @returns Result object with a Finished promise
+ */
+export function emitWithDepth(
+  depth: number,
+  ...instances: Instance[]
+): EmitResult;
+
+/**
+ * Enable a VFX instance.
+ * For ParticleEmitters and Beams, sets the Enabled property directly.
+ * For other instances, sets the "Enabled" attribute.
+ * @param obj The instance to enable
+ */
+export function enable(obj: Instance): void;
+
+/**
+ * Disable a VFX instance.
+ * For ParticleEmitters and Beams, sets the Enabled property directly.
+ * For other instances, sets the "Enabled" attribute.
+ * @param obj The instance to disable
+ */
+export function disable(obj: Instance): void;
+
+/**
+ * Cache attributes for a VFX instance and its descendants.
+ * Strips attributes from instances and stores them in memory for faster access.
+ * Only works on the client and for instances inside ReplicatedStorage.
+ * @param obj The instance whose descendant attributes to cache
+ */
+export function cacheAttributes(obj: Instance): void;
+
+/**
+ * Restore previously cached attributes back onto instances.
+ * Only works on the client.
+ * @param obj The instance whose descendant attributes to restore
+ */
+export function restoreAttributes(obj: Instance): void;

package/out/init.luau

@@ -0,0 +1 @@
+return require(script.ForgeVFX)

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@zilibobi/forge-vfx",
+  "version": "2.2.3",
+  "description": "The official emit module from the VFX Forge plugin used to emit visual effects in-game.",
+  "main": "out/init.lua",
+  "types": "out/index.d.ts",
+  "type": "commonjs",
+  "files": [
+    "out"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zilibobi/forge-vfx.git"
+  },
+  "homepage": "https://docs.zilibobi.dev/vfx-forge/module/installation/",
+  "author": "zilibobi",
+  "license": "VFX-DL-1.1",
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check index.d.ts",
+    "format": "biome format --write index.d.ts",
+    "format:check": "biome format index.d.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.8",
+    "@rbxts/compiler-types": "^3.0.0-types.0",
+    "@rbxts/types": "^1.0.891",
+    "roblox-ts": "^3.0.0",
+    "typescript": "^5.9.3"
+  }
+}