A plugin for adding custom songs into Beat Saber.
This mod works on both the Steam and Oculus Store versions.
-
Download the latest release
-
Extract the .zip file into the
Oculus Apps\Software\hyperbolic-magnetism-beat-saber
for Oculus Home ORsteamapps\common\Beat Saber
for Steam. (The one with Beat Saber.exe)The Beat Saber folder should look something like this:
Beat Saber_Data
CustomSongs
IPA
Plugins
WIP Songs
Beat Saber (Patch & Launch)
Beat Saber.exe
IPA.exe
Mono.Cecil.dll
UnityPlayer.dll
-
Done!
- Launch Beat Saber through the platform you purchased it on.
- Go to 'Solo' and scroll to the right on the song pack selection view to the
Custom Maps
Pack and select it to view your songs
- The following files must be placed within their own folder inside the "CustomSongs" folder.
- You Can place songs in the
WIP Songs
Folder instead to place them in the WIP Maps songpack and have them only be playable in practice mode, this is recommended if you are either making the map yourself or testing someone else's map - If a duplicate song is in both the
CustomSongs
andWIP Songs
folder it will only show in the Custom Maps pack
Required files:
1. cover.jpg (Size 256x256)
-This is the picture shown next to song in the selection screen.
-The name can be whatever you want, make sure its the same as the one found in info.json
-Only supported image s are jpg and png
2. song.wav / song.ogg
-This is your song you would like to load
-Name must be the same as in info.json
-Only supported audio types are wav and ogg
3. easy.json / normal.json / hard.json / expert.json
-This is the note chart for each difficulty
-Names must match the "jsonPath" in info.json
-Use a Beat Saber editor to make your own note chart for the song
4. info.json
-Contains the info for the song
The following is a template for you to use:
{
"songName":"YourSongName",
"songSubName":"ft. Name",
"authorName":"AuthorName",
"beatsPerMinute":179.0,
"previewStartTime":12.0,
"previewDuration":10.0,
"audioPath":"YourSong.ogg",
"coverImagePath":"cover.jpg",
"environmentName":"DefaultEnvironment",
"customEnvironment": "Platform Name",
"customEnvironmentHash": "<platform's ModelSaber md5sum hash>",
"shuffle":1,
"shufflePeriod":0.2,
"oneSaber":true,
"difficultyLevels": [
{ "difficulty":"Expert", "difficultyRank":4, "jsonPath":"expert.json" },
{ "difficulty":"Easy", "difficultyRank":0, "jsonPath":"easy.json", "characteristic":"Standard", "difficultyLabel":"EX" }
],
"contributors": [
{ "role": "Kirb", "name": "Kyle 1413", "iconPath": "test.png" },
{ "role": "Lighter","name": "Kyle 1413 The Second", "iconPath": "test.png"}
]
}
"songName" - Name of your song
"songSubName" - Text rendered in smaller letters next to song name. (ft. Artist)
# Mappers/lighters fields being renovated, do not use
"beatsPerMinute" - BPM of the song you are using
"previewStartTime" - How many seconds into the song the preview should start
"previewDuration" - Time in seconds the song will be previewed in selection screen
"coverImagePath" - Cover image name
"environmentName" - Game environment to be used
"customEnvironment" - Custom Platform override, will use "environmentName" if CustomPlatforms isn't installed or disabled
"customEnvironmentHash" - The hash found on ModelSaber, used to download missing platforms
"shuffle" - Time in number of beats how much a note should shift
"shufflePeriod" - Time in number of beats how often a note should shift. Don't ask me why this is a feature, I don't know
"oneSaber" - true or false if it should appear in the one saber list
(If the WHOLE map is only one saber! For one saber difficulties use the characteristic in the difficultylevels)
All possible environmentNames:
-DefaultEnvironment
-BigMirrorEnvironment
-TriangleEnvironment
-NiceEnvironment
-KDAEnvironment
-MonstercatEnvironment
"difficultyLevels"
"difficulty" - This can only be set to Easy, Normal, Hard, Expert or ExpertPlus,
"difficultyRank" - Currently unused whole number for ranking difficulty,
"jsonPath" - The name of the json file for this specific difficulty,
"characteristic" - What section you want the difficulty to be listed under, refer to bottom of readme for usage
"difficultyLabel" - The name to display for the difficulty in game
Note: Difficulty labels affect Every difficulty of the same type(Easy, Normal, etc)
for that song, if you have two difficulty labels
for a single type, only one will take effect
This will also not affect how the difficulty displays on scoresaber or elsewhere
"contributors"
"role" - The role the person had, i.e. Mapper, Lighter, Inspiration
"name" - The name of the person
"iconPath" - path to the icon to use for the person within the song folder i.e. icon.png
- Refer to Modders section for a list of common capabilites that mods register
"_warnings":["Warning1","Warning2","WarningX"], - Any warnings you would like the player to be aware of before playing the song
"_information":["Thing1","Thing2","ThingX"], - Any general information you would like the player to be aware of before playing the song
"_suggestions":["Mod1","Mod2","ModX"], - Any Mods to suggest the player uses for playing the song, must be supported by the mod in question otherwise the player will constantly be informed they are missing suggested mod(s)
"_requirements":["Mod1","Mod2","ModX"], - Any Mods to require the player has before being able to play the song, must be supported by mod in question otherwise song will simply not be playable
"_colorLeft":{"r":1, "g":1, "b":1}, - A color to override the left color to if the player has custom song colors enabled, color range for r,g, and b is a 0-1 scale, not 0-255 scale
"_colorRight":{"r":1, "g":1, "b":1}, - A color to override the left color to if the player has custom song colors enabled, color range for r,g, and b is a 0-1 scale, not 0-255 scale
If using either color override you must add a color for both sides
Default colors are approximately
Left: 1,0,0
Right, 0, 0.706, 1
"_noteJumpStartBeatOffset":1, - Set the noteJumpStartBeatOffset for the song, default value is 0 if not implemented
- You can add/remove capabilities to your mods for maps to be able to use by doing the following
- You can register a beatmap characteristic OnApplicationStart by doing the following Make sure to do this before songloader loads songs
// To register
SongLoaderPlugin.SongLoader.RegisterCapability("Capability name");
// To remove
SongLoaderPlugin.SongLoader.DeregisterizeCapability("Capability name");
//If you make a mod that registers a capability feel free to message me on Discord ( Kyle1413#1413 ) and I will add it to the list below
SongLoader.RegisterCustomCharacteristic(Sprite Icon, "Characteristic Name", "Hint Text", "SerializedName", "CompoundIdPartName");
//For the SerializedName and CompoundIdPartName, as a basic rule can just put the characteristic name without spaces or special characters
//The Characteristic Name will be what mappers put as the characteristic when labelling their difficulties
//If you make a mod that registers a characteristic feel free to message me on Discord ( Kyle1413#1413 ) and I will add it to the list below
- Note: Songloader currently auto detects Precision Placement, Extra Note Angles, and More Lanes. Other features of mapping extensions require you to add the "Mapping Extensions" Capability as a requirement for your song, and it is advised if you use any of the capabilities of a mpod, you assume it will not be auto added and add the capability to the JSON.
Capability | Mod |
---|---|
"Mapping Extensions" | Mapping Extensions |
"Mapping Extensions-Precision Placement" | Mapping Extensions |
"Mapping Extensions-Extra Note Angles" | Mapping Extensions |
"Mapping Extensions-More Lanes" | Mapping Extensions |
"Chroma" | Chroma |
"Chroma Lighting Events" | Chroma |
"Chroma Special Events" | Chroma |
- These control what difficulty set the difficulty is placed under, so if you wanted to include a set of 5 difficulties that were all one saber in addition to a normal set of 5 difficulties, similar to what the OST does, you would give all of the one saber difficultyLevels a characteristic of one saber
Characteristic | Source |
---|---|
"Standard" | Base Game |
"No Arrows" | Base Game |
"One Saber" | Base Game |
"Lawless" | SongLoader |
"Lightshow" | SongLoader |
- Press Ctrl+R when in the main menu to do a full refresh. (This means removing deleted songs and updating existing songs)
- Press R when in main menu to do a quick refresh (This will only add new songs in the CustomSongs folder)