@rbxts/vfx-forge 2.2.2

package/out/mod/attributes.luau

@@ -0,0 +1,227 @@
+local RunService = game:GetService("RunService")
+
+local logger = require("./logger")
+
+local IS_SERVER = RunService:IsServer()
+local ATTR_CACHE_ID = "U"
+
+type AttrCache = {
+  [number]: {
+    [string]: any,
+  },
+}
+
+type AttrHooks = {
+  [Instance]: {
+    [string]: { (v: any) -> never },
+  },
+}
+
+type RuntimeState = {
+  [Instance]: {
+    [string]: any,
+  },
+}
+
+local Cache: AttrCache = {}
+local Hooks: AttrHooks = {}
+local State: RuntimeState = {}
+
+local LastRefId = 0
+
+local attr = {}
+
+function attr.cache(obj: Instance)
+  local attributes = obj:GetAttributes()
+
+  if next(attributes) == nil then
+    return
+  end
+
+  LastRefId += 1
+
+  local id = LastRefId
+  local map = {}
+
+  for k, v in attributes do
+    if k == ATTR_CACHE_ID then
+      continue
+    end
+
+    map[k] = v
+    obj:SetAttribute(k, nil)
+  end
+
+  Cache[id] = map
+
+  obj:SetAttribute(ATTR_CACHE_ID, id)
+end
+
+function attr.restore(obj: Instance)
+  local id = obj:GetAttribute(ATTR_CACHE_ID)
+
+  local cache = Cache[id]
+
+  if not cache then
+    logger.error(`{obj} with cache id '{id}' doesn't have any cached attributes`)
+  end
+
+  for k, v in cache do
+    obj:SetAttribute(k, v)
+  end
+
+  obj:SetAttribute(ATTR_CACHE_ID, nil)
+end
+
+function attr.get<T>(obj: Instance, key: string, default: T, soft: boolean?, validate: ((v: unknown) -> T)?): T
+  local id = obj:GetAttribute(ATTR_CACHE_ID)
+
+  local cache = Cache[id]
+  local value = cache and cache[key]
+
+  if value ~= nil then
+    return if validate then validate(value) else if value == nil then default else value
+  end
+
+  value = obj:GetAttribute(key)
+
+  if validate then
+    value = validate(value)
+  elseif value == nil then
+    value = default
+  end
+
+  if not soft and IS_SERVER then
+    obj:SetAttribute(key, value)
+  end
+
+  return value
+end
+
+function attr.getRange(obj: Instance, key: string, default: NumberRange, clamp: NumberRange?, soft: boolean?)
+  return attr.get(obj, key, default, soft, function(v)
+    if typeof(v) ~= "NumberRange" then
+      return default
+    end
+
+    if clamp then
+      -- stylua: ignore
+      return NumberRange.new(
+        math.clamp(v.Min, clamp.Min, clamp.Max),
+        math.clamp(v.Max, clamp.Min, clamp.Max)
+      )
+    end
+
+    return v
+  end)
+end
+
+function attr.getEnum<T>(obj: Instance, key: string, default: T, enums: { T }, soft: boolean?): T
+  return attr.get(obj, key, default, soft, function(v)
+    if v == nil or not table.find(enums, v) then
+      return default
+    end
+
+    return v
+  end)
+end
+
+function attr.set<T>(obj: Instance, key: string, value: T)
+  local id = obj:GetAttribute(ATTR_CACHE_ID)
+
+  local cache = Cache[id]
+
+  if cache then
+    cache[key] = value
+  else
+    obj:SetAttribute(key, value)
+  end
+end
+
+function attr.isCached(obj: Instance): boolean
+  return obj:GetAttribute(ATTR_CACHE_ID) ~= nil
+end
+
+function attr.getState<T>(obj: Instance, key: string, default: T): T
+  local state = State[obj]
+  local value = state and state[key]
+
+  return if value ~= nil then value else default
+end
+
+function attr.setState<T>(obj: Instance, key: string, value: T)
+  local state = State[obj]
+
+  if not state then
+    state = {}
+    State[obj] = state
+  end
+
+  state[key] = value
+end
+
+function attr.clearState(obj: Instance)
+  State[obj] = nil
+end
+
+function attr.trigger<T>(obj: Instance, key: string, value: T)
+  local hooks = Hooks[obj]
+  local callbacks = hooks and hooks[key]
+
+  if not callbacks then
+    return
+  end
+
+  for _, callback in callbacks do
+    callback(value)
+  end
+end
+
+function attr.hook<T>(obj: Instance, key: string, callback: (v: T) -> never)
+  local hooks = Hooks[obj]
+
+  if not hooks then
+    hooks = {}
+    Hooks[obj] = hooks
+  end
+
+  local callbacks = hooks[key]
+
+  if not callbacks then
+    callbacks = {}
+    hooks[key] = callbacks
+  end
+
+  table.insert(callbacks, callback)
+
+  local connection
+
+  if not attr.isCached(obj) then
+    connection = obj:GetAttributeChangedSignal(key):Connect(function()
+      local value = obj:GetAttribute(key)
+      callback(value)
+    end)
+  end
+
+  return function()
+    if connection then
+      connection:Disconnect()
+    end
+
+    local index = table.find(callbacks, callback)
+
+    if index then
+      table.remove(callbacks, index)
+    end
+
+    if #callbacks == 0 then
+      hooks[key] = nil
+    end
+
+    if next(hooks) == nil then
+      Hooks[obj] = nil
+    end
+  end
+end
+
+return attr

package/out/mod/color/Oklab.luau

@@ -0,0 +1,93 @@
+--[[
+MIT License
+
+Copyright (c) 2024 Daniel P H Fox
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE 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. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+]]
+
+--!strict
+--!nolint LocalUnused
+--!nolint LocalShadow
+local task = nil -- Disable usage of Roblox's task scheduler
+
+--[[
+	Provides functions for converting Color3s into Oklab space, for more
+	perceptually uniform colour blending.
+
+	See: https://bottosson.github.io/posts/oklab/
+]]
+
+local sRGB = require("@mod/color/sRGB")
+
+local Oklab = {}
+
+-- Converts a Color3 in linear RGB space to a Vector3 in Oklab space.
+function Oklab.fromLinear(rgb: Color3): Vector3
+  local l = rgb.R * 0.4122214708 + rgb.G * 0.5363325363 + rgb.B * 0.0514459929
+  local m = rgb.R * 0.2119034982 + rgb.G * 0.6806995451 + rgb.B * 0.1073969566
+  local s = rgb.R * 0.0883024619 + rgb.G * 0.2817188376 + rgb.B * 0.6299787005
+
+  local lRoot = l ^ (1 / 3)
+  local mRoot = m ^ (1 / 3)
+  local sRoot = s ^ (1 / 3)
+
+  return Vector3.new(
+    lRoot * 0.2104542553 + mRoot * 0.7936177850 - sRoot * 0.0040720468,
+    lRoot * 1.9779984951 - mRoot * 2.4285922050 + sRoot * 0.4505937099,
+    lRoot * 0.0259040371 + mRoot * 0.7827717662 - sRoot * 0.8086757660
+  )
+end
+
+-- Converts a Color3 in sRGB space to a Vector3 in Oklab space.
+function Oklab.fromSRGB(srgb: Color3): Vector3
+  return Oklab.fromLinear(sRGB.toLinear(srgb))
+end
+
+-- Converts a Vector3 in Oklab space to a Color3 in linear RGB space.
+-- The Color3 will be clamped by default unless specified otherwise.
+function Oklab.toLinear(lab: Vector3, unclamped: boolean?): Color3
+  local lRoot = lab.X + lab.Y * 0.3963377774 + lab.Z * 0.2158037573
+  local mRoot = lab.X - lab.Y * 0.1055613458 - lab.Z * 0.0638541728
+  local sRoot = lab.X - lab.Y * 0.0894841775 - lab.Z * 1.2914855480
+
+  local l = lRoot ^ 3
+  local m = mRoot ^ 3
+  local s = sRoot ^ 3
+
+  local red = l * 4.0767416621 - m * 3.3077115913 + s * 0.2309699292
+  local green = l * -1.2684380046 + m * 2.6097574011 - s * 0.3413193965
+  local blue = l * -0.0041960863 - m * 0.7034186147 + s * 1.7076147010
+
+  if not unclamped then
+    red = math.clamp(red, 0, 1)
+    green = math.clamp(green, 0, 1)
+    blue = math.clamp(blue, 0, 1)
+  end
+
+  return Color3.new(red, green, blue)
+end
+
+-- Converts a Vector3 in Oklab space to a Color3 in sRGB space.
+-- The Color3 will be clamped by default unless specified otherwise.
+function Oklab.toSRGB(lab: Vector3, unclamped: boolean?): Color3
+  return sRGB.fromLinear(Oklab.toLinear(lab, unclamped))
+end
+
+return Oklab

package/out/mod/color/sRGB.luau

@@ -0,0 +1,71 @@
+--[[
+MIT License
+
+Copyright (c) 2024 Daniel P H Fox
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE 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. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+]]
+
+--!strict
+--!nolint LocalUnused
+--!nolint LocalShadow
+local task = nil -- Disable usage of Roblox's task scheduler
+
+--[[
+    Provides transformation functions for converting linear RGB values
+    into sRGB values.
+
+    RGB color channel transformations are outlined here:
+    https://bottosson.github.io/posts/colorwrong/#what-can-we-do%3F
+]]
+
+local sRGB = {}
+
+-- Equivalent to f_inv. Takes a linear sRGB channel and returns
+-- the sRGB channel
+local function transform(channel: number): number
+  if channel < 0.04045 then
+    return channel / 12.92
+  end
+
+  return ((channel + 0.055) / 1.055) ^ 2.4
+end
+
+-- Equivalent to f. Takes an sRGB channel and returns
+-- the linear sRGB channel
+local function inverse(channel: number): number
+  if channel < 0.0031308 then
+    return 12.92 * channel
+  end
+
+  return (1.055 * channel ^ (1 / 2.4)) - 0.055
+end
+
+-- Uses a transformation to convert linear RGB into sRGB.
+function sRGB.fromLinear(rgb: Color3): Color3
+  return Color3.new(inverse(rgb.R), inverse(rgb.G), inverse(rgb.B))
+end
+
+-- Converts an sRGB into linear RGB using a
+-- (The inverse of sRGB.fromLinear).
+function sRGB.toLinear(srgb: Color3): Color3
+  return Color3.new(transform(srgb.R), transform(srgb.G), transform(srgb.B))
+end
+
+return sRGB