@quenty/animations 1.0.1-canary.385.c37a0ad.0

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# 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.385.c37a0ad.0 (2023-07-10)
+
+
+### Features
+
+* Add utility package to play back animations easily ([46c33ea](https://github.com/Quenty/NevermoreEngine/commit/46c33ea401987b14ba9c674280e56cd5d4cfe530))

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 @@
+## Animations
+
+<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>
+
+Utility methods for playing back animations on Roblox
+
+<div align="center"><a href="https://quenty.github.io/NevermoreEngine/api/AnimationsUtils">View docs →</a></div>
+
+## Installation
+
+```
+npm install @quenty/animations --save
+```

package/default.project.json

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

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@quenty/animations",
+  "version": "1.0.1-canary.385.c37a0ad.0",
+  "description": "Utility methods for playing back animations on Roblox",
+  "keywords": [
+    "Roblox",
+    "Nevermore",
+    "Lua",
+    "animations"
+  ],
+  "bugs": {
+    "url": "https://github.com/Quenty/NevermoreEngine/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Quenty/NevermoreEngine.git",
+    "directory": "src/animations/"
+  },
+  "funding": {
+    "type": "patreon",
+    "url": "https://www.patreon.com/quenty"
+  },
+  "license": "MIT",
+  "contributors": [
+    "Quenty"
+  ],
+  "dependencies": {
+    "@quenty/enumutils": "3.1.0",
+    "@quenty/humanoidanimatorutils": "2.1.2-canary.385.c37a0ad.0",
+    "@quenty/loader": "6.2.1",
+    "@quenty/promisemaid": "1.1.0",
+    "@quenty/rbxasset": "1.0.1-canary.385.c37a0ad.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "gitHead": "c37a0ad3981a0e27d4d9db436a0f21e675b12bf0"
+}

package/src/Shared/AnimationPromiseUtils.lua

@@ -0,0 +1,32 @@
+--[=[
+	@class AnimationPromiseUtils
+]=]
+
+local require = require(script.Parent.loader).load(script)
+
+local Promise = require("Promise")
+local PromiseMaidUtils = require("PromiseMaidUtils")
+
+local AnimationPromiseUtils = {}
+
+function AnimationPromiseUtils.promiseFinished(animationTrack)
+	local promise = Promise.new()
+
+	PromiseMaidUtils.whilePromise(promise, function(maid)
+		maid:GiveTask(animationTrack.Ended:Connect(function()
+			promise:Resolve()
+		end))
+
+		maid:GiveTask(animationTrack.Stopped:Connect(function()
+			promise:Resolve()
+		end))
+
+		maid:GiveTask(animationTrack.Destroying:Connect(function()
+			promise:Resolve()
+		end))
+	end)
+
+	return promise
+end
+
+return AnimationPromiseUtils

package/src/Shared/AnimationUtils.lua

@@ -0,0 +1,212 @@
+--[=[
+	@class AnimationUtils
+]=]
+
+local require = require(script.Parent.loader).load(script)
+
+local RbxAssetUtils = require("RbxAssetUtils")
+local HumanoidAnimatorUtils = require("HumanoidAnimatorUtils")
+local EnumUtils = require("EnumUtils")
+
+local AnimationUtils = {}
+
+--[=[
+	Plays the animation on the target instance.
+
+	@return AnimationTrack?
+]=]
+function AnimationUtils.playAnimation(
+	target: Animator | Player | Model | AnimationController,
+	id: string | number,
+	fadeTime: number?,
+	weight: number?,
+	speed: number?,
+	priority: AnimationPriority?): AnimationTrack?
+	assert(typeof(target) == "Instance", "Bad target")
+	assert(RbxAssetUtils.isConvertableToRbxAsset(id), "Bad id")
+	assert(type(fadeTime) == "number" or fadeTime == nil, "Bad fadeTime")
+	assert(type(weight) == "number" or weight == nil, "Bad weight")
+	assert(type(speed) == "number" or speed == nil, "Bad speed")
+	assert(EnumUtils.isOfType(Enum.AnimationPriority, priority) or priority == nil, "Bad priority")
+
+	local animationTrack = AnimationUtils.getOrCreateAnimationTrack(target, id, priority)
+
+	if animationTrack then
+		animationTrack:Play(fadeTime, weight, speed)
+
+		if priority then
+			animationTrack.Priority = priority
+		end
+	else
+		warn(string.format("[AnimationUtils] - Failed to play animationTrack %q", tostring(id)))
+	end
+
+	return animationTrack
+end
+
+--[=[
+	Stops the animation on the target instance.
+]=]
+function AnimationUtils.stopAnimation(target: Animator | Player | Model | AnimationController, id: string | number, fadeTime: number?): AnimationTrack?
+	assert(typeof(target) == "Instance", "Bad target")
+	assert(RbxAssetUtils.isConvertableToRbxAsset(id), "Bad id")
+	assert(type(fadeTime) == "number" or fadeTime == nil, "Bad fadeTime")
+
+	local animationTrack = AnimationUtils.findAnimationTrack(target, id)
+
+	if animationTrack then
+		animationTrack:Stop(fadeTime)
+	end
+
+	return animationTrack
+end
+
+--[=[
+	Gets or creates an animation track for the player
+]=]
+function AnimationUtils.getOrCreateAnimationTrack(
+	target: Animator | Player | Model | AnimationController,
+	id: string | number,
+	priority: AnimationPriority?): AnimationTrack?
+	assert(typeof(target) == "Instance", "Bad target")
+	assert(RbxAssetUtils.isConvertableToRbxAsset(id), "Bad id")
+	assert(EnumUtils.isOfType(Enum.AnimationPriority, priority) or priority == nil, "Bad priority")
+
+	local animator = AnimationUtils.getOrCreateAnimator(target)
+	if not animator then
+		return nil
+	end
+
+	assert(typeof(animator) == "Instance" and animator:IsA("Animator"), "Bad animator")
+
+	local foundAnimationTrack = AnimationUtils.findAnimationTrackInAnimator(animator, id)
+	if foundAnimationTrack then
+		return foundAnimationTrack
+	end
+
+	local animation = AnimationUtils.getOrCreateAnimationFromIdInAnimator(animator, id)
+
+	local animationTrack
+	local ok, err = pcall(function()
+		animationTrack = animator:LoadAnimation(animation)
+	end)
+	if not ok then
+		warn(string.format("[AnimationUtils] - Failed to load animation with id %q due to %q", tostring(id), tostring(err)))
+		return nil
+	end
+
+	return animationTrack
+end
+
+function AnimationUtils.getOrCreateAnimationFromIdInAnimator(animator: Animator, id: string | number)
+	assert(typeof(animator) == "Instance" and animator:IsA("Animator"), "Bad animator")
+	assert(RbxAssetUtils.isConvertableToRbxAsset(id), "Bad id")
+
+	local animationId = RbxAssetUtils.toRbxAssetId(id)
+	for _, animation in pairs(animator:GetChildren()) do
+		if animation:IsA("Animation") then
+			if animation.AnimationId == animationId then
+				return animation
+			end
+		end
+	end
+
+	local animation = AnimationUtils.createAnimationFromId(id)
+	animation.Parent = animator
+
+	return animation
+end
+
+function AnimationUtils.findAnimationTrack(
+	target: Animator | Player | Model | AnimationController,
+	id: string | number)
+	assert(typeof(target) == "Instance", "Bad target")
+	assert(RbxAssetUtils.isConvertableToRbxAsset(id), "Bad id")
+
+	local animator = AnimationUtils.getOrCreateAnimator(target)
+	if not animator then
+		return nil
+	end
+
+	return AnimationUtils.findAnimationTrackInAnimator(animator, id)
+end
+
+function AnimationUtils.findAnimationTrackInAnimator(animator: Animator, id: string | number)
+	assert(typeof(animator) == "Instance" and animator:IsA("Animator"), "Bad animator")
+	assert(RbxAssetUtils.isConvertableToRbxAsset(id), "Bad id")
+
+	local animationId = RbxAssetUtils.toRbxAssetId(id)
+
+	for _, animationTrack in pairs(animator:GetPlayingAnimationTracks()) do
+		local animation = animationTrack.Animation
+		if animation and animation.AnimationId == animationId then
+			return animationTrack
+		end
+	end
+
+	return nil
+end
+
+--[=[
+	Finds an animator for the current instance
+]=]
+function AnimationUtils.getOrCreateAnimator(target: Animator | Player | Model | AnimationController)
+	assert(typeof(target) == "Instance", "Bad target")
+
+	if target:IsA("Animator") then
+		return target
+	elseif target:IsA("Humanoid") then
+		return HumanoidAnimatorUtils.getOrCreateAnimator(target)
+	elseif target:IsA("AnimationController") then
+		return HumanoidAnimatorUtils.getOrCreateAnimator(target)
+	elseif target:IsA("Player") then
+		local character = target.Character
+		if not character then
+			return nil
+		end
+
+		local humanoid = character:FindFirstChildWhichIsA("Humanoid")
+		if not humanoid then
+			return nil
+		end
+
+		return HumanoidAnimatorUtils.getOrCreateAnimator(humanoid)
+	elseif target:IsA("Model") then
+		local humanoid = target:FindFirstChildWhichIsA("Humanoid")
+		if humanoid then
+			return HumanoidAnimatorUtils.getOrCreateAnimator(humanoid)
+		end
+
+		local animationController = target:FindFirstChildWhichIsA("AnimationController")
+		if animationController then
+			return HumanoidAnimatorUtils.getOrCreateAnimator(animationController)
+		end
+
+		return nil
+	else
+		return nil
+	end
+end
+
+function AnimationUtils.getAnimationId(animationId)
+	return string.format("Animation_%s", animationId)
+end
+
+--[=[
+	Creates a new animation object from the given id
+]=]
+function AnimationUtils.createAnimationFromId(id: string | number): Animation
+	assert(RbxAssetUtils.isConvertableToRbxAsset(id), "Bad id")
+
+	local animationId = RbxAssetUtils.toRbxAssetId(id)
+	assert(type(animationId) == "string", "Bad id")
+
+	local animation = Instance.new("Animation")
+	animation.Name = AnimationUtils.getAnimationId(animationId)
+	animation.AnimationId = animationId
+	animation.Archivable = false
+
+	return animation
+end
+
+return AnimationUtils

package/src/node_modules.project.json

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

package/test/default.project.json

@@ -0,0 +1,21 @@
+{
+  "name": "AnimationTest",
+  "tree": {
+    "$className": "DataModel",
+    "ServerScriptService": {
+      "animations": {
+        "$path": ".."
+      },
+      "Script": {
+        "$path": "scripts/Server"
+      }
+    },
+    "StarterPlayer": {
+      "StarterPlayerScripts": {
+        "Main": {
+          "$path": "scripts/Client"
+        }
+      }
+    }
+  }
+}

package/test/scripts/Client/ClientMain.client.lua

@@ -0,0 +1,14 @@
+--[[
+	@class ClientMain
+]]
+local packages = game:GetService("ReplicatedStorage"):WaitForChild("Packages")
+
+local Players = game:GetService("Players")
+
+local AnimationUtils = require(packages:WaitForChild("AnimationUtils"))
+
+game.UserInputService.InputBegan:Connect(function(inputObject)
+	if inputObject.KeyCode == Enum.KeyCode.Q then
+		AnimationUtils.playAnimation(Players.LocalPlayer, "rbxassetid://14012074834", nil, nil, 1, Enum.AnimationPriority.Action3)
+	end
+end)

package/test/scripts/Server/ServerMain.server.lua

@@ -0,0 +1,8 @@
+--[[
+	@class ServerMain
+]]
+local ServerScriptService = game:GetService("ServerScriptService")
+
+local loader = ServerScriptService:FindFirstChild("LoaderUtils", true).Parent
+require(loader).bootstrapGame(ServerScriptService.animations)
+