Tutorials:XML to Lua

From SMTheming Wiki

Themers who have worked inside StepMania "3.95"/OpenITG have gotten quite familiar with XML. However, StepMania 4.0 dropped XML in favor of Lua. For those themers who know XML, Lua may seem daunting, but in reality, Lua is actually not that different from XML. Generally, tags are replaced with their Lua equivalents, and commands are wrapped in cmd().

Conversion Guides

This section contains examples of commonly used theme elements in both XML and Lua.

General Notes

In XML, everything is wrapped in tags. In Lua, everything is contained within curly braces: { }. This is explained further in ActorFrame.

Commands have slightly changed as well:

• XML: OnCommand="commands here"
• Lua (simple): OnCommand=cmd(commands here);

The command syntax itself hasn't changed, so the same commands from StepMania 3.9 onward work in SM4 (with a few differences for certain commands). Do note the semicolon at the end, though. Those get important when making an element with more than one Command. Close every set of curly braces with a semicolon as well.

ActorFrame

ActorFrames occur naturally in XML, and they also appear in Lua. The key difference here is that the Lua equivalent of <children> is rarely used, usually relegated to ActorScrollers.

XML

<ActorFrame>
    <children>
        <!-- layers here -->
    </children>
</ActorFrame>

Lua

Def.ActorFrame{
    -- LoadActors() here 
};

Layer

Layers are the primary way to create objects with XML. They can be purposed for multiple things with the Type attribute. Since SM4 splits out certain object types, conversion is not 1:1.

If attempting to convert a <Layer Type="Quad"> , see Quad. For converting <Layer Type="BitmapText">, see LoadFont.

XML

 <Layer
  File="@THEME:GetPathG('ScreenTitleMenu',GAMESTATE:GetCurrentGame():GetName())"
  OnCommand="x,SCREEN_CENTER_X;y,SCREEN_CENTER_Y;zoomy,0;sleep,0.5;bounceend,0.5;zoomy,1;" />

Lua

LoadActor(THEME:GetPathG('ScreenTitleMenu',GAMESTATE:GetCurrentGame():GetName()))..{
  OnCommand=cmd(x,SCREEN_CENTER_X;y,SCREEN_CENTER_Y;zoomy,0;sleep,0.5;bounceend,0.5;zoomy,1);
};

Quad

XML

 <Quad InitCommand="diffuse,#000000;diffusetopedge,0.5,0.5,0.5,1;" />

Lua

Def.Quad{
    InitCommand=cmd(diffuse,color("#000000");diffusetopedge,0.5,0.5,0.5,1); 
};

LoadFont

XML

<Layer
	Type="BitmapText"
	Font="Common normal"
	Text="Hello World"
	InitCommand="shadowlength,0"
/>

or

<BitmapText
	Text="Hello World"
	File="Common normal"
	OnCommand="shadowlength,0"
/>

Lua

-- sometimes LoadFont("Common", "normal") syntax is used
LoadFont("Common normal")..{
    Text="Hello World";
    InitCommand=cmd(shadowlength,0); 
};

Complete XML to Lua Example

This example specifically deals with ScreenGameplay ready, as it is simple. The code has been slightly changed in order to remove horizontal scrollbars; everything is normally in the OnCommand.

XML

<ActorFrame>
<children>
     <Layer
         File="ready.png"
         InitCommand="x,SCREEN_CENTER_X;y,SCREEN_CENTER_Y;diffusealpha,0"
         OnCommand="linear,0.5;diffusealpha,1;sleep,0.5;linear,0.5;diffusealpha,0"/>
</children>
</ActorFrame>

Lua

local t = LoadActor( "ready" ) .. {
 InitCommand = cmd(x,SCREEN_CENTER_X;y,SCREEN_CENTER_Y;diffusealpha,0);
 OnCommand = cmd(linear,0.5;diffusealpha,1;sleep,0.5;linear,0.5;diffusealpha,0);
};
return t;

This example (and any other time where you just need to load a single file) can actually be flattened down to just:

return LoadActor( "ready" ) .. {
  InitCommand = cmd(x,SCREEN_CENTER_X;y,SCREEN_CENTER_Y;diffusealpha,0);
  OnCommand = cmd(linear,0.5;diffusealpha,1;sleep,0.5;linear,0.5;diffusealpha,0);
};