Noteskins
Noteskins define the appearance of notes. They are constructed in a similar manner to Themes (with a mixture of graphics, metrics, and Lua scripts), although they are, by nature, not as complicated. On StepMania 5.0 and 5.1, noteskins are specific to a single game mode
Unlike theming (where we explicitly recommended that you not do this), it is okay to copy the Default noteskin to use as a base for your own, as they don't have as many "moving parts" you need to learn by working from a blank slate. A more complex example is midi-note, which closer resembles the look and behavior of Dance Dance Revolution noteskins.
Noteskins consist of a series of actors divided into several categories. They include, using the standard dance mode as an example;
-
Taps: An individual note. Tap notes are usually either a 2D sprite or a 3D model, but for ease of explanation, the examples in this guide will use 2D noteskins. Types of tap notes include, for instance
- Notes: A standard note (Example: Arrows in dance mode).
- Mines: Hitting them deducts score and health (Examples: Mines or X in most noteskins and SHOCK ARROWS in dance noteskins).
- Lifts: A note that must be let go when it reaches the receptors, rather than pressing it.
- Fakes: A note that does not affect scoring at all.
-
Holds and Rolls: A tail that must be held or repeatedly tapped for a length of time (Examples: FREZZE ARROWS in dance noteskins, CHARGE NOTES in beat noteskins, and long note in most noteskins). They are typically divided into three parts; top and bottom caps, and a body that is tiled for the length of the note. They also have active and inactive states.
- Some noteskins may have a Hold Head and/or Roll Head, a specific note sprite used for the head of a hold or roll, as opposed to the standard note sprite. They too have active and inactive states.
- Receptors: The targets.
- Explosions: Effects overlaid on the note when hit/held/etc. Some noteskins may distinguish between dim and bright explosions, triggering the latter after a specific combo milestone.
These sprites can either be shared by all columns, or specific columns may use different assets to set them apart from the rest; for example, most Dance noteskins only include sprites for the down arrow, because they can just be rotated for the other directions, rather than needing to have individual sprites for each direction. By contrast, Pump, popn and beat noteskins often use distinct sprites for each direction due to their traditional column-based color schemes).
As with the screens of themes, these sprites are generated by Lua scripts which define their constituent actors, which are typically Sprites that use the images contained within the noteskin's folder. In the default noteskin, Down Tap Note.lua defines a common tap note with animated dots which pulse in visibility to the beat;
local t = Def.ActorFrame {
Def.Sprite {
Texture="_arrow";
Frame0000=0;
Delay0000=1;
};
Def.Sprite {
Texture="_circle";
Frame0000=0;
Delay0000=1;
InitCommand=cmd(y,15;effectclock,"beat";diffuseramp;effectcolor1,color("1,1,1,0");effectcolor2,color("1,1,1,0.35");effectoffset,0);
};
Def.Sprite {
Texture="_circle";
Frame0000=0;
Delay0000=1;
InitCommand=cmd(y,5;effectclock,"beat";diffuseramp;effectcolor1,color("1,1,1,0");effectcolor2,color("1,1,1,0.35");effectoffset,0.25);
};
Def.Sprite {
Texture="_circle";
Frame0000=0;
Delay0000=1;
InitCommand=cmd(y,-5;effectclock,"beat";diffuseramp;effectcolor1,color("1,1,1,0");effectcolor2,color("1,1,1,0.35");effectoffset,0.5);
};
Def.Sprite {
Texture="_circle";
Frame0000=0;
Delay0000=1;
InitCommand=cmd(y,-15;effectclock,"beat";diffuseramp;effectcolor1,color("1,1,1,0");effectcolor2,color("1,1,1,0.35");effectoffset,0.75);
};
};
return t;If your noteskin contains multiple frames, as most do, StepMania will apply texture coordinate translation to switch between the frames corresponding to each note type. This applies to all Sprites that are contained within the actor.
NoteSkin.lua contains definitions for the actors in use. The RedirTable tells StepMania which Lua files to load for the note sprites in each column. Usually in a Dance noteskin, they are all set to Down, and then the ret.Rotate table is used to specify how many degrees the Down arrow is rotated to transform it into the note for a different column (i.e. rotating down 180 degrees to make Up, 90 degrees for Left, etc).
If you want to use a distinct graphic for a column's notes - for example, Left, you must;
- Create a new Lua file for that actor (i.e.
Left Tap Note.lua) and a relevant graphic - Change the RedirTable to point the Left direction to Left.
- Change the Rotation table so that it does not rotate its sprite at all
Much like themes, there is also a metrics.ini file, which is used to define certain settings and parameters.
Noteskins can either be flat (all notes are the same color), or quantized (all arrows are coloured by their note values, i.e. 4th, 8th, 16th, etc.).
For noteskins with colors based on quantification, all the different colors for notes are contained within the same image file, which are arranged in frames of equal size (in the default noteskin, each frame is 128x128 in size) in a single column. The 1x8 hint contained in the file name of the arrow sheet (_arrow 1x8.png), tells StepMania to treat this image as eight rows of single-frame sprites.
The easiest way to add animation to a tap note is to extend its respective graphic out horizontally with additional frames. StepMania will play the series of sprites on a loop based on the song's current BPM. Usually, such an animation would have 4 or 8 frames; don't forget to change the hint in the file name to match the new frame count, which in this case would be _arrow 4x8.png or _arrow 8x8.png for example.
Similar techniques can be used to add animation to other tap sprites too, such as mines and lifts.
Normally, note animations in StepMania only use the frames within the row corresponding to the respective note quantization. However, StepMania can also animate the noteskin in such a way that the animation continues to cycle through the other colors in the sheet rather than only being one color; this is referred to as a vivid animation, as it resembles the behaviour of the "Vivid" arrows from Dance Dance Revolution (the midi-vivid noteskin bundled with StepMania also uses this behaviour).
This mode is activated by changing the metrics like so;
[NoteDisplay]
TapNoteAnimationIsVivid=1
TapAdditionAnimationIsVivid=1In some cases, commands applied to the to a note's actor can also be used to add motion effects. For instance, this Down Tap Mine.lua file makes the mine spin;
local t = Def.ActorFrame {
Def.Sprite {
Texture=NOTESKIN:GetPath( '_down', 'tap mine' );
Frame0000=0;
Delay0000=1;
InitCommand=cmd(spin;effectclock,'beat';effectmagnitude,0,0,-33);
};
};
return t;Holds are divided into inactive and active states. A hold is active when it is actually being held. A roll typically flashes between the inactive and active states as it is being repeatedly tapped.
The hold tail is divided into three separate graphics in each state; the top cap, the bottom cap, and the the body - which is a tiled texture.
The receptors are the targets that signify when to actually hit a note. They typically blink to the current BPM of the song, and can provide visual feedback when the corresponding button/pad/etc. is pressed and/or held down. Their behaviour is defined in metrics.
Note explosions are defined under the [GhostArrowDim] and [GhostArrowBright] sections of metrics.ini, and are merely commands acting upon a sprite of a "glowing" note graphic. The animation and its color can be changed between the different note judgments (they go downward from W1 to W5, with W1 as the top judgement usually referred to as "Flawless", "Fantastic", or "Marvelous", and W5 being the worst before a miss) with standard tweens and diffuses.