jukebox.lua v1.2 - 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 default overworld music replacement you wish to make with the same name as the default file name it has in data\music.ini. as of 1.2, spcs that use this method are auto given gain path arguments

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

not really much i can showcase sensibly given it's nature, but i can give a run down of it's basic premise and documentation.

basic use: show

- place the library in the base of your episode. you can place it elsewhere if you know what your doing, but this guide assumes your unfamiliar with this process
- you 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 PGE)
-from there, use this code load, register, and use the system in a map.lua file:

Code: Select all

local jukebox = require("jukebox")

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

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 or lower 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. i'd recommend using the custom range (751-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.

"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. i recommend jukebox.resolveMusicFile(string) if you don't know the file extension. certain extensions can use path arguments. this may be necessary for things like .spc, which play very quietly by default. for those you'd do something like "my song.spc|0;g=2.7;". you can find a full list of music path args here. if using in conjunction with jukebox.resolveMusicFile(string), then it'd be like so: jukebox.resolveMusicFile("my song") .. "|0;g=2.7;"

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.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.

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
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 or -1 if nothing is playing
jukebox.playTrack(trackID) - plays the track of the ID supplied. can use 0 to make it not play anything.
jukebox.resolveMusicFile(path) - like Misc.resolveSoundFile(string), but can get any usable music format from this page

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.

[LennonsFactory]

this is going to be VERY useful

[SpencerEverly]

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