jukebox.lua v1.4.0 - Custom overworld music, simplified

[KBM-Quine]

not using smwMap.lua for your overworld? don't want to switch to that because you already made your map but want more music? then this should suit you just fine.

made simply because i've explained it's possible and that no one wanted to do it plenty of times. i've now made this so i can direct people to it instead of re-explaining it.

this system also allows easier default music replacement by loading the music from either the base episode folder or a sub folder titled music. to use that feature, just rename the the file you'd like to replace the default music with the same name as the default file name (found in <smbx install>\data\music) i.e. smb3-world1.ogg (in the base of your episode folder or in a sub folder titled music) will play instead of the default SMB3 World 1 (Grass Land). as of 1.4, files that are autoloaded can be given path arguments. read the documentation for more information on that.
supported file formats for autoloading are as follows:

• .ogg
• .mp3
• .wav
• .spc
• .mid
• .midi
• .gbs
• .nsf
• .mod

hopefully that covers your choice of music.

as of 1.2, music.ini files auto fill the default 16 tracks like so:
basegame music.ini > directory auto load replacement method (see above) > episode music.ini
this is in an attempt to make usage even easier for existing episodes.

showcase video

basic use: show

- place the library in the base of your episode folder. you can place it elsewhere if you know what your doing, but this guide assumes your unfamiliar with this process.
- make a map.lua file in the base of your episode folder. this is most easily done by making a new text document and renaming it to map.lua (assuming you have show file extensions on. here's a guide on that for each windows version if you do not.) you can also use a text editor of choice to make one. select "All Files (".")" as the type and put .lua at the end of the filename when saving. make sure the file is map.lua and not map.lua.txt!
- place down a musicbox and take note of it's coordinates. you can get those by either holding ctrl while placing or right clicking the musicbox an going to - copy preference > position: X, Y (in the editor)
- from there use this code to load, register, and use the system in your map.lua file:

Code: Select all

local jukebox = require("jukebox")

jukebox.setTrack(track ID, "path to music file with extension")
jukebox.setMusicBoxTrack(track ID, musicbox X, musicbox Y)

breakdown of code:

jukebox.setTrack() - this sets the track of the specified track ID to the "path to music file", it only needs to be done once per ID. using 0 for the ID will return an error

track ID - the ID used by the system to determine the track to play. this can technically be anything. my personal recommendation is use the custom range (751-1000) when registering. just for sake of keeping things in-line with basegame systems. regardless, you can use any ID (even negative) except for 0. using it on IDs 1-16 will overwrite the default map music.

"path to music file with extension" - this is a string and does as the name implies. if your unfamiliar with lua, strings need backslashes to be escaped to be properly used. (like "music\\smb3-world1.spc" or something akin to that). alternatively, something like "music/smb3-world1.spc" also works. certain extensions can use path arguments, as of 1.4 those are supported without extra fuss.

jukebox.setMusicBox() - transforms the musicbox at the specified X/Y's ID to the track ID supplied. thus you'd use one of the IDs you used in a setTrack if using a custom one. this needs to be done for as many musicboxes as you want for the custom track ID your using. as of 1.4 index can be used in place of X/Y (so jukebox.setMusicBox(track ID, index)). there is no clean way to get that on the users end until beta 5/X2's next editor update. at which point you can use the copy preference method and select "Array ID; #" instead.

as of 1.2, an alias was added for jukebox.setMusicBox, jukebox.setMusicBoxTrack. it functions the same but was added because i felt the name for the former was a bit obtuse but didn't want to break compatibility.

disclaimer: this will not work properly if you have nested folders!
think of it like this: you have a level like so: "my episode folder\my level\my level.lvlx". this will break not only jukebox.lua, but a good chunk of other lua. always have levels in the base episode folder!

---

documentation: show

here are some additional functions you can use to control the system a bit:

jukebox.autoPlayMusic - bool; whether or not the system will auto play music upon start/touching a music box. can be used to call your own music changes. true by default.
jukebox.autoLoadPathArgs - table of strings; path arguments that get appended to auto loaded replacement music. you will need to directly add anything to this within jukebox.lua due to execution order. to use, append your entry under [".spc"] = "|0;g=2.7" in this format: [".extension"] = "|args", for path arguments, see this page
jukebox.getTrack(id) - returns the filename/path of the track of the ID given
jukebox.getPlayingTrack() - returns the filename/path of the track currently playing. will return nil if nothing is playing
jukebox.getPlayingTrackID() - returns the ID of the track currently playing. will return 0 if nothing is playing
jukebox.playTrack(trackID) - plays the track of the ID supplied.
jukebox.stopTrack() - stops the current music and sets track to 0.

---

changelog: show

--v1.2 (11/26/2021)--
- default 16 (17, but that one's reserved and only put in due to how this works) trackIDs are auto populated through the music.ini file in the base game directory.
-- this also allows episode music.inis to populate these tracks for ease of use, see the first post for more on how that works.
- fixed a bug where music didn't properly switch when pathing animations are active/after clearing a level.
- added an alias for jukebox.setMusicBox, jukebox.setMusicBoxTrack. for more info, check the "basic use" spoiler in the first post.
- spcs that use the "directory auto load replacement method" are given gain args automatically. see the first post for more details.
- some minor re-wording in some places of the "basic use" spoiler on the first post for clarity sake.
--v1.3 (2/13/2023)--
- removed jukebox.resolveMusicFile(). sorry for any inconvenience that might cause but it was ultimately useless.
- redid the method for getting the musicbox in jukebox.setMusicBox and added an error to explain why it might fail.
- tidied up the first post in an attempt to make it more readable.
--v1.3.1 (6/16/2023)--
- fixed a hard crash if one enters an overworld level that both points to a level file and has "go to X/Y" fields filled out, where the resulting go to coordinates have a musicbox with an ID greater then 16
--v1.4.0 (9/26/2023)--
- added some sanity checking to a good portion of code, enabling a bit of QoL stuff.
- path arguments can now be directly added to file paths without Misc.episodePath().
- added more errors to help catch mis-steps in user end code.
- fixed autoloading default music replacements (which broke at some point after 1.2...?)
- jukebox.setTrack() now errors if given 0. but allows for negative numbers.
- jukebox.playTrack(0) is replaced by jukebox.stopTrack(). calling jukebox.playTrack(0) will call jukebox.stopTrack(), keeping the functionality
- added jukebox.autoLoadPathArgs. see the documentation spoiler for details
- made jukebox.setMusicBox() now take musicbox index optionally if the y coordinate isn't supplied (making the x coordinate the index) see the basic use spoiler for details.

---

--Credit--
Horikawa Otane - code taken from classexpander.lua

feel free to give any feedback or report bugs, have a nice day.

[Marioman2007]

Ooh, really Nice! Finally we can have multiple overworld music.

[KBM-Quine]

seems i accidentally left jukebox.autoPlayMusic on false from my testing, oops! fixed that and put the version number to 1.0 proper. link is updated but a redownload isn't entirely necessary. if you don't want to redownload, just edit line 8 to true. or don't if it being false by default suits you fine.

[len]

this is going to be VERY useful

[SpencerlyEverly]

How can I normalize the music playing in the world map? Thinking of using this for my episode.

[KBM-Quine]

How can I normalize the music playing in the world map? Thinking of using this for my episode.

so looked into it, looks like you have to use the gain arg for .spc's. like "my song.spc|0;g=2.7;". you can read about music path args here

that all said, another update! read the first post for more, as well as the download in it has been updated

edit:small mistake, the gain arg was lower then intended. fixed.

[KBM-Quine]

bumping because i've updated to 1.2:
- default 16 (17, but that one's reserved and only put in due to how this works) trackIDs are auto populated through the music.ini file in the base game directory.
-- this also allows episode music.inis to populate these tracks for ease of use, see the first post for more on how that works.
- fixed a bug where music didn't properly switch when pathing animations are active/after clearing a level.
- added an alias for jukebox.setMusicBox, jukebox.setMusicBoxTrack. for more info, check the "basic use" spoiler in the first post.
- spcs that use the "directory auto load replacement method" are given gain args automatically. see the first post for more details.
- some minor re-wording in some places of the "basic use" spoiler on the first post for clarity sake.

[Dor_78]

track ID - the ID used by the system to determine the track to play. this can technically be anything. i'd recommend using the custom range (750-1000) when registering just for sake of keeping things in-line with base game systems. if one wants to replace the default 16 via lua, use the desired IDs with this.

How to use the custom range?

[KBM-Quine]

How to use the custom range?

The Custom Range is a range of IDs reserved for per-level and per-episode object replacements. These items are guaranteed to never have any basegame behaviour.

as this page outlines, it's just an ID range that is guaranteed to not be touched by basegame assets. i preffer to use this range for future proofing reasons. but if you need an exact use case, here:

Code: Select all

local jukebox = require("jukebox")

jukebox.setTrack(751, "06_The 8th Annual VLDC - MAP - Grass and Hub.wav")
jukebox.setTrack(752, "MAP - Ice and Sky.spc")

jukebox.setMusicBox(751, 704, 544)
jukebox.setMusicBox(752, -704, 800)

[Dor_78]

?????

[KBM-Quine]

?????

again, the page explains the concept as you previously asked. this library (and by extension myself) has no baring on what's in that page and it hardly applies here since this isn't a basegame library. this library is using the concept but not the actual system that doesn't exist yet. i won't be replying further for others' sakes

[Dor_78]

ohh
ok

[Pixelated_Perfection]

i have it set up like this


but it keeps giving me this error (even if i change it to OW\\)



what exactly am i doing wrong?

edit: nevermind we're troubleshooting it in the discord

[KBM-Quine]

helped the above problem and updated to 1.3:
- removed jukebox.resolveMusicFile(). sorry for any inconvenience that might cause but it was ultimately useless.
- redid the method for getting the musicbox in jukebox.setMusicBox and added an error to explain why it might fail.
- tidied up the first post in an attempt to make it more readable.

[Doodoxing]

Tried to use custom song in *.spc format with volume argument, but it shows me this error when entering a music box on world map. I used the method to replace a music box ID of 1 with custom file.

Code: Select all

local jukebox = require("jukebox") 

jukebox.setTrack(1,"27.spc|0;g=2;")

[KBM-Quine]

Tried to use custom song in *.spc format with volume argument, but it shows me this error when entering a music box on world map. I used the method to replace a music box ID of 1 with custom file.

append `Misc.episodePath() .. ` to the beginning of you file path (so that'd be `jukebox.setTrack(1, Misc.episodePath() .. "27.spc|0;g=2;")`. i'll leave a note in the op about it.

[Doodoxing]

Thanks for explaining this. I will try it.

[ditditdit]

WOW i needed this! thanks!

[KBM-Quine]

small update: fixed a hard crash if one enters an overworld level that both points to a level file and has "go to X/Y" fields filled out, where the resulting go to coordinates have a musicbox with an ID greater then 16. also added a changelog to the op. download is updated as well

[KBM-Quine]

new update! should make things less unwieldy. see the original post for more details.

--v1.4.0 (9/26/2023)--
- added some sanity checking to a good portion of code, enabling a bit of QoL stuff.
- path arguments can now be directly added to file paths without Misc.episodePath().
- added more errors to help catch mis-steps in user end code.
- fixed autoloading default music replacements (which broke at some point after 1.2...?)
- jukebox.setTrack() now errors if given 0. but allows for negative numbers.
- jukebox.playTrack(0) is replaced by jukebox.stopTrack(). calling jukebox.playTrack(0) will call jukebox.stopTrack(), keeping the functionality
- added jukebox.autoLoadPathArgs. see the documentation spoiler for details
- made jukebox.setMusicBox() now take musicbox index optionally if the y coordinate isn't supplied (making the x coordinate the index) see the basic use spoiler for details.