Adding Songs and Beatmaps to Chop It
Creating and Importing Songs and Beatmaps
We’ve worked hard to make importing of your own songs and beatmaps into the My Tracks feature of Chop It simple and accessible. Today we’ll cover the basic features in the VR beatmap editor, which we call the Mapping Station, as well as explain the basic directory and file structure for importing your content.
Along with this article, we’ve made a quick start video that shows how to set up the directory for a new song to be imported.
[2018–09–14] Update: We now have an external 2D mapping tool that runs in your browser. It’s in beta, but you can check out the latest stable build here. It offers tap along mapping as well as converters for MIDI and Beat Saber tracks.
File and Directory Format for Imported Content
When you install Chop It, we include Terror Pigeon’s song ‘Chamber of Secrets for 1’ as an example for you to copy or reference.
You can find this example in the StreamingAssets directory within Chop It’s local data. On Steam, this should be at ‘steamapps/common/Chop It/chopit_Data/StreamingAssets’. You can quickly navigate to this directory by selecting Chop It from your Steam Library, going to Properties, and on the Local Files tab clicking the ‘Browse Local Files…’ button.
Within the StreamingAssets directory you’ll find the ‘TerrorPigeonChamberOfSecretsFor1’ folder which contains all of the files necessary to have a playable song in Chop It.
ChamberOfSecretsFor1.wav — the audio file to be played.
SongInfo.json — a json file containing the artist name and song title that you’d like to be displayed in-game.
ChamberOfSecretsFor1_beatmap_standard.txt — the beatmap file, which contains a json object describing the gameplay associated with this audio file. We’ll explain the file format in more detail below.
Some useful notes about the imported files:
- The audio file must be of format .wav. This is due to a restriction with Unity around importing external audio files. A quick and easy solution for other file formats is to download the free audio tool Audacity and convert the file to a .wav. You can find a tutorial on how to do this conversion here.
- The name of the folder containing your files does not matter, as long as it is in the StreamingAssets directory.
- SongInfo.json contains information that is solely for display purposes. Edit this file in Notepad (or similar) to set the display artist name and song title to whatever you’d like.
- Beatmap files must be of type .txt or .json and the file name must contain the word ‘beatmap’ in order to be imported. This file can be generated in-game when using the VR Mapping Station to create a beatmap.
Importing Songs
Following the Terror Pigeon example, we can quickly get to mapping our own audio files.
The first step is to make a new directory in the StreamingAssets folder. For this example, my folder will be named ‘ConBroChillPowerHappy’.
Copy your .wav file into your newly created ConBroChillPowerHappy folder.
In order for our song to appear in-game, we need to set some display information.
Create a new text file named ‘SongInfo.json’, or simply copy the existing file from the Terror Pigeon example directory. Within SongInfo.json we simply need this string:
{“artistName”: “Con Bro Chill”, “songName”: “Power Happy”}
Set the values of artistName and songName to be whatever you’d like to appear in-game.
If you’ve created and populated this file successfully, you will now see your song the next time you load the My Tracks menu in Chop It.
If you navigate to your new song in Chop It and select it to be played, you’ll notice that it displays the song information but is not playable because there are no selectable beatmaps.
That means it’s time to create a new beatmap!
Creating Beatmaps with the VR Mapping Station
In that same song information screen, you can hit the Create/Edit Beatmap button. Since no beatmap is selected, it will take you to the Mapping Station with a new empty beatmap. Once you have a beatmap created, you can always come back and edit the beatmap by navigating to the song information screen, selecting the beatmap you wish to edit, and hitting the Create/Edit Beatmap button.
The Mapping Station is built to give you total control over the player’s experience during the song.
On each hand, you will see an object in front of your fingers that looks like a small version of a board with a white sphere in the middle. We call the fullobject the Mapping Tracker and the white sphere is the Control.
This Mapping Tracker is built to give you a preview of exactly what type of item will be spawned, as well as the final rotation of the item, when you map a beat. As you rotate your hand, you’ll see the item locking to the supported rotation closest to the rotation of your hand. Similarly, if you hold the trigger to make a fist you’ll notice the board switches to a cinderblock.
In front of you is the array of Target Boxes represented by green cubes. Four on the top row, three in the middle, and four on the bottom. These represent the final landing locations of the items as the Sensei throws them.
Any time the Control of your Mapping Tracker touches a Target Box, a new beat will be added to your beatmap containing the time in the audio file that was playing when the contact occurred, the Target Box ID with which the contact occurred, the item type (board or cinderblock) active at the time of contact, and the rotation of the item at the time of contact. These attributes describe exactly how the beat will be presented to the player when that time occurs in the song. You can see these beats as they are mapped to the right of the Target Boxes on the Chalkboard.
You can map beats while the song is playing or paused. There is a Play/Pause button under the Target Boxes along with an audio slider for you to jump around the song time.
If the song is playing in the Mapping Station, any previously mapped beats will appear as the song plays. This allows you to preview the flow of the beatmap without having to leave the tool.
To further customize the gameplay at a previously-mapped time, you can select a beat from the Chalkboard to the right of the Target Boxes. This will jump to the audio time of that mapped beat as well as preview any beats mapped to that time. You can then map new beats at that same time or delete beats by hitting the red box next to any beat on the Chalkboard. Use this tool to create swipes and combos or really complicated unplayable beatmap art.
To save your beatmap at any time hit the Save to File button to the right of the Chalkboard. If this is a new beatmap, this will generate a new beatmap file within the same folder as the audio file you are mapping. The name will typically be something like ‘SongName_beatmap_custom_<timestamp>.txt’.
Saving to file is not done automatically, so if you do something like accidentally hit the Clear Beats button, you can exit the tool and re-enter and it will reload the beatmap from disk.
The Detect Beats button will algorithmically detect beats in the audio file that you are mapping. This feature can only be activated for new, empty beatmaps. It typically takes 5–15 seconds depending on the file size and is a bit experimental.
The intention here is to give you a skeleton of a beatmap to further customize. You can, of course, generate a full beatmap with the Detect Beats feature, Save to File, and play it immediately, but in our experience curating a beatmap to play exactly how you want will give players a more enjoyable experience. If you’re interested in the beat detection algorithm, we’ve written a detailed blog and released the working source code here.
For those that are interested in the internals of beatmaps, and potentially creating your own tools to create beatmaps, we will go into detail about the contents of a beatmap.
Understanding Beatmap Files
Beatmap files are essentially json serializations of the beatmaps generated in-game. Since we know some users may prefer to edit beatmaps manually or with an external tool, we’ll describe the properties of the beatmap here:
mapName — a display field for the name of the beatmap.
appVersion — populated with the current release version of Chop It. Example: “1.5.3”
randomSenseiMovement —one of true, false (no quotes)— a setting which enables or disables the Sensei’s ability to jump around the Pagoda during gameplay.
difficulty —one of “easy”, “standard”, “hard” — a display field describing the difficulty of the beatmap.
beats — a list of Beat objects listed in order by time — This list is iterated during gameplay and beat times are compared to the audio time as the song plays.
A beatmap with metadata, but no beats, would look like this:
{
“mapName”:”Techboy’s Beatmap”,
“appVersion”:”0.2.0",
“difficulty”:”standard”,
“randomSenseiMovement”:true,
“beats”:[]
}
Beat objects are representations of gameplay at a given audio time. The properties of a Beat:
beatID — the position of the beat in the sequence starting with the number 0. The first beat you map would have beatID of 0, the second beat you map would have beatID of 1, etc… When a beatmap is saved to file in the Mapping Station, these IDs are automatically generated after the beats are sorted by time.
time — the exact time in the audio file that the player is expected to hit an item. This time is in seconds with millisecond precision. Example: 125.004 would represent the audio playing 2 minutes, 5 seconds, and 4 milliseconds into the song.
rotationID — one of “H”, “V”, “R”, “L” — The rotation of the item when it is expected to be hit. H (horizontal), V (vertical), R (diagonal with top leaning right), L (diagonal with top leaning left). Default is horizontal.
itemType — one of “B”, “C” — The type of item spawned. B (board), C (cinderblock). Default is board.
targetID — “A”, “B”, “C”, “D”, “E”, “F”, “G”, “H”, “I”, “J”, “K” — The target location that the item is thrown to. Default is F., which is the center-most target.
Target locations as they appear to the player:
A — B — C — D
- E — F — G -
H — I — J — K
Regardless of the position of the Sensei, the targets rotate accordingly so this orientation to the player is guaranteed.
A beat object that is fully populated looks like this:
{
“beatID”:0,
“time”:3.58
“targetID”:”F”,
“rotationID”:”H”,
“itemType”:”B”
}
and a fully functional beatmap with 2 beats looks like this:
{
“mapName”:”Techboy’s Beatmap”,
“appVersion”:”0.2.0",
“difficulty”:”standard”,
“randomSenseiMovement”:true,
“beats”:[
{“beatID”:0,“time”:3.58,“targetID”:”F”,“rotationID”:”H”,“itemType”:”B”},
{“beatID”:1,“time”:6.91,“targetID”:”D”,“rotationID”:”V”,“itemType”:”C”}]
}
Summary
We’d love your feedback about how we can make the mapping experience better for you. Feel free to send us your beatmaps for us to play and test, and please report any bugs you come across! As always, you can find us on Twitter, Steam, or email us directly at scambot@giantscam.com.
Thanks!
