Notes on ScreenPHOTwON | written by AJ Kelly
--------------------------------------------------------------------------------
ScrenPHOTwOn is an implementation of a custom menu in StepMania 4/sm-ssc, using
the technology developed for Project MK2ULTRA.

MK2ULTRA (ab)uses ScreenSelectMaster's Menu[Direction][P1/P2] messages along
with a code for the Start button. A blank Actor is used for controlling the
menu state.

An example of a basic MK2ULTRA setup, where Screen* is your screen's Name:

{metrics.ini}___________________________________________________________________
[Screen*]
Class="ScreenSelectMaster"
Fallback="ScreenSelectMaster"

ChoiceNames="1,2,3,4"
Choice1="name,TopLeft;"
Choice2="name,TopRight;"
Choice3="name,BotLeft;"
Choice4="name,BotRight;"
DefaultChoice="1"

OptionOrderUp="1:3,3:1,2:4,4:2"
OptionOrderDown="1:3,3:1,2:4,4:2"
OptionOrderLeft="1:2,2:1,3:4,4:3"
OptionOrderRight="1:2,2:1,3:4,4:3"

# needed for detecting start input
CodeNames="Start"
CodeStart="~Start"

{BGAnimations/Screen* overlay/default.lua}______________________________________
local t = Def.ActorFrame{
	Def.Actor{
		Name="MenuController";
		MenuInputMessageCommand=function(self,param)
			-- check if param.PlayerNumber is active
			-- check param.Input for the pressed input
		end;
		MenuUpP1MessageCommand=function(self) MESSAGEMAN:Broadcast("MenuInput", { Player = PLAYER_1, Input = "Up", }); end;
		MenuUpP2MessageCommand=function(self) MESSAGEMAN:Broadcast("MenuInput", { Player = PLAYER_2, Input = "Up", }); end;
		MenuDownP1MessageCommand=function(self) MESSAGEMAN:Broadcast("MenuInput", { Player = PLAYER_1, Input = "Down", }); end;
		MenuDownP2MessageCommand=function(self) MESSAGEMAN:Broadcast("MenuInput", { Player = PLAYER_2, Input = "Down", }); end;
		MenuLeftP1MessageCommand=function(self) MESSAGEMAN:Broadcast("MenuInput", { Player = PLAYER_1, Input = "Left", }); end;
		MenuLeftP2MessageCommand=function(self) MESSAGEMAN:Broadcast("MenuInput", { Player = PLAYER_2, Input = "Left", }); end;
		MenuRightP1MessageCommand=function(self) MESSAGEMAN:Broadcast("MenuInput", { Player = PLAYER_1, Input = "Right", }); end;
		MenuRightP2MessageCommand=function(self) MESSAGEMAN:Broadcast("MenuInput", { Player = PLAYER_2, Input = "Right", }); end;
		-- via codes
		CodeMessageCommand=function(self,param)
			MESSAGEMAN:Broadcast("MenuInput", { Player = param.PlayerNumber, Input = param.Name })
		end;
	};
};
return t;
________________________________________________________________________________
This is a very basic design that doesn't impose how you index the items or
anything similar. Depending on how you design your screen, that could get a
little complex. I know I had some problems when designing ScreenPHOTwON.

The key elements to have are menu states and a current item index. It's best
if the two have matching values, so you can easily access them.
{example Lua: item index/menu states}___________________________________________
local curIndex = 1; -- start on the first item.
local curState = 'MenuState_Main';
-- even though I never use this table, I like to have a list of the
-- possible menu states somewhere:
local possibleStates = {
	'MenuState_Main',
	'MenuState_Option1',
	'MenuState_Option2'
};

-- itemNames[curIndex] is useful here, if you name the menu icons after them.
local itemNames = {
	"Option1",
	"Option2",
	"Exit"
};
________________________________________________________________________________