@quenty/sounds 4.0.0-canary.236.5597d0a.0 → 4.1.0

package/CHANGELOG.md

@@ -3,7 +3,66 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
-# [4.0.0-canary.236.5597d0a.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/sounds@3.4.0...@quenty/sounds@4.0.0-canary.236.5597d0a.0) (2021-12-18)
+# [4.1.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/sounds@4.0.0...@quenty/sounds@4.1.0) (2022-03-10)
+
+**Note:** Version bump only for package @quenty/sounds
+
+
+
+
+
+# [4.0.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/sounds@3.8.0...@quenty/sounds@4.0.0) (2022-03-06)
+
+
+### Bug Fixes
+
+* Support sound playback for non-local situations. On the server this will require the sound to be parented. ([1884237](https://github.com/Quenty/NevermoreEngine/commit/1884237120fbbb3c9b29032d995c132af381f16b))
+
+
+
+
+
+# [3.8.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/sounds@3.7.1...@quenty/sounds@3.8.0) (2022-01-17)
+
+**Note:** Version bump only for package @quenty/sounds
+
+
+
+
+
+## [3.7.1](https://github.com/Quenty/NevermoreEngine/compare/@quenty/sounds@3.7.0...@quenty/sounds@3.7.1) (2022-01-16)
+
+**Note:** Version bump only for package @quenty/sounds
+
+
+
+
+
+# [3.7.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/sounds@3.6.0...@quenty/sounds@3.7.0) (2022-01-07)
+
+**Note:** Version bump only for package @quenty/sounds
+
+
+
+
+
+# [3.6.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/sounds@3.5.1...@quenty/sounds@3.6.0) (2022-01-03)
+
+**Note:** Version bump only for package @quenty/sounds
+
+
+
+
+
+## [3.5.1](https://github.com/Quenty/NevermoreEngine/compare/@quenty/sounds@3.5.0...@quenty/sounds@3.5.1) (2021-12-30)
+
+**Note:** Version bump only for package @quenty/sounds
+
+
+
+
+
+# [3.5.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/sounds@3.4.0...@quenty/sounds@3.5.0) (2021-12-18)
 
 **Note:** Version bump only for package @quenty/sounds
 

package/README.md

@@ -1,10 +1,10 @@
 ## SoundPromiseUtils
 <div align="center">
-  <a href="http://quenty.github.io/api/">
-    <img src="https://img.shields.io/badge/docs-website-green.svg" alt="Documentation" />
+  <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/badge/discord-nevermore-blue.svg" alt="Discord" />
+    <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" />
@@ -13,15 +13,9 @@
 
 Utility functions involving sounds and their state
 
+<div align="center"><a href="https://quenty.github.io/NevermoreEngine/api/SoundUtils">View docs →</a></div>
+
 ## Installation
 ```
 npm install @quenty/soundpromiseutils --save
-```
-
-## Usage
-Usage is designed to be simple.
-
-### `SoundPromiseUtils.promiseLoaded(sound)`
-
-### `SoundPromiseUtils.promiseAllSoundsLoaded(sounds)`
-
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/sounds",
-  "version": "4.0.0-canary.236.5597d0a.0",
+  "version": "4.1.0",
   "description": "Utility functions involving sounds and their state",
   "keywords": [
     "Roblox",
@@ -26,11 +26,11 @@
     "Quenty"
   ],
   "dependencies": {
-    "@quenty/loader": "3.1.1",
-    "@quenty/promise": "4.0.0-canary.236.5597d0a.0"
+    "@quenty/loader": "^4.0.0",
+    "@quenty/promise": "^4.1.0"
   },
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "5597d0abdadd88f369f1401a558a8d6d1a1c5aab"
+  "gitHead": "0797de955876b050fb24875de0423453e268b2ce"
 }

package/src/Shared/SoundPromiseUtils.lua

@@ -1,6 +1,7 @@
---- Utility functions involving sounds and their state
--- @module SoundPromiseUtils
--- @author Quenty
+--[=[
+	Utility functions involving sounds and their state
+	@class SoundPromiseUtils
+]=]
 
 local require = require(script.Parent.loader).load(script)
 
@@ -9,6 +10,11 @@ local PromiseUtils = require("PromiseUtils")
 
 local SoundPromiseUtils = {}
 
+--[=[
+	Promises that a sound is loaded
+	@param sound Sound
+	@return Promise
+]=]
 function SoundPromiseUtils.promiseLoaded(sound)
 	if sound.IsLoaded then
 		return Promise.resolved()
@@ -31,6 +37,11 @@ function SoundPromiseUtils.promiseLoaded(sound)
 	return promise
 end
 
+--[=[
+	Promises that all sounds are loaded
+	@param sounds { Sound }
+	@return Promise
+]=]
 function SoundPromiseUtils.promiseAllSoundsLoaded(sounds)
 	local promises = {}
 	for _, sound in pairs(sounds) do

package/src/Shared/SoundUtils.lua

@@ -1,19 +1,47 @@
---- Helps play sounds on the client
--- @module SoundUtils
--- @author Quenty
+--[=[
+	Helps plays back sounds in the Roblox engine.
+
+	```lua
+	SoundUtils.playFromId("rbxassetid://4255432837") -- Plays a wooshing sound
+	```
+
+	@class SoundUtils
+]=]
 
 local SoundService = game:GetService("SoundService")
+local RunService = game:GetService("RunService")
 
 local SoundUtils = {}
 
-function SoundUtils.playTemplate(templates, templateName)
-	assert(type(templates) == "table", "Bad templates")
-	assert(type(templateName) == "string", "Bad templateName")
+--[=[
+	Plays back a template given asset id.
 
-	local sound = templates:Clone(templateName)
+	```lua
+	SoundUtils.playFromId("rbxassetid://4255432837") -- Plays a wooshing sound
+	```
+
+	:::tip
+	The sound will be automatically cleaned up after the sound is played.
+	:::
+
+	@param id string | number
+	@return Sound
+]=]
+function SoundUtils.playFromId(id)
+	local soundId = SoundUtils.toRbxAssetId(id)
+	assert(type(soundId) == "string", "Bad id")
+
+	local sound = Instance.new("Sound")
+	sound.Name = ("Sound_%s"):format(soundId)
+	sound.SoundId = soundId
+	sound.Volume = 0.25
 	sound.Archivable = false
 
-	SoundService:PlayLocalSound(sound)
+	if RunService:IsClient() then
+		SoundService:PlayLocalSound(sound)
+	else
+		sound:Play()
+	end
 
 	task.delay(sound.TimeLength + 0.05, function()
 		sound:Destroy()
@@ -22,14 +50,22 @@ function SoundUtils.playTemplate(templates, templateName)
 	return sound
 end
 
-function SoundUtils.playFromId(id)
-	local soundId = SoundUtils.toRbxAssetId(id)
-	assert(type(soundId) == "string", "Bad id")
+--[=[
+	Plays back a template given the templateName.
 
-	local sound = Instance.new("Sound")
-	sound.Name = ("Sound_%s"):format(soundId)
-	sound.SoundId = soundId
-	sound.Volume = 0.25
+	:::tip
+	The sound will be automatically cleaned up after the sound is played.
+	:::
+
+	@param templates TemplateProvider
+	@param templateName string
+	@return Sound
+]=]
+function SoundUtils.playTemplate(templates, templateName)
+	assert(type(templates) == "table", "Bad templates")
+	assert(type(templateName) == "string", "Bad templateName")
+
+	local sound = templates:Clone(templateName)
 	sound.Archivable = false
 
 	SoundService:PlayLocalSound(sound)
@@ -41,6 +77,11 @@ function SoundUtils.playFromId(id)
 	return sound
 end
 
+--[=[
+	Converts a string or number to a string for playback.
+	@param id string | number
+	@return string
+]=]
 function SoundUtils.toRbxAssetId(id)
 	if type(id) == "number" then
 		return ("rbxassetid://%d"):format(id)
@@ -49,6 +90,18 @@ function SoundUtils.toRbxAssetId(id)
 	end
 end
 
+--[=[
+	Plays back a sound template in a specific parent.
+
+	:::tip
+	The sound will be automatically cleaned up after the sound is played.
+	:::
+
+	@param templates TemplateProvider
+	@param templateName string
+	@param parent Instance
+	@return Sound
+]=]
 function SoundUtils.playTemplateInParent(templates, templateName, parent)
 	local sound = templates:Clone(templateName)
 	sound.Archivable = false
@@ -63,5 +116,4 @@ function SoundUtils.playTemplateInParent(templates, templateName, parent)
 	return sound
 end
 
-
 return SoundUtils