@rbxts/vfx-forge 2.2.2

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,39 @@
+![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
+
+#### Using Wally
+
+```sh
+ForgeVFX = "zilibobi/forge-vfx@2.2.2"
+```
+
+#### 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/effects/beam.luau

@@ -0,0 +1,312 @@
+--!nolint LocalShadow
+local attr = require("@mod/attributes")
+local tween = require("@mod/tween")
+local types = require("@root/types")
+local utility = require("@mod/utility")
+local flipbook_common = require("@mod/common/flipbook")
+
+local Promise = require("@pkg/Promise")
+
+local rng = Random.new()
+
+local function getLegacyWidths(obj: Beam, scale: number)
+  local w0 = attr.get(obj, "Width0", obj.Width0, true) * scale
+  local w1 = attr.get(obj, "Width1", obj.Width1, true) * scale
+
+  local s_w0 = attr.get(obj, "StartWidth0", obj.Width0, true) * scale
+  local s_w1 = attr.get(obj, "StartWidth1", obj.Width1, true) * scale
+
+  return w0, w1, s_w0, s_w1
+end
+
+local beam = {}
+
+function beam.emit(ref: Beam, obj: Beam, scope: types.scope, scale: number)
+  local emitOnFinish = scope.effects.prepareEmitOnFinish(obj, scope)
+
+  local a1, a2, a3, a4 = getLegacyWidths(ref, scale)
+
+  local w1 = attr.get(ref, "Width0_Start", a3)
+  local w2 = attr.get(ref, "Width0_End", a1)
+  local w3 = attr.get(ref, "Width1_Start", a4)
+  local w4 = attr.get(ref, "Width1_End", a2)
+
+  local c1 = attr.get(ref, "CurveSize0_Start", obj.CurveSize0)
+  local c2 = attr.get(ref, "CurveSize0_End", obj.CurveSize0)
+  local c3 = attr.get(ref, "CurveSize1_Start", obj.CurveSize1)
+  local c4 = attr.get(ref, "CurveSize1_End", obj.CurveSize1)
+
+  local emitDelay = attr.get(ref, "EmitDelay", 0)
+
+  local legacy_duration = attr.get(ref, "Duration", 1, true)
+  local legacy_tpScale = attr.get(ref, "EndTransparencyScale", 1, true)
+
+  local durationRange = attr.getRange(
+    ref,
+    "EffectDuration",
+    NumberRange.new(legacy_duration, legacy_duration),
+    NumberRange.new(0, math.huge)
+  )
+
+  local lengthScaleRangeStart = attr.get(ref, "Length_Scale_Start", NumberRange.new(1, 1))
+  local lengthScaleRangeEnd = attr.get(ref, "Length_Scale_End", NumberRange.new(1, 1))
+
+  local texLengthStart = attr.get(ref, "Length_Texture_Start", ref.TextureLength)
+  local textLengthEnd = attr.get(ref, "Length_Texture_End", ref.TextureLength)
+
+  local duration = rng:NextNumber(durationRange.Min, durationRange.Max)
+
+  local lengthScaleEnd = rng:NextNumber(lengthScaleRangeEnd.Min, lengthScaleRangeEnd.Max)
+  local lengthScaleStart = rng:NextNumber(lengthScaleRangeStart.Min, lengthScaleRangeStart.Max)
+
+  local tStart, tEnd =
+    attr.get(ref, "Transparency_Scale_Start", 1), attr.get(ref, "Transparency_Scale_End", legacy_tpScale)
+
+  local texSpeedStart = attr.get(ref, "Speed_Texture_Start", ref.TextureSpeed)
+  local texSpeedEnd = attr.get(ref, "Speed_Texture_End", ref.TextureSpeed)
+
+  local speedStart = attr.get(ref, "Speed_Start", 1)
+  local speedEnd = attr.get(ref, "Speed_End", 1)
+
+  local baseTexSpeed = obj.TextureSpeed
+
+  task.wait(emitDelay)
+
+  obj.Enabled = true
+
+  local promises = {}
+  local currentSpeed = 1
+
+  local speedTween
+
+  local env = scope.effects.emitNested(obj, scope.depth + 1)
+  table.insert(promises, env.Finished)
+
+  if texSpeedStart ~= texSpeedEnd then
+    tween.fromParams(attr.get(ref, "Speed_Texture_Curve", utility.default_bezier), duration, function(alpha, deltaTime)
+      baseTexSpeed = utility.lerp(texSpeedStart, texSpeedEnd, alpha)
+      obj.TextureSpeed = baseTexSpeed * currentSpeed
+
+      return deltaTime
+    end)
+  end
+
+  if speedStart ~= speedEnd then
+    speedTween = tween.fromParams(
+      attr.get(ref, "Speed_Curve", utility.default_bezier),
+      attr.get(obj, "Speed_Duration", 0.1),
+      function(alpha, deltaTime)
+        currentSpeed = utility.lerp(speedStart, speedEnd, alpha)
+
+        obj.TextureSpeed = baseTexSpeed * currentSpeed
+
+        return deltaTime
+      end
+    )
+
+    table.insert(scope, speedTween)
+  end
+
+  local refTpKp = ref.Transparency.Keypoints
+
+  local numKeypoints = #refTpKp
+  local scaledKeypoints = table.create(numKeypoints)
+
+  local keypointData = table.create(numKeypoints)
+
+  for i, kp in refTpKp do
+    keypointData[i] = {
+      time = kp.Time,
+      value = kp.Value,
+      envelope = kp.Envelope,
+    }
+  end
+
+  local lastTScale = nil
+
+  local function setTScale(tscale: number)
+    if lastTScale and math.abs(tscale - lastTScale) < 0.001 then
+      return
+    end
+
+    lastTScale = tscale
+
+    local offset = tscale > 1 and tscale - 1 or 1 - tscale
+
+    for i, kd in keypointData do
+      local value = kd.value
+      local base = tscale > 1 and (1 - value) or -value
+
+      scaledKeypoints[i] = NumberSequenceKeypoint.new(kd.time, value + base * offset, kd.envelope)
+    end
+
+    obj.Transparency = NumberSequence.new(scaledKeypoints)
+  end
+
+  local att0, att1 = obj.Attachment0, obj.Attachment1
+  local cf0, cf1 = att0 and att0.CFrame, att1 and att1.CFrame
+
+  local function setLengthScale(scale: number)
+    if not cf0 or not cf1 then
+      return
+    end
+
+    -- calculate the original offset vector from att0 to att1
+    local offset = cf1.Position - cf0.Position
+    local halfOffset = offset * 0.5
+
+    -- calculate center point
+    local center = cf0.Position + halfOffset
+
+    -- scale the half-offsets and apply from center
+    local scaledHalfOffset = halfOffset * scale
+
+    att0.CFrame = CFrame.new(center - scaledHalfOffset) * (cf0 - cf0.Position)
+    att1.CFrame = CFrame.new(center + scaledHalfOffset) * (cf1 - cf1.Position)
+  end
+
+  table.insert(scope, function()
+    setLengthScale(1)
+  end)
+
+  if tStart ~= tEnd then
+    table.insert(
+      scope,
+      tween.fromParams(
+        attr.get(ref, "Transparency_Scale_Curve", utility.default_bezier),
+        duration,
+        function(alpha, deltaTime)
+          setTScale(utility.lerp(tStart, tEnd, alpha))
+          return deltaTime * currentSpeed
+        end,
+        speedTween
+      )
+    )
+  elseif tStart ~= 1 then
+    setTScale(tStart)
+  end
+
+  if texLengthStart ~= textLengthEnd then
+    table.insert(
+      scope,
+      tween.fromParams(
+        attr.get(ref, "Length_Texture_Curve", utility.default_bezier),
+        duration,
+        function(alpha, deltaTime)
+          obj.TextureLength = utility.lerp(texLengthStart, textLengthEnd, alpha)
+          return deltaTime * currentSpeed
+        end,
+        speedTween
+      )
+    )
+  end
+
+  if lengthScaleStart ~= lengthScaleEnd then
+    table.insert(
+      scope,
+      tween.fromParams(attr.get(ref, "Length_Scale_Curve", utility.default_bezier), duration, function(alpha, deltaTime)
+        local x = utility.lerp(lengthScaleStart, lengthScaleEnd, alpha)
+
+        setLengthScale(x)
+
+        return deltaTime * currentSpeed
+      end, speedTween)
+    )
+  elseif texLengthStart ~= 1 then
+    setLengthScale(lengthScaleStart)
+  end
+
+  if w1 ~= w2 then
+    table.insert(
+      scope,
+      tween.fromParams(attr.get(ref, "Width0_Curve", utility.default_bezier), duration, function(alpha, deltaTime)
+        obj.Width0 = utility.lerp(w1, w2, alpha)
+        return deltaTime * currentSpeed
+      end, speedTween)
+    )
+  else
+    obj.Width0 = w1
+  end
+
+  if w3 ~= w4 then
+    table.insert(
+      scope,
+      tween.fromParams(attr.get(ref, "Width1_Curve", utility.default_bezier), duration, function(alpha, deltaTime)
+        obj.Width1 = utility.lerp(w3, w4, alpha)
+        return deltaTime * currentSpeed
+      end, speedTween)
+    )
+  else
+    obj.Width1 = w3
+  end
+
+  if c1 ~= c2 then
+    table.insert(
+      scope,
+      tween.fromParams(attr.get(ref, "CurveSize0_Curve", utility.default_bezier), duration, function(alpha, deltaTime)
+        obj.CurveSize0 = utility.lerp(c1, c2, alpha)
+        return deltaTime * currentSpeed
+      end, speedTween)
+    )
+  else
+    obj.Width0 = w1
+  end
+
+  if c3 ~= c4 then
+    table.insert(
+      scope,
+      tween.fromParams(attr.get(ref, "CurveSize1_Curve", utility.default_bezier), duration, function(alpha, deltaTime)
+        obj.CurveSize1 = utility.lerp(c3, c4, alpha)
+        return deltaTime * currentSpeed
+      end, speedTween)
+    )
+  else
+    obj.Width1 = w3
+  end
+
+  -- flipbook support
+  local flipbookDuration = 0
+  local flipbook = flipbook_common.getFlipbookData(ref)
+
+  if flipbook then
+    local config = {
+      ref = ref,
+      frames = flipbook,
+      speedTween = speedTween,
+      effectDuration = duration,
+
+      curve = attr.get(ref, "Flipbook_Change_Curve", utility.linear_bezier),
+      duration = attr.get(ref, "Flipbook_Change_Duration", duration),
+
+      getSpeed = function()
+        return currentSpeed
+      end,
+
+      setTexture = function(texture)
+        obj.Texture = texture
+      end,
+    }
+
+    flipbookDuration = flipbook_common.getChangeDuration(config)
+
+    table.insert(
+      scope,
+      tween.fromParams(config.curve, flipbookDuration, flipbook_common.createUpdateCallback(config), speedTween)
+    )
+  end
+
+  tween.timer(math.max(duration, flipbookDuration), function(deltaTime, elapsed)
+    return if currentSpeed > 0 or (elapsed > 0 and speedTween and speedTween.Connected)
+      then deltaTime * currentSpeed
+      else nil
+  end, speedTween, scope)
+
+  if emitOnFinish then
+    local env = scope.effects.emitOnFinish(emitOnFinish, obj.Parent or workspace.Terrain, scope.depth + 1)
+    table.insert(promises, env.Finished)
+  end
+
+  Promise.all(promises):await()
+end
+
+return beam