Adding Customization Options to STARLiGHT twopointzero

Overview

XX STARLiGHT -twopointzero- supports a multitude of custom options that affect how the theme looks. Due to the nature of how the theme is structured currently (Version 2.1.0), adding options can be difficult for the end user. This wiki will show you how to add options to each type of customization option.

Due to how the complexity of adding Music Select options, they will not be covered in this tutorial.

Getting Started

A majority of the work will be done inside the following folders and files:

File Name/Folder	Reason
BGAnimations/ScreenPHOTwON overlay	This is where all the scripts and files are located for the customization menus.
Scripts/99 MenuMusic.lua	This is where you set the paths for BGMs. You have to set a path for each type of BGM or the game will error out.

Each option type requires:

• An Internal Name (i.e. inori). This is what the theme will be looking for while loading in your files
• An External Name (i.e. Inorizushi). This is what the theme will display as the option name.
• An Image Preview (i.e. A screenshot of the background, music wheel, or the graphic displayed for BGMs)

Adding Menu Backgrounds

The files/folders you will need to work on are:

File Name/Folder	Reason
BGAnimations/ScreenWithMenuElements background	This is where any files for the Menu Backgrounds are loaded. This is required or your background will not display.
BGAnimations/ScreenPHOTwON overlay/MenuBG	This is where your Internal/External Names will be set and where you add the option to select it in the theme.

Adding your background

Open BGAnimations/ScreenWithMenuElements background. Create a folder named what you would like the background to be named internally (i.e. "mycustombg") Open that folder and create a file named default.lua. This is the file that tells the engine what to do.

If you are adding a menu background from another theme, just copy the default.lua and any other files in the source theme's ScreenWithMenuElements background folder.

Due to the scope of programming a StepMania theme, I will only be covering loading a still image or a video.

Open default.lua and copy and paste this code into it.

return Def.ActorFrame{
    Def.Sprite{
	    Texture="<image/movie file name>",
	    InitCommand=function(self)
		    self:FullScreen()
			--[[This will automatically center and stretch the image
			to the confines of the StepMania window.
			If you want to specify the size of the image, use the following instead.
			Remove the previous line and the dashes at the beginning of the next line.]]

			--self:xy(_screen.cx,_screen.cx):setsize(width,height)
			--[[This will center the image and set the size to what you set
			as width and height. STARLiGHT renders natively at 1920x1080
			so please adjust accordingly.]]
		end
	},
}

You are now done with the BGAnimations/ScreenWithMenuElements background folder.

Making the option appear in the theme

Open BGAnimations/ScreenPHOTwON overlay/MenuBG.

In this folder you will see the default.lua file and the images that are used as the previews in the theme.

Open default.lua. At the beginning of the file you will see a table named frames. This is where we will be specifying our internal name and external name of the option.

local frames = {
	{"Default","DEFAULT"},
	{"OG","STARLiGHT 1.0"},
	{"OLD","STARLiGHT 2011"},
	{"SN1","SuperNOVA"},
	{"SN2", "SuperNOVA2"},
	{"X1", "X"},
	{"X2", "X2"},
	{"SN3","SuperNOVA 3"},
	{"NG2","Next Generation 2"},
	{"Retrowave","Retrowave"},
};

There are two keys that need to be added. The first being your Internal Name, the second being your External Name.

To add your option, just create another entry to the table with 2 keys like the others.

{"mycustombg","My Custom BG"},

In the end, the frames table should look like this.

local frames = {
	{"Default","DEFAULT"},
	{"OG","STARLiGHT 1.0"},
	{"OLD","STARLiGHT 2011"},
	{"SN1","SuperNOVA"},
	{"SN2", "SuperNOVA2"},
	{"X1", "X"},
	{"X2", "X2"},
	{"SN3","SuperNOVA 3"},
	{"NG2","Next Generation 2"},
	{"Retrowave","Retrowave"},
	{"mycustombg","My Custom BG"},
};

You're now done with editing default.lua so feel free to close it.

Create an image preview that showcases the menu background that you will be adding at 300x168 resolution. and name it mycustombgPrev.

You are now done with the BGAnimations/ScreenPHOTwON overlay/MenuBG folder.

Open StepMania/Outfox, enter the Customization screen, open the Menu Backgrounds option, and scroll down and see if your Background now appears. Select it and exit the customization screen. If all things went correctly, your background should now be displaying.

Adding Background Music

The files/folders you will need to work on are:

File Name/Folder	Reason
Scripts/99 MenuMusic.lua	This is where we set the paths for your sound files. It is required to add to each table or StepMania/Outfox will error out and crash.
Sounds/MenuMusic	This is where your sound files will be located. You can have separate music for the Profile Select, Results, Options, Stage Information, and Title screens from the common music that will be played on Style Select and Music Select.
BGAnimations/ScreenPHOTwON overlay/BGM	This is where your Internal/External Names will be set and where you add the option to select it in the theme.

Adding your Music Files

Open Sounds/MenuMusic. In here you will see folders for each screen that you can change the music on.

Folder Name	Usage
common	This is what will always be played on the Select Style and Select Music screens.
options	This is what will be played on the StepMania/Outfox options screen.
profile	This is what will be played on the profile select and data save screens.
results	This is what will be played on the Results screens.
StageInfo	This is what will be played on the screen that appears after Music Select and before gameplay. You can either set a single sound to play or music. Please note that the music can only last for 8 seconds or it will be cut off.
Title	This is what will be played on mode select screen (Where you choose to start the game, open options, etc.

You only need to add files if you're going to be using different music or sounds than what already exists in the theme.

Setting paths

Open Scripts/99 MenuMusic.lua. In here you will find a multi-layered array for each bgm type as mentioned above. You have to add your option to each of these arrays or StepMania/Outfox will crash. The theme currently does not have a fallback for these files implemented.

Adding your option is relatively straightforward. For each BGM type, add yours to the end of each table matching the others. [mycustombgm] = "MenuMusic/<type>/mycustombgm (loop).ogg

The first entry being your internal name for your bgm, followed by the path for the sound file you want for that bgm type.

Do this for the rest of the bgm types in the table. As you can see with some of the existing options, they do not have custom files so the path is just set to something that already exists. This also applies if you aren't using custom music for each screen, so just set the path to the same that you set for common or the music you want shared between screens.

You are now done with Scripts/99 MenuMusic.lua

Making the option appear in the theme

Open BGAnimations/ScreenPHOTwON overlay/BGM. Like with menu backgrounds, you will see default.lua and the image previews inside the CDs folder. Currently the CDs used are hard baked images. This will change in the future so you can just add the image you want displayed on the CD.

For now, open your favorite image editor, add the image you want displayed and the _overlay.png file. Make the image fit inside the overlay image. The _mask.png is provided to help get the boundaries correct. Save the file as <internalname>.png.

Open default.lua. Like with adding Menu Backgrounds, you will see the same frames table but for the BGM options. Do the same as you would with Menu Backgrounds.

In order to set the preview loop, scroll down to line 129. curIndex refers to the current item that's being highlighted according to the order of the frames table.

To add your BGM, go to the end of the MoveScrollerBGMMessageCommand function and add the following before the end line.

elseif curIndex ==  <number in frames>  then
	SOUND:PlayMusicPart(THEME:GetPathS("","MenuMusic/common/<internalname> (loop).ogg"), 0, 13, 0, 0, true)

As an example, since the last BGM added (as of writing this documentation) is the 8th entry into frames, set <number in frames> to 9.

But what's with all that stuff inside PlayMusicPart?

PlayMusicPart takes multiple values.

Taken from StepMania5 Lua Doc

PlayMusicPart(  string  musicPath,  float  musicStart,  float  musicLength,  float  fadeIn,  float  fadeOut,  bool  loop,  bool  applyRate,  bool  alignBeat )

Play the sound at  `musicPath`  starting from  `musicStart`  for  `musicLength`  seconds one 	time. Both  `fadeIn`  and  `fadeOut`  can be customized as required.  `loop`  tells the sound manager to loop the music part.  `applyRate`  tells the sound manager to apply the current music rate. If  `alignBeat`  is true or nil, the length is automatically adjusted to cover an integer number of beats.

So in the example code, we:

1. Set the path to the bgm that we want played for the preview.
2. Set where in the music that we want the preview to start, in this case 0 so it plays from the beginning.
3. Set how long the preview will last.
4. Set the length of the fade in, 0 as we don't want the preview to fade in.
5. Set the length of the fade out, 0 as we don't want the preview to fade out. You can use this if you aren't just playing the entirety of the bgm as the preview.
6. Set it to loop the preview.

We don't need to set the last two values that can be used (applyRate and alignBeat) as they aren't needed.

You are now done with the BGAnimations/ScreenPHOTwON overlay/BGM folder.

Open StepMania/Outfox, enter the Customization screen, open the Menu BGM option, and scroll down and see if your music now appears and the preview is playing. Select it and exit the customization screen. If all things went correctly, your music should now be playing.