@quenty/bodycolorsutils 1.0.1-canary.345.60686f2.0

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
+
+## 1.0.1-canary.345.60686f2.0 (2023-03-31)
+
+
+### Bug Fixes
+
+* Fix body color serialization and add additional attribute support ([4490c02](https://github.com/Quenty/NevermoreEngine/commit/4490c02d990b9531ef6f4a49340be06a26f1ee52))
+
+
+### Features
+
+* Add baseline bodycolors package ([04cb07f](https://github.com/Quenty/NevermoreEngine/commit/04cb07fa0ae789f1534ea4310120c2dde97c1d4e))
+* Add BodyColorsDataUtils ([80aa539](https://github.com/Quenty/NevermoreEngine/commit/80aa53906a1ff4e3a736fd4a3cacc861b047c6e5))
+* Add RxBodyColorDataUtils ([2eb64e2](https://github.com/Quenty/NevermoreEngine/commit/2eb64e24f643a75e926eb32cc35775a2da7e1196))
+* Add serialization ([f08cbce](https://github.com/Quenty/NevermoreEngine/commit/f08cbce0e807ec1c911b48f88cd3c34dbefc11a3))

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2014-2023 James Onnen (Quenty)
+
+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.

package/README.md

@@ -0,0 +1,23 @@
+## BodyColorsUtils
+
+<div align="center">
+  <a href="http://quenty.github.io/NevermoreEngine/">
+    <img src="https://github.com/Quenty/NevermoreEngine/actions/workflows/docs.yml/badge.svg" alt="Documentation status" />
+  </a>
+  <a href="https://discord.gg/mhtGUS8">
+    <img src="https://img.shields.io/discord/385151591524597761?color=5865F2&label=discord&logo=discord&logoColor=white" alt="Discord" />
+  </a>
+  <a href="https://github.com/Quenty/NevermoreEngine/actions">
+    <img src="https://github.com/Quenty/NevermoreEngine/actions/workflows/build.yml/badge.svg" alt="Build and release status" />
+  </a>
+</div>
+
+Body color helper utilities for merging and representing body colors over the network and datastore
+
+<div align="center"><a href="https://quenty.github.io/NevermoreEngine/api/BodyColorsDataUtils">View docs →</a></div>
+
+## Installation
+
+```
+npm install @quenty/bodycolorsutils --save
+```

package/default.project.json

@@ -0,0 +1,6 @@
+{
+  "name": "bodycolorsutils",
+  "tree": {
+    "$path": "src"
+  }
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@quenty/bodycolorsutils",
+  "version": "1.0.1-canary.345.60686f2.0",
+  "description": "Body color helper utilities for merging and representing body colors over the network and datastore",
+  "keywords": [
+    "Roblox",
+    "Nevermore",
+    "Lua",
+    "bodycolorutils"
+  ],
+  "bugs": {
+    "url": "https://github.com/Quenty/NevermoreEngine/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Quenty/NevermoreEngine.git",
+    "directory": "src/bodycolorsutils/"
+  },
+  "funding": {
+    "type": "patreon",
+    "url": "https://www.patreon.com/quenty"
+  },
+  "license": "MIT",
+  "contributors": [
+    "Quenty"
+  ],
+  "dependencies": {
+    "@quenty/attributeutils": "8.8.0",
+    "@quenty/color3serializationutils": "2.1.0",
+    "@quenty/color3utils": "5.12.1-canary.345.60686f2.0",
+    "@quenty/loader": "6.2.0",
+    "@quenty/rx": "7.7.0",
+    "@quenty/table": "3.2.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "gitHead": "60686f2af2e3db9a768ca47d2636bf84ea263494"
+}

package/src/Shared/BodyColorsDataConstants.lua

@@ -0,0 +1,18 @@
+--[=[
+	@class BodyColorsDataConstants
+]=]
+
+local require = require(script.Parent.loader).load(script)
+
+local Table = require("Table")
+
+return Table.readonly({
+	ATTRIBUTE_MAPPING = {
+		headColor = "HeadColor";
+		leftArmColor = "LeftArmColor";
+		leftLegColor = "LeftLegColor";
+		rightArmColor = "RightArmColor";
+		rightLegColor = "RightLegColor";
+		torsoColor = "TorsoColor";
+	};
+})

package/src/Shared/BodyColorsDataUtils.lua

@@ -0,0 +1,326 @@
+--[=[
+	Utility to transfer and manipulate body colors for a character
+
+	@class BodyColorsDataUtils
+]=]
+
+local require = require(script.Parent.loader).load(script)
+
+local Color3Utils = require("Color3Utils")
+local Color3SerializationUtils = require("Color3SerializationUtils")
+local BodyColorsDataConstants = require("BodyColorsDataConstants")
+
+local BodyColorsDataUtils = {}
+
+--[=[
+	Represents body colors data for a humanoid
+
+	@interface BodyColorsData
+	.headColor Color3
+	.leftArmColor Color3
+	.leftLegColor Color3
+	.rightArmColor Color3
+	.rightLegColor Color3
+	.torsoColor Color3
+	@within BodyColorsDataUtils
+]=]
+
+--[=[
+	Creates a new BodyColorsData
+	@param bodyColorsData any
+	@return BodyColorsData
+]=]
+function BodyColorsDataUtils.createBodyColorsData(bodyColorsData)
+	assert(BodyColorsDataUtils.isBodyColorsData(bodyColorsData), "Bad bodyColorsData")
+
+	return bodyColorsData
+end
+
+--[=[
+	Returns true if it's a body color data
+	@param value any
+	@return boolean
+]=]
+function BodyColorsDataUtils.isBodyColorsData(value)
+	return type(value) == "table"
+		and (typeof(value.headColor) == "Color3" or value.headColor == nil)
+		and (typeof(value.leftArmColor) == "Color3" or value.leftArmColor == nil)
+		and (typeof(value.leftLegColor) == "Color3" or value.leftLegColor == nil)
+		and (typeof(value.rightArmColor) == "Color3" or value.rightArmColor == nil)
+		and (typeof(value.rightLegColor) == "Color3" or value.rightLegColor == nil)
+		and (typeof(value.torsoColor) == "Color3" or value.torsoColor == nil)
+end
+
+--[=[
+	Creates a new BodyColorsData from a single color
+
+	@param color3 Color3
+	@return BodyColorsData
+]=]
+function BodyColorsDataUtils.fromSingleColor(color3)
+	assert(typeof(color3) == "Color3", "Bad color3")
+
+	return BodyColorsDataUtils.createBodyColorsData({
+		headColor = color3;
+		leftArmColor = color3;
+		leftLegColor = color3;
+		rightArmColor = color3;
+		rightLegColor = color3;
+		torsoColor = color3;
+	})
+end
+
+--[=[
+	Creates a new BodyColorsData from a BodyColors instance
+
+	@param bodyColors BodyColors
+	@return BodyColorsData
+]=]
+function BodyColorsDataUtils.fromBodyColors(bodyColors)
+	assert(typeof(bodyColors) == "Instance" and bodyColors:IsA("BodyColors"), "Bad bodyColors")
+
+	return BodyColorsDataUtils.createBodyColorsData({
+		headColor = bodyColors.HeadColor3;
+		leftArmColor = bodyColors.LeftArmColor3;
+		leftLegColor = bodyColors.LeftLegColor3;
+		rightArmColor = bodyColors.RightArmColor3;
+		rightLegColor = bodyColors.RightLegColor3;
+		torsoColor = bodyColors.TorsoColor3;
+	})
+end
+
+--[=[
+	Returns true if the data is a datastore safe body color
+	@param value any
+	@return boolean
+]=]
+function BodyColorsDataUtils.isDataStoreSafeBodyColorsData(value)
+	return type(value) == "table"
+		and (Color3SerializationUtils.isSerializedColor3(value.headColor) or value.headColor == nil)
+		and (Color3SerializationUtils.isSerializedColor3(value.leftArmColor) or value.leftArmColor == nil)
+		and (Color3SerializationUtils.isSerializedColor3(value.leftLegColor) or value.leftLegColor == nil)
+		and (Color3SerializationUtils.isSerializedColor3(value.rightArmColor) or value.rightArmColor == nil)
+		and (Color3SerializationUtils.isSerializedColor3(value.rightLegColor) or value.rightLegColor == nil)
+		and (Color3SerializationUtils.isSerializedColor3(value.torsoColor) or value.torsoColor == nil)
+end
+
+--[=[
+	Gets a datastore safe version of body color
+	@param bodyColorsData BodyColorsData
+	@return DataStoreSafeBodyColorsData
+]=]
+function BodyColorsDataUtils.toDataStoreSafeBodyColorsData(bodyColorsData)
+	assert(BodyColorsDataUtils.isBodyColorsData(bodyColorsData), "Bad bodyColorsData")
+
+	return {
+		headColor = bodyColorsData.headColor and Color3SerializationUtils.serialize(bodyColorsData.headColor) or nil;
+		leftArmColor = bodyColorsData.leftArmColor and Color3SerializationUtils.serialize(bodyColorsData.leftArmColor) or nil;
+		leftLegColor = bodyColorsData.leftLegColor and Color3SerializationUtils.serialize(bodyColorsData.leftLegColor) or nil;
+		rightArmColor = bodyColorsData.rightArmColor and Color3SerializationUtils.serialize(bodyColorsData.rightArmColor) or nil;
+		rightLegColor = bodyColorsData.rightLegColor and Color3SerializationUtils.serialize(bodyColorsData.rightLegColor) or nil;
+		torsoColor = bodyColorsData.torsoColor and Color3SerializationUtils.serialize(bodyColorsData.torsoColor) or nil;
+	}
+end
+
+function BodyColorsDataUtils.fromDataStoreSafeBodyColorsData(data)
+	assert(BodyColorsDataUtils.isDataStoreSafeBodyColorsData(data), "Bad dataStoreSafeBodyColorsData")
+
+	return BodyColorsDataUtils.createBodyColorsData({
+		headColor = data.headColor and Color3SerializationUtils.deserialize(data.headColor) or nil;
+		leftArmColor = data.leftArmColor and Color3SerializationUtils.deserialize(data.leftArmColor) or nil;
+		leftLegColor = data.leftLegColor and Color3SerializationUtils.deserialize(data.leftLegColor) or nil;
+		rightArmColor = data.rightArmColor and Color3SerializationUtils.deserialize(data.rightArmColor) or nil;
+		rightLegColor = data.rightLegColor and Color3SerializationUtils.deserialize(data.rightLegColor) or nil;
+		torsoColor = data.torsoColor and Color3SerializationUtils.deserialize(data.torsoColor) or nil;
+	})
+end
+
+--[=[
+	Constructs a BodyColorsData from a humanoidDescription
+
+	@param humanoidDescription HumanoidDescription
+	@return BodyColorsData
+]=]
+function BodyColorsDataUtils.fromHumanoidDescription(humanoidDescription)
+	assert(typeof(humanoidDescription) == "Instance" and humanoidDescription:IsA("HumanoidDescription"), "Bad humanoidDescription")
+
+	return BodyColorsDataUtils.createBodyColorsData({
+		headColor = humanoidDescription.HeadColor;
+		leftArmColor = humanoidDescription.LeftArmColor;
+		leftLegColor = humanoidDescription.LeftLegColor;
+		rightArmColor = humanoidDescription.RightArmColor;
+		rightLegColor = humanoidDescription.RightLegColor;
+		torsoColor = humanoidDescription.TorsoColor;
+	})
+end
+
+--[=[
+	Returns if the body colors data represents one solid color for all body parts.
+
+	@param bodyColorsData BodyColorsData
+	@return boolean
+]=]
+function BodyColorsDataUtils.isSingleColor(bodyColorsData)
+	assert(BodyColorsDataUtils.isBodyColorsData(bodyColorsData), "Bad bodyColorsData")
+
+	local headColor = bodyColorsData.headColor
+	if headColor == nil then
+		return false
+	end
+
+	if bodyColorsData.leftArmColor == nil or not Color3Utils.areEqual(headColor, bodyColorsData.leftArmColor) then
+		return false
+	end
+
+	if bodyColorsData.leftLegColor == nil or not Color3Utils.areEqual(headColor, bodyColorsData.leftLegColor) then
+		return false
+	end
+
+	if bodyColorsData.rightArmColor == nil or not Color3Utils.areEqual(headColor, bodyColorsData.rightArmColor) then
+		return false
+	end
+
+	if bodyColorsData.rightLegColor == nil or not Color3Utils.areEqual(headColor, bodyColorsData.rightLegColor) then
+		return false
+	end
+
+	if bodyColorsData.torsoColor == nil or not Color3Utils.areEqual(headColor, bodyColorsData.torsoColor) then
+		return false
+	end
+
+	return true
+end
+
+--[=[
+	Constructs a BodyColors from the bodyColorsData
+
+	@param bodyColorsData BodyColorsData
+	@return BodyColors
+]=]
+function BodyColorsDataUtils.toBodyColors(bodyColorsData)
+	assert(BodyColorsDataUtils.isBodyColorsData(bodyColorsData), "Bad bodyColorsData")
+
+	local bodyColors = Instance.new("BodyColors")
+	BodyColorsDataUtils.applyToBodyColors(bodyColors, bodyColorsData)
+
+	return bodyColors
+end
+
+--[=[
+	Applies body colors to the actual body color property
+
+	@param bodyColorsData BodyColorsData
+	@param bodyColors BodyColors
+	@return BodyColors
+]=]
+function BodyColorsDataUtils.applyToBodyColors(bodyColorsData, bodyColors)
+	assert(BodyColorsDataUtils.isBodyColorsData(bodyColorsData), "Bad bodyColorsData")
+	assert(typeof(bodyColors) == "Instance" and bodyColors:IsA("BodyColors"), "Bad bodyColors")
+
+	if bodyColorsData.headColor then
+		bodyColors.HeadColor3 = bodyColorsData.headColor
+	end
+
+	if bodyColorsData.leftArmColor then
+		bodyColors.LeftArmColor3 = bodyColorsData.leftArmColor
+	end
+
+	if bodyColorsData.leftLegColor then
+		bodyColors.LeftLegColor3 = bodyColorsData.leftLegColor
+	end
+
+	if bodyColorsData.rightArmColor then
+		bodyColors.RightArmColor3 = bodyColorsData.rightArmColor
+	end
+
+	if bodyColorsData.rightLegColor then
+		bodyColors.RightLegColor3 = bodyColorsData.rightLegColor
+	end
+
+	if bodyColorsData.torsoColor then
+		bodyColors.TorsoColor3 = bodyColorsData.torsoColor
+	end
+end
+
+--[=[
+	Extracts body colors from attributes
+	@param instance Instance
+	@return BodyColorsData
+]=]
+function BodyColorsDataUtils.fromAttributes(instance)
+	assert(typeof(instance) == "Instance", "Bad instance")
+
+	local bodyColorsData = {}
+
+	for key, attributeName in pairs(BodyColorsDataConstants.ATTRIBUTE_MAPPING) do
+		local value = instance:GetAttribute(attributeName)
+		if value ~= nil then
+			if typeof(value) == "Color3" then
+				bodyColorsData[key] = value
+			else
+				warn(string.format("[BodyColorsDataUtils.fromAttributes] - Bad attribute %q of type %q",
+					attributeName,
+					typeof(value)))
+			end
+		end
+	end
+
+	return BodyColorsDataUtils.createBodyColorsData(bodyColorsData)
+end
+
+--[=[
+	Sets attributes to store body colors.
+	@param instance Instance
+	@param bodyColorsData BodyColorsData
+]=]
+function BodyColorsDataUtils.setAttributes(instance, bodyColorsData)
+	assert(typeof(instance) == "Instance", "Bad instance")
+	assert(BodyColorsDataUtils.isBodyColorsData(bodyColorsData), "Bad bodyColorsData")
+
+	for key, attributeName in pairs(BodyColorsDataConstants.ATTRIBUTE_MAPPING) do
+		local value = bodyColorsData[key]
+		if value then
+			instance:SetAttribute(attributeName, value)
+		else
+			instance:SetAttribute(attributeName, nil)
+		end
+	end
+end
+
+--[=[
+	Applies body colors to the actual body color property
+
+	@param bodyColorsData BodyColorsData
+	@param humanoidDescription HumanoidDescription
+	@return BodyColors
+]=]
+function BodyColorsDataUtils.applyToHumanoidDescription(bodyColorsData, humanoidDescription)
+	assert(BodyColorsDataUtils.isBodyColorsData(bodyColorsData), "Bad bodyColorsData")
+	assert(typeof(humanoidDescription) == "Instance" and humanoidDescription:IsA("HumanoidDescription"), "Bad humanoidDescription")
+
+	if bodyColorsData.headColor then
+		humanoidDescription.HeadColor = bodyColorsData.headColor
+	end
+
+	if bodyColorsData.leftArmColor then
+		humanoidDescription.LeftArmColor = bodyColorsData.leftArmColor
+	end
+
+	if bodyColorsData.leftLegColor then
+		humanoidDescription.LeftLegColor = bodyColorsData.leftLegColor
+	end
+
+	if bodyColorsData.rightArmColor then
+		humanoidDescription.RightArmColor = bodyColorsData.rightArmColor
+	end
+
+	if bodyColorsData.rightLegColor then
+		humanoidDescription.RightLegColor = bodyColorsData.rightLegColor
+	end
+
+	if bodyColorsData.torsoColor then
+		humanoidDescription.TorsoColor = bodyColorsData.torsoColor
+	end
+end
+
+return BodyColorsDataUtils

package/src/Shared/RxBodyColorsDataUtils.lua

@@ -0,0 +1,49 @@
+--[=[
+	@class RxBodyColorsDataUtils
+]=]
+
+local require = require(script.Parent.loader).load(script)
+
+local Rx = require("Rx")
+local BodyColorsDataConstants = require("BodyColorsDataConstants")
+local RxAttributeUtils = require("RxAttributeUtils")
+local BodyColorsDataUtils = require("BodyColorsDataUtils")
+
+local RxBodyColorsDataUtils = {}
+
+--[=[
+	Observes the current body colors data from attributes
+
+	@param instance Instance
+	@return Observable<BodyColorsData>
+]=]
+function RxBodyColorsDataUtils.observeFromAttributes(instance)
+	assert(typeof(instance) == "Instance", "Bad instance")
+
+	local observables = {}
+
+	for key, attributeName in pairs(BodyColorsDataConstants.ATTRIBUTE_MAPPING) do
+		observables[key] = RxAttributeUtils.observeAttribute(instance, attributeName)
+	end
+
+	return Rx.combineLatest(observables):Pipe({
+		Rx.map(function(latestValues)
+			for key, attributeName in pairs(BodyColorsDataConstants.ATTRIBUTE_MAPPING) do
+				local bodyColorsData = {}
+
+				local value = latestValues[key]
+				if typeof(value) == "Color3" then
+					bodyColorsData[key] = value
+				else
+					warn(string.format("[RxBodyColorsDataUtils.observeFromAttributes] - Bad attribute %q of type %q",
+						attributeName,
+						typeof(value)))
+				end
+
+				return BodyColorsDataUtils.createBodyColorsData(bodyColorsData)
+			end
+		end);
+	})
+end
+
+return RxBodyColorsDataUtils

package/src/node_modules.project.json

@@ -0,0 +1,7 @@
+{
+  "name": "node_modules",
+  "globIgnorePaths": [ "**/.package-lock.json" ],
+  "tree": {
+    "$path": { "optional": "../node_modules" }
+  }
+}