Usage¶

Setup guide¶

This will guide you through the important steps to set up a fully functional menu.

Regions¶

Open oMenu’s create event, here is everything for configuring the menu.

Here you’ll see a lot of regions. All of them are marked either with a (system) or a (user) tag. You only want to change the (user) tagged regions.

Every region is a settings for something.

Here is a list of the regions and what they do:

Audio settings - Menu sound effects settings
Credits text - Text for credits (if you have one)
Look settings - The menu’s look, visual settings
Animation settings - Button animation settings
Scrolling settings - Settings for scrolling (if you have a big menu page)
Pause settings - Pause menu settings
Menu array - The menu’s structure (buttons and what they do)
Input setup - Menu navigation settings

Creating the menu array¶

First, you should create the menu array. Which defines how your menu is structured, what buttons are on which page and what do they do.

Go to the menu’s Menu array region, here will be an empty array. This is where your buttons go.

That empty array is a page array which means that it stores buttons. Buttons are also arrays they consist of two elements:

Button name
Button function

Here is the list of button functions:

ScriptRunner - Runs a script or a method
Slider - Changes a value in a range (usually used for volume settings)
Shift - Changes a value between a set of options (good for graphics, difficulty settings, etc.)
Toggle - Toggles a value on or off.
Controls - Creates a controls menu from an InputSystem
Credits - Displays a scrolling credits screen

These are constructors so they should be created with the new keyword in front of them.

Or if you want your button to switch to another menu page, the second element in the array should be another array that will also have buttons in it.

Here is a basic example:


menu = [
    ["Start",   new ScriptRunner(function() { room = rGame })],

    ["Settings", [
        ["Audio", [
            ["Master",      new Slider([0, 1], 0.3,         "audio_master")],
            ["Sounds",      new Slider([0, 1], 1,           "audio_sounds")],
            ["Music",       new Slider([0, 1], 1,           "audio_music")]
        ]],

        ["Graphics", [
            ["Quality",         new Shift(["Low", "Medium", "High", "Ultra"], 2, "quality")],
            ["Window Mode", new Shift(["Windowed", "Fullscreen"], 1, "window_mode")],
            ["Vsync",               new Toggle(0,           "vsync")]
        ]],

        ["Controls", new Controls(global.input_sys, "input_save.json", true, ["right", "left", "up", "down"])]
    ]],

    ["Credits", new Credits(credits_string)],

    ["Quit",    new ScriptRunner(game_end)]
];

Okay, this may look a bit confusing here is what it does:

The first button is the "Start", it runs a function which simply goes to another room.

After that comes "Settings" which holds another menu page. Inside the "Settings" there are also two menu pages "Audio" and "Graphics". These have a mix of sliders, toggles, and shifts in them.

Then comes the "Credits" which displays the credits text defined in the Credits text region.

And at last "Quit" which runs the built in function game_end().

To see how a menu array looks like with pausing, click here.

Here are some tips:

The ScriptRunner can call built-in functions as well.
When creating a Controls menu it’s good to make the input system global, so the menu can access it easily.
Controls generates a new menu page for it’s self so you don’t have to put it in an additional menu page.

Creating menu presets¶

If you have a title menu you most likely want to have a pause menu as well. But obviously a pause menu should have different buttons in it than a title menu, for instance instead of a start button you might want a resume button, or you may want to remove some buttons. Basically you can create alternatives of buttons or add compleately new buttons for different situations. So for that this system has menu presets which allows you to change what buttos do when the game is running.

To create a new preset for a button you simply add another name and button function to it.

You can have as many presets as you want.

So the start button before:


["Start",   new ScriptRunner(function() { room = rGame }]

And the start button with an additional Resume preset:

["Start",   new ScriptRunner(function() { room = rGame },
"Resume",   new ScriptRunner(resumeGame)]
Warning

The second button is added to the end of an existing button array and it isn’t in a separate array!

You can also make a button invisible when in a preset by setting both its name and function to undefined.


// This button is only visible on the title screen
["Start",   new ScriptRunner(function() { room = rGame },
undefined, undefined]

// This button is only visible in the pause menu
[undefined, undefined,
"Save & Quit",   new ScriptRunner(function() { save code here }]

To change presets use the menuSetPreset() function. Give it the preset number from 0 to the number of presets - 1.

I recommend using an enumerator for this purpose. There is one by default at the bottom of the Menu array region. Feel free to add your presets to it.

There is a title_screen and pause_menu preset added by default:


enum e_menu_presets {
    title_screen,
    pause_menu
}

So then later you can call menuSetPreset() like this:


menuSetPreset(e_menu_presets.pause_menu);

See more about pausing here.

Changing the look¶

To change the way your menu looks go into the Look settings region.

Here you will see two structs:

look - The look settings of the entire menu
item_look - The look of individual items (e.g. sliders, toggles, shifts, etc.)

There are a bazillion options so I won’t go through all of them but here are the imporant ones.

Start with the look struct.

Here are are the three main settings.

txt - Text font, size, outline etc.
col - Color settings
pos - Position of the menu and elements

In the text settings there is a normal and small text type. Normal is used most of the time, small is for input icons and disclaimer text at the bottom.

Set your own fonts for both if you don’t like the default one.

Note

There are options marked with an (A) tag. These can be set to auto (automatic). If so the system will predict an appropriate size for the item. If the systems prediction is wrong just try until you find a good-looking value for it.

Then go onto the col struct. Here are two types selected and unselected. You have to set two colors each, one used most of the time and a more intense/dark color. Set them to your liking.

Then in the pos struct, you most likely want to change the menu_pos.y because the menu is in the middle by default so it may cover the title of your game or something.

You can set a nine slice sprite four your buttons background, to set it go to item_look > button and set the nine_slice variable to a sprite that is nine slice enabled.

But in case someting isn’t working how you want it. Here are the other things I didn’t talk about:

If a specific menu element looks wrong find it in Look settings > item_look struct
To change the menu’s sounds go to Audio settings
To change the button animation or turn it off go to Animation settings
To change scrolling behaviour go to Scrolling settings
To change things about pausing go to Pause settings
To change buttons used to navigate the menu go to Input setup

And here are some tips if your font looks odd.

If you are using a pixelated font turn of anti-aliasing on it. And if it still doesn’t look right try changing the size of the asset until it looks good, the nuber should be around the height of the font in pixels.

On the other hand you are using a non-pixelated font scaling will mess it up, so go into look > txt and set scale to 1. Now you will have to change the font assets size until it is properly sized, it takes some time but it’s worth it.

Pausing¶

If have a game with a title menu you usally want to have a pause menu as well. For that the system offers a built in pause system wich will basically take a “photo” of the screen, deactivate every object, and than draw the “photo” on the screen. This way it looks that the game is paused.

You can do this two ways:

Manually - by calling the pauseGame() and resumeGame() functions
Automatically - by calling the menuPauseEnable(), and from then the menu will handle pausing

You also have to disable the menu when you enable pausing, because it would cover half of your game. But you want to reenable it when you go back to the title screen.

For this purpose I made two useful scripts.

menuModeTitle() enables the menu and disables pausing, because you don’t want the player to pause the game when it isn’t started yet.
menuModePause() disables the menu so that you can see the game, and enables pausing so that you can use the pause menu.

And also when you enable pausing you most likely want the menu to look a bit differently, for instance replacing a start button start with resume. If you haven’t made any menu presets read about them here.

Ok, so when you want to switch to pause mode call the menuModePause() function and set your preset by calling menuSetPreset(). And when you want to set it back to title screen mode call menuModeTitle() and set you preset back with menuSetPreset().

Here is an example of a Start button with a Resume preset.


["Start",   new ScriptRunner(function() {
    menuModePause();
    menuSetPreset(e_menu_presets.pause_menu);
    room_goto(rGame);
}),

"Resume", new ScriptRunner(resumeGame)]

And here is an example of a Quit button with a Back to title preset.


["Quit",    new ScriptRunner(game_end),

"Title Screen", new ScriptRunner(function() {
    menuModeTitle();
    menuSetPreset(e_menu_presets.title_screen);
    room = rTitle;
})]

To see a fully set up menu example with pausing, click here.

To change how the menu looks when the game is paused go to the Pause settings region in the create event.

The settings struct (getting values)¶

After you have created your menu you want to get the values of settings somehow.

The values are stored in a struct called global.settings. To get the value of an item write global.settings.save_key where the save_key is the string what you defined in the menu array when you created the item.

Here is how the different elements save their values:

Slider - (type: real) The value will be in the range you defined when you created it
Shift - (type: real) The value will range from 0 to the number of options - 1
Toggle - (type: bool) Either true or false
Controls - The controls changes the given input system directly it does not return anything

You can do anyting with these values in any object but there is a Change actual values region in the menu’s step event for it. Here you can change the window size, volume etc.