Adding Custom Piano Songs

Version 0.8.4 added support for custom piano songs in the piano mini-game.

TOC

1. JSON Format
   1. JSON Format description
   2. Piano Note-Key Map
2. JSON Location
3. Troubleshooting JSONs
4. Known Issues
5. Submitting Piano Songs

The Format

All Piano songs are stored in text files in JSON format. Here's an example of how a (very short) piano song is notated in JSON:

{
    "name": "Song name",
    "verse_list": [0, 5, 10, 23],
    "pnm_list": [
        {
            "text": "This is a song lyric",
            "style": "monika_credits_text",
            "notes": [
                "D5",
                "C5SH",
                "B4",
                "F4SH",
                "B4",
                "C5SH",
                "D5",
                "E5",
                "D5",
                "C5SH",
                "B4",
                "A4",
                "G4",
                "D5",
                "E5"
            ],
            "express": "1eub",
            "postexpress": "1eua",
            "vis_timeout": 2.0,
            "verse": 0,
            "posttext": true
        },
        {
            "text": "This is the another song lyric",
            "style": "monika_credits_text",
            "notes": [
                "D5",
                "A4",
                "D5",
                "A4",
                "D5",
                "A4",
                "D5",
                "E5",
                "C5SH"
            ],
            "postnotes": [
                "D5",
                "C5SH"
            ],
            "express": "1eub",
            "postexpress": "1eua",
            "ev_timeout": 1.0
        }
    ]
}

Object Explanation:

Main name/value pairs:

• name: (string) name of the song
  • must be unique
  • This is also shown to the player in the Piano song menu
• verse_list: (list) list of indexes (int) where each verse starts
  • verses are like checkpoints. They are the reason why you don't have to start Your Reality from the beginning when you make a mistake.
  • the index should be the location of note-phrase in pnm_list that represents a start of a verse
  • this uses 0-indexing
• pnm_list: (list) list of note phrases (object)
  • each note phrase is an object, name/value pairs are described below
• _comment: ignored field useful for adding comments

name, verse_list, and pnm_list are all required. There are additional params that are meant for internal use only or are not ready for release. For more info on those, see the top of zz_pianokeys

Note Phrase name/value pairs:

• text: (string) text Monika will say during these set of notes
• style: (string) style to apply to the text
  • monika_credits_text is the one the stock songs use. You can use other styles, but this is probably the best one.
• notes: (list) list of notes for this phrase
  • see below for info on notes
• postnotes: (list) list of optional notes that can be played after the notes
  • these are used to ensure smooth transitions from one note phrase to another
  • see below for info on notes
• express: (string) sprite code to display during this note phrase
  • this is only shown as the notes are being played
• postexpress: (string) sprite code to display when the note phrase is successfully played
  • this is shown after the notes are played
  • this is also shown while postnotes are played
• ev_timeout: (float) number of seconds to wait before timing out input / assuming a missed note / resetting verse
  • mainly used to setup a larger timing window for user input leading into this note phrase
  • if not provided, the default timeout of either 1.0 (no song) or 3.0 (during song) is used
• vis_timeout: (float) number of seconds to wait before resetting Monika's expression / remove visual lyric
  • mainly used to extend either Monika's expression or the visual lyric for an amount of time before visual reset
  • this does not extend into the next note phrase if the player begins input for the next phrase
  • if not provided, the default timeout of either 2.5 (no song) or 4.0 (during song) is used
• verse: (int) verse index this note phrase belongs to
  • this must match a number in verse_list
• posttext: (bool) true means the visual lyric will remain visible after the note phrase is completed
  • default behavior (false) is to hide the lyric right after the note phrase is completed.
  • this respects the vis_timeout setting
• _comment: ignored field useful for adding comments

text, style, and notes are all required. There are additional params that are meant for internal use only or are not ready for release. For more info on those, see the top of zz_pianokeys

Notes

Notes are just strings. Here are the available notes: (They correspond to actual piano notes)

Notes	Default key
F4	q
F4SH	2
G4	w
G4SH	3
A4	e
A4SH	4
B4	r
C5	t
C5SH	6
D5	y
D5SH	7
E5	u
F5	i
F5SH	9
G5	o
G5SH	0
A5	p
A5SH	-
B5	[
C6	]

Location

Custom piano songs should be stored in piano_songs/ with a filename of songname.json

Checking for Correctness

Warnings and errors in piano JSONs are logged to the file pnm.log. The logging is fairly descriptive and should be enough to troubleshoot issues. The log is not guaranteed to be written during gameplay. The best way to check your files is to launch then quit.

MAS (and the piano minigame) will still run even if your piano JSON is invalid. Songs that failed to load properly are ignored.

Known Issues

Song data regarding wins / passes / fails are stored internally and organized by song name. Once you've passed a song with a certain name, that song will always appear in play a song even if the underlying JSON is not the same. We are not planning to fix this since it would probably require a rewrite of how we store the data.

Submitting Piano Songs

Made a song for Monika to sing when using the piano?

Follow these instructions to submit them. Note that we most likely will not be adding anymore songs officially, but we will be compiling JSONs and releasing them in a pianonote pack. (Similar to spritepacks).

To submit a piano song:

1. Make an issue
2. Attach the JSON to the issue. If the file is too large, then link it to the issue.
3. Include the text #3765 in the issue.

You can also submit just the notes, however that will delay its inclusion into the piano notes packs.