SM4 theming documentation: what does everyone want?

[AJ 187]

With any luck, after the release of moonlight, I'm going to take things a bit slower and flesh out theming documentation in order to help more people understand the theming system of the SM4 alphas.

I've already written up two tutorials on porting 3.9 (ini) and 3.95 (XML) BGAnimations to Lua:

• Ini -> Lua (3.9)
• XML -> Lua (3.95, early 4.0)

Hopefully these help people converting from one version to another, but this may not be enough, so I'm asking everyone what they want more information on. Post anything you'd like to see documented more in the theming system, even if it's a general "how do I work with x?".

[Midiman]

I propose we have a portal on the wiki that categorizes our information into more simple sections, such as "Just Starting", "Beginner Tutorials", "Intermediate Tutorials", and "Advanced Methods & Information".

so this way, people can learn things they want to at a simple pace, and when they get a feel for it, they can go into intermediate and advanced things to look at and learn from.

[xjen0vax]

I agree with Midiman. Great idea to go along with it, a sample theme used throughout such a set of tutorials with all materials and code provided as necessary to really convey how to create a theme from the ground up would make things a lot easier for beginners than just a bunch of information to expect them to read. Get people actually building a theme with example code so they can get a feel for actually theming. Similar to how programming courses and tutorials tend to include sample projects to teach concepts.

[Daisuke Master]

Something like function commands tutorial would be useful for a lot of users...

OnCommand=function(self) end;

Here is a little comtribution of mine, Advanced and more detailed comparation between ini and lua

-- Comparación entre default.lua y BGAnimation.ini
-- (viendo los equivalentes de ciertas partes de ambos)
-- * Comandos como linear, diffuse, etc se escriben tal cual
-- * Fíjate bien donde van los punto y coma ";" para evitar errores
--[[-------------------------------------------------------------------------
default.lua				BGAnimation.ini
--]]-------------------------------------------------------------------------

-- usando variables (van fuera del actorframe)
local playcond = GAMESTATE:GetPlayMode() == 'PlayMode_Regular'

return Def.ActorFrame {			--  [BGAnimation]
	LoadActor("img.png")..{		--  [Layer1]
			-->		--  File=img.png
		OnCommand=cmd(...);	--  OnCommand=...
		OffCommand=cmd();	--  OffCommand=	
	};
	LoadActor("img.png")..{		--  [Layer2]
			-->		--  File=img.png
		OnCommand=cmd(...);	--  OnCommand=...
		Condition=playcond;	--  Condition=PlayModeName() == "Nonstop"
	};
-- Fonts / Texts
	LoadFont("bitmapfont")..{	--  [Layer3]
			-->		--  File=bitmapfont
		Text="hello there";	--  Text=hello there
		OnCommand=cmd(...);	--  OnCommand=...
	};

-- Sprites!
					--  [Layer4]
					--  File=filename.sprite
					--  OnCommand=...
-- Equivalencias con sprites
-- (no necesitas un archivo externo para asignar frames)
--[[-------------------------------------------------------------------------
default.lua				Filename.sprite
--]]-------------------------------------------------------------------------
	Def.Sprite {			--  [Sprite]
		Texture="spr 4x4.png";	--  Texture=spr 4x4.png
		BaseRotationZ=90;	--  BaseRotationZ=90
		
		Frame0000=0;		--  Frame0000=0
		Delay0000=0.1;		--  Delay0000=0.1
		Frame0001=1;		--  Frame0001=1
		Delay0001=0.1;		--  Delay0001=0.1
		
--		(...);			--  (...)
		
		Frame0014=14;		--  Frame0014=14
		Delay0014=0.1;		--  Delay0014=0.1
		Frame0015=15;		--  Frame0015=15
		Delay0015=0.1;		--  Delay0015=0.1
		
		OnCommand=cmd();	--  ## OnCommand en la layer del sprite
	};
	-- O bien...
	LoadActor("frames 2x2.png")..{
		Frame0000=3;
		Delay0000=0.5;
		Frame0001=1;
		Delay0001=0.33;
	};
	--Tambien:
	Def.Sprite {	-- O con LoadActor, como quieras :P
		Texture="imagen con frames 2x3.png";
		-- Es más confuso pero te evitas acomnodar todo numerado,
		-- si pusiste algo fuera de lugar solamente lo cambias y listo :D
		Frames = {
			{Frame = 0; Delay = 0.1};
			{Frame = 1; Delay = 0.1};
			{Frame = 2; Delay = 0.1};
			{Frame = 3; Delay = 0.1};
			{Frame = 4; Delay = 0.1};
			{Frame = 5; Delay = 0.1};
		};
	};
-- Equivalencias con actors
--[[-------------------------------------------------------------------------
default.lua				Filename.actor
--]]-------------------------------------------------------------------------
	LoadActor("ImageFile.png")..{	--  [Actor]
			-->		--  File=ImageFile.png
		BaseRotationZ=0;	--  BaseRotationZ=0
		BaseZoomX=1.5;		--  BaseZoomX=1.5
		
		--todos los comandos de basezoom y baserotation
		--y derivados / parecidos son acoplables a lua
	};
--[[-------------------------------------------------------------------------
Avanzados: Usando funciones / messagecommands
--]]-------------------------------------------------------------------------
	LoadActor("imagen")..{
		InitCommand=cmd(comandos;playcommand,"Custom");
		CustomCommand=function(self)
			--las variables tambien pueden ir dentro de funciones
			local timevar = 0.5
			
			self:diffusealpha(0);
			self:linear(timevar);
			self:diffusealpha(1);
		end;
		CurrentSongChangedMessageCommand=cmd(playcommand,"Custom");
	};
}

-- Agregale gráficos a las layers y verás que el file funciona a la perfección :P
-- Esto es una línea de comentario, señales para los humanos (por ej. para qué sirve eso o aquello)

uh... I will not bother translating it D:

[Midiman]

Daisuke Master, I kind of get the jist of it; Would it be bad if I just tried to take a crack at it and remaking it in english if thats ok with you?

[Daisuke Master]

first, spell my nick name correctly :P

-- Comparisons between default.lua and BGAnimation.ini
-- (checking equivalences of certain sections of both)
-- * Stepmania actor comands such linear, diffuse, etc, are written as usual
-- * Check for semicolons ubications to avoid mistakes and lua debug errors
--[[-------------------------------------------------------------------------
default.lua				BGAnimation.ini
--]]-------------------------------------------------------------------------

-- using variables (outside actorframe)
local playcond = GAMESTATE:GetPlayMode() == 'PlayMode_Regular'

return Def.ActorFrame {			--  [BGAnimation]
	LoadActor("img.png")..{		--  [Layer1]
			-->		--  File=img.png
		OnCommand=cmd(...);	--  OnCommand=...
		OffCommand=cmd();	--  OffCommand=	
	};
	LoadActor("img.png")..{		--  [Layer2]
			-->		--  File=img.png
		OnCommand=cmd(...);	--  OnCommand=...
		Condition=playcond;	--  Condition=PlayModeName() == "Nonstop"
	};
-- Fonts / Texts
	LoadFont("bitmapfont")..{	--  [Layer3]
			-->		--  File=bitmapfont
		Text="hello there";	--  Text=hello there
		OnCommand=cmd(...);	--  OnCommand=...
	};

-- Sprites!
					--  [Layer4]
					--  File=filename.sprite
					--  OnCommand=...
-- Sprite files equivalences
-- (external files for actors not needed anymore)
--[[-------------------------------------------------------------------------
default.lua				Filename.sprite
--]]-------------------------------------------------------------------------
	Def.Sprite {			--  [Sprite]
		Texture="spr 4x4.png";	--  Texture=spr 4x4.png
		BaseRotationZ=90;	--  BaseRotationZ=90
		
		Frame0000=0;		--  Frame0000=0
		Delay0000=0.1;		--  Delay0000=0.1
		Frame0001=1;		--  Frame0001=1
		Delay0001=0.1;		--  Delay0001=0.1
		
--		(...);			--  (...)
		
		Frame0014=14;		--  Frame0014=14
		Delay0014=0.1;		--  Delay0014=0.1
		Frame0015=15;		--  Frame0015=15
		Delay0015=0.1;		--  Delay0015=0.1
		
		OnCommand=cmd();	--  ## OnCommand in sprite's layer
	};
	-- Or...
	LoadActor("frames 2x2.png")..{
		Frame0000=3;
		Delay0000=0.5;
		Frame0001=1;
		Delay0001=0.33;
	};
	-- Can be too:
	Def.Sprite {	-- Or with a LoadActor, as you need :P
		Texture="image with frames 2x3.png";
		-- More confusing but helps ordering frames just by changing it's position
		Frames = {
			{Frame = 0; Delay = 0.1};
			{Frame = 1; Delay = 0.1};
			{Frame = 2; Delay = 0.1};
			{Frame = 3; Delay = 0.1};
			{Frame = 4; Delay = 0.1};
			{Frame = 5; Delay = 0.1};
		};
	};
-- Actor files Equivalences
--[[-------------------------------------------------------------------------
default.lua				Filename.actor
--]]-------------------------------------------------------------------------
	LoadActor("ImageFile.png")..{	--  [Actor]
			-->		--  File=ImageFile.png
		BaseRotationZ=0;	--  BaseRotationZ=0
		BaseZoomX=1.5;		--  BaseZoomX=1.5
		
		-- Any basezoom/baserotation type commands are
		-- aplicable to lua layers
	};
--[[-------------------------------------------------------------------------
Advanced: Using functions / messagecommands
--]]-------------------------------------------------------------------------
	LoadActor("imagen")..{
		InitCommand=cmd(comandos;playcommand,"Custom");
		CustomCommand=function(self)
			--variables can be inside functions too
			local timevar = 0.5
			
			self:diffusealpha(0);
			self:linear(timevar);
			self:diffusealpha(1);
		end;
		CurrentSongChangedMessageCommand=cmd(playcommand,"Custom");
	};
}

-- Add graphics and commands to the layers and you'll see this lua file 100% working
-- This is a comment line, notes for human beings (i.e. for what is this or that etc...)

I bothered translating it just by request D:

point me where you found engrish phrases plz, I did it fast

[Midiman]

Originally Posted by Daisuke Master

first, spell my nick name correctly :P

oops, sorry about that.

Originally Posted by Daisuke Master

point me where you found engrish phrases plz, I did it fast

ok, ill point out blocks of them I suppose

-- Comparisons between default.lua and BGAnimation.ini
-- (checking equivalences of certain sections of both)
-- * Stepmania actor commands such linear, diffuse, etc, are written as usual

compare -> comparisons
comans -> commands

        Texture="image with frames 2x3.png";
        -- More confusing but helps ordering frames just by changing it's position

confuse -> confusing


everything else is a-ok

[Daisuke Master]

Fixed already (:

[akstylish]

I have no knowledge on theming, and it seems like there are lots of codes to add if one wants to do more than changing graphics. Do I need C++ experience before getting into some serious theming?

[Daisuke Master]

nope, just some basic programming knowledge would suffice (typing algorhythms and pseudocodes) I known nothing but lua and 10% or less of C#, and I forgot completely about BASIC programming.