@rbxts/vfx-forge 2.2.2

package/out/index.d.ts

@@ -0,0 +1,341 @@
+/**
+ * Main API for Forge VFX.
+ *
+ * @example
+ *
+ * ```ts
+ * import vfx from "@rbxts/forge-vfx";
+ * vfx.init();
+ *
+ * const env = vfx.emit(Workspace.Effect);
+ * env.Finished.finally(() => print("Effect finished!"));
+ * ```
+ */
+export interface Api {
+	/**
+	 * Caches attributes for a VFX object. Client-side only. Use with
+	 * `restoreAttributes` to save/restore original attribute values.
+	 *
+	 * @param object - Instance whose attributes to cache.
+	 */
+	cacheAttributes: (object: Instance) => void;
+
+	/** Internal caches used by the VFX system. */
+	caches: ApiCaches;
+
+	/**
+	 * Clean up and shut down Forge VFX. Destroys all caches, cleans up scopes,
+	 * deinitializes all modules, and disconnects event handlers.
+	 */
+	deinit: () => void;
+
+	/**
+	 * Disables a ParticleEmitter, Beam, or VFX object.
+	 *
+	 * @param object - Instance to disable.
+	 */
+	disable: (object: Instance) => void;
+
+	/**
+	 * Emit VFX effects from the provided instances. Supports ParticleEmitters,
+	 * Beams, Trails, Meshes, Beziers, Spin Models, Shockwaves, and all other
+	 * Forge VFX effect types.
+	 *
+	 * @example
+	 *
+	 * ```ts
+	 * // Basic emit
+	 * vfx.emit(Workspace.Effect);
+	 *
+	 * // Emit multiple effects
+	 * vfx.emit(Effects.Explosion, Effects.Wind);
+	 *
+	 * // Emit with 2x scale
+	 * vfx.emit(2, Workspace.Effect);
+	 * ```
+	 */
+	emit: {
+		/**
+		 * Emit effects at default scale (1).
+		 *
+		 * @param instances - One or more Roblox instances to emit effects from.
+		 * @returns Environment with a Finished promise that resolves when
+		 *   complete.
+		 */
+		(...instances: Array<Instance>): EmitEnvironment;
+		/**
+		 * Emit effects at a specified scale.
+		 *
+		 * @param scale - Scale multiplier for the effects.
+		 * @param instances - One or more Roblox instances to emit effects from.
+		 * @returns Environment with a Finished promise that resolves when
+		 *   complete.
+		 */
+		(scale: number, ...instances: Array<Instance>): EmitEnvironment;
+	};
+
+	/**
+	 * Emit VFX effects with specified render depth ordering.
+	 *
+	 * @param depth - Render priority depth for the emitted effects.
+	 * @param instances - One or more Roblox instances to emit effects from.
+	 * @returns Environment with a Finished promise that resolves when complete.
+	 */
+	emitWithDepth: (depth: number, ...instances: Array<Instance>) => EmitEnvironment;
+
+	/**
+	 * Enables a ParticleEmitter, Beam, or VFX object.
+	 *
+	 * @param object - Instance to enable.
+	 */
+	enable: (object: Instance) => void;
+
+	/**
+	 * Initializes the VFX system. Sets up collision groups on server,
+	 * initializes caches and all VFX modules.
+	 *
+	 * @param parameters - Optional initialization parameters.
+	 */
+	init: (parameters?: object) => void;
+
+	/**
+	 * Restores previously cached attributes for a VFX object. Client-side only.
+	 *
+	 * @param object - Instance whose attributes to restore.
+	 */
+	restoreAttributes: (object: Instance) => void;
+
+	/** Current active scope stack for cleanup management. */
+	scope: Array<unknown>;
+
+	/** Whether the VFX system has been initialized. */
+	setup: boolean;
+}
+
+/** Internal cache storage for the VFX system. */
+export interface ApiCaches {
+	/** Shared part cache for pooling reusable effect parts. */
+	shared_part: ObjectCache;
+}
+
+/**
+ * Configuration parameters for object caching. Controls pooling behavior for
+ * VFX instances.
+ */
+export interface CacheParameters {
+	/**
+	 * Seconds before excess cached items are cleaned up.
+	 *
+	 * @default undefined
+	 */
+	excess_lifetime?: number;
+	/**
+	 * Callback invoked when an item is returned to the cache.
+	 *
+	 * @param item - The cache item being freed.
+	 */
+	on_free?: (item: Item) => void;
+	/**
+	 * Initial/target size of the cache pool.
+	 *
+	 * @default undefined
+	 */
+	size?: number;
+}
+
+/**
+ * Internal service managing effect emission and lifecycle.
+ *
+ * @internal
+ */
+export interface EffectsService {
+	/** Shuts down the effects service and cleans up resources. */
+	deinit: () => void;
+	/**
+	 * Emits effects with specified depth ordering.
+	 *
+	 * @param depth - Render priority depth.
+	 * @param instances - Instances to emit effects from.
+	 */
+	emit: (depth: number, ...instances: Array<Instance>) => EmitEnvironment;
+	/**
+	 * Emits effects from a folder's children, parenting them to the target first.
+	 *
+	 * @param folder - Folder containing effects to emit, or undefined.
+	 * @param targetParent - Instance to parent the folder's children to.
+	 * @param depth - Render priority depth.
+	 */
+	emitFromFolder: (folder: Folder | undefined, targetParent: Instance, depth: number) => EmitEnvironment;
+	/**
+	 * Emits nested effects from a part's children.
+	 *
+	 * @param part - Instance whose children to emit.
+	 * @param depth - Render priority depth.
+	 */
+	emitNested: (part: Instance, depth: number) => EmitEnvironment;
+	/**
+	 * Emits effects from an EmitOnFinish folder. Delegates to emitFromFolder.
+	 *
+	 * @param emitOnFinish - EmitOnFinish folder, or undefined.
+	 * @param targetParent - Instance to parent effects to.
+	 * @param depth - Render priority depth.
+	 */
+	emitOnFinish: (emitOnFinish: Folder | undefined, targetParent: Instance, depth: number) => EmitEnvironment;
+	/**
+	 * Initializes the effects service.
+	 *
+	 * @param api - Reference to the main API.
+	 */
+	init: (api: Api) => void;
+	/**
+	 * Prepares a named folder for deferred emission by unparenting it.
+	 *
+	 * @param obj - Instance to search for the folder.
+	 * @param folderName - Name of the folder to prepare.
+	 * @param scope - Scope for cleanup.
+	 */
+	prepareEmitFolder: (obj: Instance, folderName: string, scope: Scope) => Folder | undefined;
+	/**
+	 * Prepares the EmitOnFinish folder. Delegates to prepareEmitFolder.
+	 *
+	 * @param obj - Instance to search for EmitOnFinish.
+	 * @param scope - Scope for cleanup.
+	 */
+	prepareEmitOnFinish: (obj: Instance, scope: Scope) => Folder | undefined;
+}
+
+/**
+ * Result returned from emitting VFX effects. Contains a promise for tracking
+ * effect completion.
+ *
+ * @example
+ *
+ * ```ts
+ * const env = vfx.emit(Workspace.Effect);
+ * env.Finished.finally(() => print("Effect finished!"));
+ * ```
+ */
+export interface EmitEnvironment {
+	/**
+	 * Promise that resolves when all emitted effects have finished playing. Use
+	 * `:finally()` or `:andThen()` to run code after completion.
+	 */
+	Finished: Promise<void>;
+}
+
+/**
+ * Object cache for pooling and reusing VFX instances. Extends the base Cache
+ * with additional tracking for part-based effects. MeshPart and Union effects
+ * cannot be reasonably pooled, so their CFrames are not updated in bulk which
+ * may impact performance with heavy emission.
+ */
+export interface ObjectCache extends Cache {
+	/** Current number of items in the cache. */
+	amount: number;
+	/** Map of keys to their corresponding cache items. */
+	item_map: Map<unknown, Item>;
+	/** Cache configuration parameters. */
+	params: CacheParameters;
+	/** Parent instance for cached items. */
+	parent?: Instance;
+	/** Whether this cache is in part mode for bulk CFrame updates. */
+	part_mode: boolean;
+	/** Reference instance used as template for creating new cache items. */
+	ref: Instance;
+	/** Number of items to restore to the pool. */
+	restore_amount: number;
+	/** Scope for cleanup management. */
+	scope: Array<unknown>;
+	/** Array of unused items available for reuse. */
+	unused: Array<Item>;
+}
+
+/**
+ * Scope for managing VFX cleanup and lifecycle. Scopes hold cleanup functions,
+ * connections, and tweens that need to be cleaned up when effects finish.
+ * Implements array semantics for storing cleanup handlers.
+ */
+export interface Scope extends Array<unknown> {
+	/**
+	 * Render priority depth for this scope. Used to determine the order of
+	 * render step bindings.
+	 */
+	depth: number;
+	/** Reference to the effects service for this scope. */
+	effects: EffectsService;
+}
+
+/**
+ * Internal representation of a cached item.
+ *
+ * @internal
+ */
+interface Item {
+	/** Unique key identifying this item in the cache. */
+	key: unknown;
+	/** Timestamp when item was added to cache. */
+	added: number;
+	/** Number of active references to this item. */
+	dependents: number;
+	/** The actual Roblox instance being cached. */
+	value: Instance;
+}
+
+/**
+ * Base cache class for pooling Roblox instances. Used internally to reduce
+ * instantiation overhead for VFX effects.
+ */
+declare class Cache {
+	/**
+	 * Destroys the cache and all cached items. Call during cleanup to prevent
+	 * memory leaks.
+	 */
+	public destroy: () => void;
+	/**
+	 * Returns an item to the cache pool for reuse.
+	 *
+	 * @param key - Key of the item to free.
+	 */
+	public free: (key: unknown) => void;
+	/**
+	 * Retrieves an item from the cache, creating one if needed.
+	 *
+	 * @param key - Key to retrieve or create.
+	 * @returns The cached instance.
+	 */
+	public get: (key: unknown) => Instance;
+	/**
+	 * Checks if an item exists in the cache.
+	 *
+	 * @param key - Key to check.
+	 * @returns True if the key exists in the cache.
+	 */
+	public has: (key: unknown) => boolean;
+	/**
+	 * Retrieves an item without creating it if missing.
+	 *
+	 * @param key - Key to look up.
+	 * @returns The cached instance, or undefined if not found.
+	 */
+	public peek: (key: unknown) => Instance | undefined;
+
+	/**
+	 * Creates a new cache.
+	 *
+	 * @param ref - Template instance to clone when creating new items.
+	 * @param parent - Optional parent for cached instances.
+	 * @param parameters - Optional cache configuration.
+	 */
+	constructor(ref: Instance, parent?: Instance, parameters?: CacheParameters);
+}
+
+/**
+ * Forge VFX - An advanced custom VFX system for Roblox.
+ *
+ * Supports 12+ effect types including particles, beams, trails, meshes, bezier
+ * curves, shockwaves, spin models, screen effects, and camera shake.
+ *
+ * @see https://docs.zilibobi.dev/vfx-forge/
+ */
+declare const VfxForge: Api;
+export default VfxForge;

package/out/init.luau

@@ -0,0 +1,279 @@
+-- The license is placed inside a string in order for it to be preserved when the code is decompiled
+-- Even if the engine retains the entire string in memory, it's only around 3.5kB
+local _ = [[
+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.
+]]
+
+local RunService = game:GetService("RunService")
+local CollectionService = game:GetService("CollectionService")
+local ReplicatedStorage = game:GetService("ReplicatedStorage")
+
+local logger = require("@mod/logger")
+local utility = require("@mod/utility")
+local attributes = require("@mod/attributes")
+
+local Sound = require("@vfx/sound")
+local Bezier = require("@vfx/bezier")
+local Lightning = require("@vfx/lightning")
+local CameraShake = require("@vfx/camera_shake")
+local ShockwaveRing = require("@vfx/shockwave_ring")
+local ShockwaveLine = require("@vfx/shockwave_line")
+local ShockwaveDebris = require("@vfx/shockwave_debris")
+
+local caches = require("@srv/caches")
+local effects = require("@srv/effects")
+local texture_loader = require("@srv/texture_loader")
+local enabled_effects = require("@srv/enabled_effects")
+
+local PluginContext = utility.PLUGIN_CONTEXT
+local ServerContext = utility.SERVER_CONTEXT
+
+type params = {}
+
+local api = {}
+
+api.scope = {}
+api.setup = false
+
+function api.init(params: params?)
+  if api.setup then
+    return
+  end
+
+  if ServerContext then
+    task.spawn(function()
+      local done = false
+      local tries = 0
+
+      local lastErr
+
+      repeat
+        tries += 1
+
+        local ok, err = pcall(utility.setCollisionGroups, utility.COLLISION_GROUPS)
+
+        done = ok
+        lastErr = err
+
+        if not done then
+          task.wait(tries)
+        end
+      until done or tries >= 5
+
+      if not done then
+        logger.warn(
+          `couldn't register necessary collision groups after {tries} tries with the last error being: {lastErr}`
+        )
+      end
+    end)
+  end
+
+  api.setup = true
+
+  if RunService:IsServer() and not PluginContext then
+    return
+  end
+
+  api.caches = caches.init(api.scope)
+
+  shared.vfx = api
+
+  -- init services
+  effects.init(api)
+
+  texture_loader.init(api.scope)
+  enabled_effects.init(api.scope, api.caches.shared_part, effects)
+
+  -- init effects
+  Sound.init()
+  CameraShake.init()
+
+  Bezier.init(api.caches.shared_part)
+  Lightning.init(api.caches.shared_part)
+  ShockwaveRing.init(api.caches.shared_part)
+  ShockwaveLine.init(api.caches.shared_part)
+  ShockwaveDebris.init(api.caches.shared_part)
+end
+
+function api.deinit()
+  if not api.setup then
+    return
+  end
+
+  api.setup = false
+
+  shared.vfx = nil
+
+  if RunService:IsServer() and not PluginContext then
+    return
+  end
+
+  utility.cleanupScope(api.scope)
+
+  effects.deinit()
+
+  Sound.deinit()
+  Bezier.deinit()
+  Lightning.deinit()
+  CameraShake.deinit()
+  ShockwaveRing.deinit()
+  ShockwaveLine.deinit()
+  ShockwaveDebris.deinit()
+
+  local cleanupObjects = CollectionService:GetTagged(utility.CLEANUP_TAG)
+
+  for _, obj in cleanupObjects do
+    obj:Destroy()
+  end
+end
+
+local function fullEmit(scale: number, depth: number, ...: Instance)
+  if not api.setup then
+    logger.error("not initialized")
+  end
+
+  return effects.emit(depth, ...)
+end
+
+function api.emit(vfxOrScale: number | Instance, ...: Instance)
+  if typeof(vfxOrScale) ~= "number" then
+    return fullEmit(1, 0, vfxOrScale, ...)
+  else
+    return fullEmit(vfxOrScale, 0, ...)
+  end
+end
+
+function api.emitWithDepth(depth: number, ...: Instance)
+  return fullEmit(1, depth, ...)
+end
+
+function api.enable(obj: Instance)
+  if obj:IsA("ParticleEmitter") or obj:IsA("Beam") then
+    obj.Enabled = true
+    return
+  end
+
+  if attributes.isCached(obj) then
+    attributes.trigger(obj, "Enabled", true)
+  else
+    obj:SetAttribute("Enabled", true)
+  end
+end
+
+function api.disable(obj: Instance)
+  if obj:IsA("ParticleEmitter") or obj:IsA("Beam") then
+    obj.Enabled = false
+    return
+  end
+
+  if attributes.isCached(obj) then
+    attributes.trigger(obj, "Enabled", false)
+  else
+    obj:SetAttribute("Enabled", false)
+  end
+end
+
+function api.cacheAttributes(obj: Instance)
+  if utility.SERVER_CONTEXT then
+    logger.error("attributes can only be cached in a client-side context")
+  end
+
+  if not obj:IsDescendantOf(ReplicatedStorage) then
+    logger.error("attributes can only be cached for VFX inside ReplicatedStorage")
+  end
+
+  for _, v in obj:GetDescendants() do
+    attributes.cache(v)
+  end
+end
+
+function api.restoreAttributes(obj: Instance)
+  if utility.SERVER_CONTEXT then
+    logger.error("attributes can only be restored in a client-side context")
+  end
+
+  for _, v in obj:GetDescendants() do
+    attributes.restore(v)
+  end
+end
+
+return api