This stuff is currently all over a couple other threads, but I figured it might be a good idea to put it all in one place, nicely labelled, in case of future forum searches (Hi there, future mod-makers! :P ). [EDIT] I guess pinning it would also work. Thanks!
- Edwards
Guide to Creating New Songs
To create a new song, you will need three files:
1) An xml file, named "songs.xml", which will contain the notes and other non-scripting information for your song.
2) A lua script, named "songs.lua", which will contain the scripts for all new songs you have.
3) An image file, which will contain the symbol to show up when the song is sung.
Part I: songs.xml
The file should be placed directly in the scripts folder of your mod. If you wish to see an example of a songs.xml file, one is located in the "data" subfolder of the game's data folder. The file has a very simple structure: it consists of a series of Song tags, each of which is formatted as detailed below:
Format of a Song tag:
<Song idx="1" vox="Naija_Song_EnergyForm" slot="2" name="Energy Form" notes="7 6 5" script="0"/>
- idx: An arbitrary number to identify your song. This number is used for learning songs with learnSong(), and is the number passed when castSong() is called (see below). The indices 0-15 are used by the existing songs.
- vox: The name of the audio and subtitle file to be played when the song is clicked on in the pause screen. Both the sound file and the text file must be directly in the sounds folder of your mod (this will correctly override any existing sound or text files with the same name). Note that although a sound file without subtitles will work, in order to display subtitles, you need to have a sound file (note that any sound file will work).
- name: The name that shows up on the right when the song is moused over in the pause screen. This can include line breaks, although I do not recommend it, as the text is not vertically centered (two lines looks a bit odd, and more will overflow into other areas of the pause screen).
- slot: This determines both where on the list on the pause screen the song appears, and what image is displayed when the song is sung. Songs in slots 0-9 will appear on the menu, and can be sung using the number keys on the keyboard (although be warned that if you attempt to add a new image for these slots, or slot 10, you will need to either call reloadTextures() in your mod-init.lua file, or add the a Properties tag with a recache attribute set to "1" to the mod's xml file, or else the new images will not show up). Songs in slots 10 and up will not appear on the menu, and will not have keyboard hotkeys, although they will still work if you sing them normally. There is some order to the positioning of the slots on the menu screen (see following image for the nominal layout), but when you add new songs in the existing slots 0-9, the ordering can become very messed up- I've even seen songs with different slots stacked on top of each other.
(http://i9.photobucket.com/albums/a68/vernagovi/Songslots.png) - notes: This is the song itself. The notes are numbered from 0 to 7, starting at the bottom and running counter-clockwise (see image below). Songs can be as long as you want, as far as I can tell (I've set up Happy Birthday with no ill effects).
(http://i9.photobucket.com/albums/a68/vernagovi/NoteNums.png) - script: If the content of this tag is "1", then the game will call castSong() in songs.lua when the song is sung.
Part II: songs.lua
This file should be placed directly in the scripts folder of your mod. It should contain a function called castSong(), which will be called with the idx of the sung song as an argument. The file can contain as many helper functions as you wish. Note that it is re-compiled every time a song is sung that calls castSong(), so it likely will not work to try to make the script have persistent variables (I have not tested this, though).
Example of songs.lua:
function castSong(songIdx)
if songIdx == 100 then
-- Script for song 100
elseif songIdx == 101 then
-- Script for song 101
end
-- If song 102 is played, nothing happens
end
Part III: songslot-*.png
This image file should be a 128x128 png image with a transparent background, named songslot-X.png, where X is the number of the slot this image is associated with (so images should be named songslot-1.png, songslot-35.png, etc.). The file should be placed in the graphics/song directory of your mod. Once again, be warned that if you attempt to replace the existing songslot images (for slots 0-10), you will need to force the game to reload all of its cached images either by calling reloadTextures() in mod-init.lua, or by adding a Properties tag to your mod's xml file, with the attribute recache="1" (i.e. <Properties recache="1"/>). Be further warned that if someone loads a saved game for your mod from the main title screen, the images will not be recached (as of version 1.1.1), so you may want to warn players to only load saved games from your mod's title screen.
Part IV: Tips
My suggestion for creating a new song is to simply play around with the note wheel until you find a 3-5 note sequence that sounds good (and is fairly easy to play, if it's a song that the player will be using often), write it down, and then keep going. When you have a good set of note sequences, check them against the incorrect note behavior listed below, and select a handful that are clearly distinct from each other and whichever of the pre-existing songs you are keeping.
Behaviour of incorrect notes in the song system:
- There can be any number of incorrect notes before the first correct note.
- There can be up to two wrong notes between a pair of consecutive notes.
- There is no limit on the total number of wrong notes allowed.
- The last note must not be wrong.
Priority seems to be placed on the song sung that is closest to correct. For example, try combining the shield and bind songs in various ways, or the fish and nature forms. However, I have run into some issues when mod-added songs are similar to the built-in songs, with the built-in song overriding the new song even if it had a wrong note, and the new song did not (note: this may be an index issue instead, or something else entirely- I have not doe detailed testing). So, when designing your songs, try to ensure that as few as possible end on the same note (especially the same last note as a built-in song), and if they do end on the same note, make sure that the preceding few notes have as little in common as possible.