@rbxts/vfx-forge 2.2.2

package/out/mod/common/bezier.luau

@@ -0,0 +1,372 @@
+--!nolint LocalShadow
+local CollectionService = game:GetService("CollectionService")
+
+local attr = require("@mod/attributes")
+local shape = require("@mod/shape")
+local tween = require("@mod/tween")
+local utility = require("@mod/utility")
+
+local Oklab = require("@mod/color/Oklab")
+local Bezier = require("@obj/Bezier")
+
+local common = {}
+
+common.drawFuncMap = {
+  Box = {
+    Volume = shape.getPointWithinBox,
+    Surface = shape.getPointOnBox,
+  },
+
+  Cylinder = {
+    Volume = function(seed, cframe, size, normal, partial)
+      return shape.getPointWithinCylinder(seed, 0, partial, cframe, size, normal)
+    end,
+
+    Surface = function(seed, cframe, size, normal, partial)
+      return shape.getPointWithinCylinder(seed, 1, partial, cframe, size, normal)
+    end,
+  },
+
+  Sphere = {
+    Volume = function(seed, cframe, size, normal, partial)
+      return shape.getPointWithinSphere(seed, 0, partial, cframe, size, normal)
+    end,
+
+    Surface = function(seed, cframe, size, normal, partial)
+      return shape.getPointWithinSphere(seed, 1, partial, cframe, size, normal)
+    end,
+  },
+
+  Disc = {
+    Volume = function(seed, cframe, size, normal, partial)
+      return shape.getPointWithinDisc(seed, 0, partial, cframe, size, normal)
+    end,
+
+    Surface = function(seed, cframe, size, normal, partial)
+      return shape.getPointWithinDisc(seed, 1, partial, cframe, size, normal)
+    end,
+  },
+}
+
+function common.getColorAtTime(sequence: ColorSequence, time: number)
+  local keypoints = sequence.Keypoints
+
+  if time <= keypoints[1].Time then
+    return keypoints[1].Value
+  end
+
+  if time >= keypoints[#keypoints].Time then
+    return keypoints[#keypoints].Value
+  end
+
+  local closestBelow
+  local closestAbove
+
+  for i = 1, #keypoints do
+    local kp = keypoints[i]
+    if kp.Time == time then
+      return kp.Value
+    elseif kp.Time < time then
+      closestBelow = kp
+    elseif kp.Time > time then
+      closestAbove = kp
+      break
+    end
+  end
+
+  if not closestBelow or not closestAbove then
+    return keypoints[1].Value
+  end
+
+  local alpha = (time - closestBelow.Time) / (closestAbove.Time - closestBelow.Time)
+  return closestBelow.Value:Lerp(closestAbove.Value, alpha)
+end
+
+function common.getColorAtTimeOklab(sequence: ColorSequence, time: number)
+  local keypoints = sequence.Keypoints
+
+  if time <= keypoints[1].Time then
+    return keypoints[1].Value
+  end
+
+  if time >= keypoints[#keypoints].Time then
+    return keypoints[#keypoints].Value
+  end
+
+  local closestBelow
+  local closestAbove
+
+  for i = 1, #keypoints do
+    local kp = keypoints[i]
+    if kp.Time == time then
+      return kp.Value
+    elseif kp.Time < time then
+      closestBelow = kp
+    elseif kp.Time > time then
+      closestAbove = kp
+      break
+    end
+  end
+
+  if not closestBelow or not closestAbove then
+    return keypoints[1].Value
+  end
+
+  local alpha = (time - closestBelow.Time) / (closestAbove.Time - closestBelow.Time)
+
+  local labA = Oklab.fromSRGB(closestBelow.Value)
+  local labB = Oklab.fromSRGB(closestAbove.Value)
+
+  local blendedLab = labA:Lerp(labB, alpha)
+
+  return Oklab.toSRGB(blendedLab)
+end
+
+function common.getColorWithEasingOklab(sequence: ColorSequence, time: number, easingBezier)
+  local easedTime = 1 - easingBezier:getEase(math.clamp(time, 0, 1)).y
+  return common.getColorAtTimeOklab(sequence, math.clamp(easedTime, 0, 1))
+end
+
+export type HitboxConfig = {
+  enabled: boolean,
+  collisionGroup: string,
+  filterTag: string,
+  filterType: string,
+  ignoreCanCollide: boolean,
+}
+
+function common.createHitboxParams(config: HitboxConfig, parent: Instance, root: Attachment?): OverlapParams
+  local params = OverlapParams.new()
+  params.MaxParts = 1
+  params.FilterType = Enum.RaycastFilterType[config.filterType]
+  params.CollisionGroup = config.collisionGroup
+  params.RespectCanCollide = not config.ignoreCanCollide
+
+  params:AddToFilter(CollectionService:GetTagged(config.filterTag))
+
+  if config.filterType == "Exclude" then
+    local ancestorPart = root and root:FindFirstAncestorOfClass("Part")
+    params:AddToFilter({ workspace.Terrain, parent, ancestorPart })
+  end
+
+  return params
+end
+
+export type EmissionConfig = {
+  face: "InAndOut" | "Inward" | "Outward",
+  spreadAngle: Vector3,
+  mirror: boolean,
+  mirrorRot: Vector3,
+  partial: number,
+  emissionDirection: Enum.NormalId,
+}
+
+function common.calculateEmissionCFrame(
+  originCFrame: CFrame,
+  originSize: Vector3,
+  config: EmissionConfig,
+  drawFunc: ((...any) -> CFrame)?,
+  rng: Random,
+  endPoint: Attachment?,
+  isAttachment: boolean
+)
+  local cf: CFrame
+
+  if isAttachment then
+    cf = originCFrame * CFrame.new(Vector3.zero, Vector3.FromNormalId(config.emissionDirection)).Rotation
+  elseif drawFunc then
+    cf = drawFunc(nil, originCFrame, originSize, config.emissionDirection, config.partial)
+  else
+    cf = originCFrame
+  end
+
+  local normal = Vector3.FromNormalId(config.emissionDirection)
+  local pitchAxis = normal:Cross(originCFrame.LookVector)
+
+  if pitchAxis.Magnitude < 0.001 then
+    pitchAxis = normal:Cross(originCFrame.UpVector)
+  end
+
+  local spread = CFrame.fromAxisAngle(normal, math.rad(rng:NextNumber(-config.spreadAngle.X, config.spreadAngle.X)))
+    * CFrame.fromAxisAngle(pitchAxis, math.rad(rng:NextNumber(-config.spreadAngle.Y, config.spreadAngle.Y)))
+
+  cf *= spread
+
+  if config.face == "Inward" or (config.face == "InAndOut" and rng:NextInteger(0, 1) == 1) then
+    cf *= CFrame.fromOrientation(0, math.pi, 0)
+  end
+
+  if endPoint and config.mirror and (cf.Position - endPoint.WorldPosition).Unit:Dot(cf.RightVector) >= 0 then
+    local rot = config.mirrorRot * utility.DEG_TO_RAD
+    cf *= CFrame.fromOrientation(rot.X, rot.Y, rot.Z)
+  end
+
+  return cf
+end
+
+function common.createBezierWithEndpoint(points: { vector }, cf: CFrame, endPoint: Attachment?, endT1: Attachment?)
+  if not endPoint then
+    return Bezier.new(points)
+  end
+
+  local pts = {}
+
+  for j, pt in points do
+    table.insert(
+      pts,
+      if j == (#points - 1)
+        then endT1 and endT1.WorldPosition or endPoint.WorldPosition
+        else if j == #points then endPoint.WorldPosition else cf * (pt - points[1])
+    )
+  end
+
+  return Bezier.new(pts)
+end
+
+function common.createPosGetter(
+  bezier,
+  points: { vector },
+  cf: CFrame,
+  endPoint: Attachment?,
+  useArcSpace: boolean?
+): (number) -> Vector3
+  return function(alpha: number): Vector3
+    local p = if useArcSpace ~= false then bezier:getPositionArcSpace(alpha) else bezier:getPosition(alpha)
+
+    if endPoint then
+      return p
+    else
+      return cf * (p - points[1])
+    end
+  end
+end
+
+function common.readCommonAttributes(ref: Attachment)
+  return {
+    -- timing
+    emitDelay = attr.get(ref, "EmitDelay", 0),
+    emitCount = attr.get(ref, "EmitCount", 1),
+    emitDuration = attr.get(ref, "EmitDuration", 0),
+    destroyDelay = attr.get(ref, "DestroyDelay", 0),
+    duration = attr.getRange(ref, "Duration", NumberRange.new(1, 1), NumberRange.new(0, math.huge)),
+
+    -- shape/emission
+    shapeType = attr.getEnum(ref, "Shape", "Box", { "Box", "Cylinder", "Sphere", "Disc" }),
+    shapeStyle = attr.getEnum(ref, "ShapeStyle", "Volume", { "Volume", "Surface" }),
+    emissionDirection = Enum.NormalId[attr.getEnum(
+      ref,
+      "EmissionDirection",
+      "Top",
+      { "Top", "Bottom", "Left", "Right", "Front", "Back" }
+    )],
+    face = attr.getEnum(ref, "ShapeFace", "Outward", { "InAndOut", "Inward", "Outward" }),
+    spreadAngle = attr.get(ref, "SpreadAngle", vector.zero),
+    partial = attr.get(ref, "ShapePartial", 1),
+
+    -- path
+    syncPosition = attr.get(ref, "SyncPosition", false),
+    mirror = attr.get(ref, "MirrorPaths", true),
+    mirrorRot = attr.get(ref, "MirrorRotation", vector.create(0, 0, 180)),
+
+    -- projectile
+    projectileEnabled = attr.get(ref, "ProjectileEnabled", false),
+    projectileMatchEnd = attr.get(ref, "MatchEndDirection", false),
+    projectileSpeed = attr.get(ref, "ProjectileSpeed", 30),
+    projectileLifetime = attr.getRange(ref, "ProjectileLifetime", NumberRange.new(1, 1), NumberRange.new(0, math.huge)),
+
+    -- hitbox
+    hitboxEnabled = attr.get(ref, "HitboxEnabled", false),
+    hitboxCollisionGroup = attr.get(ref, "HitboxCollisionGroup", "Default"),
+    hitboxFilterTag = attr.get(ref, "HitboxFilterTag", ""),
+    hitboxFilterType = attr.get(ref, "HitboxFilterType", "Exclude"),
+    hitboxIgnoreCanCollide = attr.get(ref, "HitboxIgnoreCanCollide", false),
+
+    -- speed
+    speedStart = attr.get(ref, "Speed_Start", 1),
+    speedEnd = attr.get(ref, "Speed_End", 1),
+  }
+end
+
+function common.getCurrentOriginCFrame(parent: Instance, fallback: CFrame)
+  if parent:IsA("BasePart") then
+    return parent.CFrame
+  elseif parent:IsA("Attachment") then
+    return parent.WorldCFrame
+  end
+
+  return fallback
+end
+
+function common.findEndAttachments(ref: Attachment): (Attachment?, Attachment?)
+  local endPoint = ref:FindFirstChild("End")
+  local endT1 = endPoint and endPoint:FindFirstChild("T1")
+
+  if endPoint and not endPoint:IsA("Attachment") then
+    endPoint = nil
+  end
+
+  if endT1 and not endT1:IsA("Attachment") then
+    endT1 = nil
+  end
+
+  return endPoint, endT1
+end
+
+function common.validateParent(ref: Attachment): Instance?
+  local parent = ref.Parent
+
+  if not parent then
+    return nil
+  end
+
+  if not parent:IsA("BasePart") and not parent:IsA("Attachment") then
+    parent = ref
+  end
+
+  return parent
+end
+
+function common.getPerpendicularVectors(tangent: Vector3)
+  local right = tangent:Cross(Vector3.yAxis)
+
+  if right.Magnitude < 0.001 then
+    right = tangent:Cross(Vector3.zAxis)
+  end
+
+  right = right.Unit
+
+  local up = tangent:Cross(right).Unit
+
+  return right, up
+end
+
+function common.createPropertyTween(
+  scope: any,
+  ref: Attachment,
+  attrName: string,
+  tweenDuration: number,
+  startVal: number,
+  endVal: number,
+  setter: (number) -> (),
+  getSpeed: () -> number,
+  speedTween: any?
+)
+  if startVal == endVal then
+    return
+  end
+
+  table.insert(
+    scope,
+    tween.fromParams(
+      attr.get(ref, attrName .. "_Curve", utility.default_bezier),
+      tweenDuration,
+      function(alpha, deltaTime)
+        setter(utility.lerp(startVal, endVal, alpha))
+        return deltaTime * getSpeed()
+      end,
+      speedTween
+    )
+  )
+end
+
+return common

package/out/mod/common/flipbook.luau

@@ -0,0 +1,102 @@
+local RunService = game:GetService("RunService")
+local CollectionService = game:GetService("CollectionService")
+
+local common = {}
+
+function common.serialize(ids: { number })
+  local buf = buffer.create(#ids * 8)
+
+  for i, id in ids do
+    buffer.writef64(buf, (i - 1) * 8, id)
+  end
+
+  return buf
+end
+
+function common.deserialize(data: string | buffer)
+  local buf = typeof(data) == "string" and buffer.fromstring(data) or data
+  local count = buffer.len(buf) / 8
+
+  local ids = {}
+
+  for i = 0, count - 1 do
+    table.insert(ids, buffer.readf64(buf, i * 8))
+  end
+
+  return ids
+end
+
+function common.isLocalFlipbook(ref: Instance)
+  if not RunService:IsStudio() then
+    return false
+  end
+
+  for _, tag in CollectionService:GetTags(ref) do
+    if tag:match("^_local_flipbook_") then
+      return true
+    end
+  end
+
+  return false
+end
+
+function common.getTexturePrefix(ref: Instance)
+  return common.isLocalFlipbook(ref) and "rbxtemp://" or "rbxassetid://"
+end
+
+function common.getFlipbookData(ref: Instance): { number }?
+  if not ref:GetAttribute("FlipbookEnabled") then
+    return nil
+  end
+
+  local data = ref:GetAttribute("FlipbookTextures")
+
+  if not data then
+    return nil
+  end
+
+  local frames = common.deserialize(data)
+
+  if #frames == 0 then
+    return nil
+  end
+
+  return frames
+end
+
+export type FlipbookConfig = {
+  ref: Instance,
+  curve: string,
+  speedTween: any?,
+
+  duration: number,
+  effectDuration: number,
+
+  frames: { number },
+
+  getSpeed: () -> number,
+  setTexture: (texture: string) -> (),
+}
+
+function common.getChangeDuration(config: FlipbookConfig)
+  local changeDuration = config.duration
+
+  if config.ref:GetAttribute("SyncDuration") then
+    changeDuration = config.effectDuration
+  end
+
+  return changeDuration
+end
+
+function common.createUpdateCallback(config: FlipbookConfig)
+  local prefix = common.getTexturePrefix(config.ref)
+
+  return function(alpha, deltaTime)
+    local index = math.max(math.round(#config.frames * alpha), 1)
+    config.setTexture(`{prefix}{config.frames[index]}`)
+
+    return deltaTime * config.getSpeed()
+  end
+end
+
+return common

package/out/mod/lerp.luau

@@ -0,0 +1,210 @@
+local Oklab = require("@mod/color/Oklab")
+
+local MAX_KEYPOINTS = 20
+
+local lerp = {}
+
+function lerp.number(a: number, b: number, t: number)
+  return a + (b - a) * t
+end
+
+function lerp.Vector3(a: Vector3, b: Vector3, t: number)
+  return a:Lerp(b, t)
+end
+
+function lerp.Vector2(a: Vector2, b: Vector2, t: number)
+  return a:Lerp(b, t)
+end
+
+function lerp.CFrame(a: CFrame, b: CFrame, t: number)
+  return a:Lerp(b, t)
+end
+
+function lerp.UDim2(a: UDim2, b: UDim2, t: number)
+  return a:Lerp(b, t)
+end
+
+function lerp.UDim(a: UDim, b: UDim, t: number)
+  -- stylua: ignore
+  return UDim.new(
+    lerp.number(a.Scale, b.Scale, t),
+    lerp.number(a.Offset, b.Offset, t)
+  )
+end
+
+function lerp.NumberRange(a: NumberRange, b: NumberRange, t: number)
+  -- stylua: ignore
+  return NumberRange.new(
+    lerp.number(a.Min, b.Min, t),
+    lerp.number(a.Max, b.Max, t)
+  )
+end
+
+function lerp.Color3(a: Color3, b: Color3, t: number)
+  -- stylua: ignore
+  return Oklab.toSRGB(
+    Oklab.fromSRGB(a):Lerp(Oklab.fromSRGB(b), t)
+  )
+end
+
+function lerp.PhysicalProperties(a: PhysicalProperties, b: PhysicalProperties, t: number)
+  return PhysicalProperties.new(
+    lerp.number(a.Density, b.Density, t),
+    lerp.number(a.Friction, b.Friction, t),
+    lerp.number(a.Elasticity, b.Elasticity, t),
+    lerp.number(a.FrictionWeight, b.FrictionWeight, t),
+    lerp.number(a.ElasticityWeight, b.ElasticityWeight, t)
+  )
+end
+
+function lerp.Rect(a: Rect, b: Rect, t: number)
+  return Rect.new(a.Min:Lerp(b.Min, t), a.Max:Lerp(b.Max, t))
+end
+
+-- credit https://github.com/boatbomber/BoatTween
+function lerp.NumberSequence(a: NumberSequence, b: NumberSequence, t: number)
+  local keypoints = {}
+  local addedTimes = {}
+
+  local keylength = 0
+
+  for _, ap in a.Keypoints do
+    local closestAbove, closestBelow
+
+    for _, bp in b.Keypoints do
+      if bp.Time == ap.Time then
+        closestAbove, closestBelow = bp, bp
+        break
+      elseif bp.Time < ap.Time and (closestBelow == nil or bp.Time > closestBelow.Time) then
+        closestBelow = bp
+      elseif bp.Time > ap.Time and (closestAbove == nil or bp.Time < closestAbove.Time) then
+        closestAbove = bp
+      end
+    end
+
+    local bValue, bEnvelope
+
+    if closestAbove == closestBelow then
+      bValue, bEnvelope = closestAbove.Value, closestAbove.Envelope
+    else
+      local p = (ap.Time - closestBelow.Time) / (closestAbove.Time - closestBelow.Time)
+      bValue = (closestAbove.Value - closestBelow.Value) * p + closestBelow.Value
+      bEnvelope = (closestAbove.Envelope - closestBelow.Envelope) * p + closestBelow.Envelope
+    end
+
+    keylength += 1
+    keypoints[keylength] = NumberSequenceKeypoint.new(
+      ap.Time,
+      (bValue - ap.Value) * t + ap.Value,
+      (bEnvelope - ap.Envelope) * t + ap.Envelope
+    )
+
+    addedTimes[ap.Time] = true
+  end
+
+  for _, bp in b.Keypoints do
+    if not addedTimes[bp.Time] then
+      local closestAbove, closestBelow
+
+      for _, ap in a.Keypoints do
+        if ap.Time == bp.Time then
+          closestAbove, closestBelow = ap, ap
+          break
+        elseif ap.Time < bp.Time and (closestBelow == nil or ap.Time > closestBelow.Time) then
+          closestBelow = ap
+        elseif ap.Time > bp.Time and (closestAbove == nil or ap.Time < closestAbove.Time) then
+          closestAbove = ap
+        end
+      end
+
+      local aValue, aEnvelope
+
+      if closestAbove == closestBelow then
+        aValue, aEnvelope = closestAbove.Value, closestAbove.Envelope
+      else
+        local p = (bp.Time - closestBelow.Time) / (closestAbove.Time - closestBelow.Time)
+        aValue = (closestAbove.Value - closestBelow.Value) * p + closestBelow.Value
+        aEnvelope = (closestAbove.Envelope - closestBelow.Envelope) * p + closestBelow.Envelope
+      end
+
+      keylength += 1
+      keypoints[keylength] =
+        NumberSequenceKeypoint.new(bp.Time, (bp.Value - aValue) * t + aValue, (bp.Envelope - aEnvelope) * t + aEnvelope)
+    end
+  end
+
+  table.sort(keypoints, function(a, b)
+    return a.Time < b.Time
+  end)
+
+  local finalKeypoints
+
+  if #keypoints > MAX_KEYPOINTS then
+    finalKeypoints = {}
+    local step = (#keypoints - 1) / (MAX_KEYPOINTS - 1)
+
+    for i = 0, MAX_KEYPOINTS - 1 do
+      local index = math.floor(i * step + 1)
+      table.insert(finalKeypoints, keypoints[index])
+    end
+
+    if finalKeypoints[#finalKeypoints].Time < keypoints[#keypoints].Time then
+      finalKeypoints[#finalKeypoints] = keypoints[#keypoints]
+    end
+  else
+    finalKeypoints = keypoints
+  end
+
+  return NumberSequence.new(finalKeypoints)
+end
+
+local function getColorAtTime(sequence: ColorSequence, time: number)
+  local keypoints = sequence.Keypoints
+
+  if time <= keypoints[1].Time then
+    return keypoints[1].Value
+  end
+
+  if time >= keypoints[#keypoints].Time then
+    return keypoints[#keypoints].Value
+  end
+
+  local closestBelow
+  local closestAbove
+
+  for i = 1, #keypoints do
+    local kp = keypoints[i]
+    if kp.Time == time then
+      return kp.Value
+    elseif kp.Time < time then
+      closestBelow = kp
+    elseif kp.Time > time then
+      closestAbove = kp
+      break
+    end
+  end
+
+  local alpha = (time - closestBelow.Time) / (closestAbove.Time - closestBelow.Time)
+
+  return closestBelow.Value:Lerp(closestAbove.Value, alpha)
+end
+
+function lerp.ColorSequence(a: ColorSequence, b: ColorSequence, t: number)
+  local newKeypoints = {}
+
+  for _, bp in ipairs(b.Keypoints) do
+    local aValueAtBTime = getColorAtTime(a, bp.Time)
+    -- use linear space because color sequences are in linear space anyway
+    local finalColor = Oklab.toSRGB(Oklab.fromSRGB(aValueAtBTime:Lerp(bp.Value, t)))
+
+    table.insert(newKeypoints, ColorSequenceKeypoint.new(bp.Time, finalColor))
+  end
+
+  return ColorSequence.new(newKeypoints)
+end
+
+function lerp.Other(a: any, b: any, t: number)
+  return t < 0.5 and a or b
+end
+
+return lerp

package/out/mod/logger.luau

@@ -0,0 +1,20 @@
+local function msg(...: string)
+  return `[Forge Emit API]: {table.concat({ ... }, " ")}`
+end
+
+local logger = {}
+
+function logger.error(...)
+  error(msg(..., "\n"))
+end
+
+function logger.warn(...)
+  warn(msg(...))
+  warn(msg(debug.traceback("stack trace:")))
+end
+
+function logger.info(...)
+  print(msg(...))
+end
+
+return logger