Wiki

Clone wiki

Mono:UI / Tutorials / Getting Started

Getting Started

To get started with Mono:UI, you'll most likely want to get to grips with a few of the concepts that it uses, as well as some of the functionality. This guide aims to acquaint you with the basics, so that you have a starting point, from where you can use or easily acquaint yourself with some of the more advanced things that Mono:UI can do.

Setting up Mono:UI

The first thing you'll want to do is download Mono:UI. You can check out the Changelog to find the most recent release. Currently there haven't been any stable releases, so find the latest release at the top and download it in your preferred format.

Once you have downloaded Mono:UI, you can unpack it to a directory of your choice, and open it as a GameMaker Studio 2 project.

First Steps

You will see that there are already quite a few things in place. You won't need to worry about most of it; it's there to do the work for you.

To get started, create a new room, and open up the room creation code. To initialise all Mono:UI functionality, perform this function:

m_init();

It is important that this always happens before you do anything else involving Mono:UI, or the game might crash.

Creating a Button

One of the things that comes with Mono:UI by default is a button. This button can be customised in a variety of ways, as we will see later. For now, though, let's just create it. For this, we call m_init.

m_init();

var _btn = instance_create_depth( 100, 100, 0, m_Button );

If you run the game, you'll see that it already appears, without us having needed to do anything else. You can even click it and watch its appearance change.

Using Properties

Mono:UI has a concept called Properties. Properties are meant to be an intuitive way to change an element's behaviour or appearance. However, this concept is more powerful than just that. For now, we'll focus on changing the button that we have created using some Properties.

The first thing we'll want to do is consider what we want to do with our button. Here are some examples.

  • We want to make it blue.
  • We want to display the words "Click me!" on it.
  • We want to make it 200px wide.

Mono:UI has a function called m_property_set_value. However, it also uses the shorthand MONO, since it's the function you'll be using most. We can use this to set a variety of Properties for our newly created button.

m_init();

var _btn = instance_create_depth( 100, 100, 0, m_Button );

MONO( _btn, [
    [ "theme", "bold" ],
    [ "label", "Click Me!" ],
    [ "shape.width", 200 ],
] );

If you run the game, you'll discover that the button's appearance has changed.

Using Themes

In the above example, one of the things that might stand out as odd is the "theme" Property. It should be clear that it changes the colour, but exactly why and how it does it, is harder to deduce.

Mono:UI has a concept called Themes. A Theme is basically a collection of colours that you can apply to an element all at once. Mono:UI comes with some default Themes. "bold" is one of those Themes, which gives the element an assertive blue colour.

If you want to make your own Theme, this is also very easy. We can use a function called m_make_theme. With this function, you can even override Mono:UI's default Themes, which is in fact encouraged. So let's do this, and make our button pink instead of blue.

m_init();

m_make_theme( "bold", $dc9ee0, $f2c5f5, $ffffff, $b469b9, true );

var _btn = instance_create_depth( 100, 100, 0, m_Button );

MONO( _btn, [
    [ "theme", "bold" ],
    [ "label", "Click Me!" ],
    [ "shape.width", 200 ],
] );

The button is now a nice shade of pink.

To explain the code we just wrote, we need to break it down into 3 parts.

First, we have the name. In this case, "bold" is our name. This means that whenever we want to access this Theme, we can retrieve it be using that name.

Second, we have 4 numbers. These are hexadecimal values that represent a colour. If you copy those numbers and put them in a colour picker of your choice, they'll show the associated colour.

Third, we have the format. By default, GameMaker Studio 2 expects colours to be in BGR format. All of its colours work that way internally. Normally, a value of $ff0000 would be red, but in GameMaker Studio 2, it is blue. If you're working with these colours, then you can leave out the true at the end. However, if you want to input values using an RGB format as opposed to BGR, you must use true so that Mono:UI knows to convert the colours you've entered.

Using Plans

Now that we've created a nice-looking button, it's time to actually make it do something. Right now, if you click, nothing happens.

To make the button do something, we use another Mono:UI concept, called a Plan. A Plan describes an action to be performed. In case of a button, this happens when it is clicked.

Plans are a little more difficult to understand than the other concepts, but for now, we can use a simple one. Let's take a look at the Plan we're going to be using.

[
    scr_message,
    "Hello World!"
]

This Plan consists of two parts.

First, we have a script. If you create this script, Mono:UI will be able to call it when the Plan needs to be executed.

Second, we have an argument. If you have more than one argument, you will need to provide an array of them. But for our example, we need just one.

Let's create our scr_message script first:

show_message( argument[ 0 ] );

Now, let's return to the room creation code, and plug in our Plan.

m_init();

m_make_theme("bold", $dc9ee0, $f2c5f5, $ffffff, $b469b9);

var _btn = instance_create_depth( 100, 100, 0, m_Button );

MONO( _btn, [
    [ "theme", "bold" ],
    [ "label", "Click Me!" ],
    [ "shape.width", 200 ],
    [ "plan", [
        scr_message,
        "Hello World!",
    ] ],
] );

If you run the game, you'll discover that when you click the button, a message will pop up with the text "Hello World!", as planned.

Setting Defaults

It can be a chore providing all these properties if you have multiple buttons. If we want them all to be pink and 200px wide, do we really need to specify so every time? Actually, no.

Let us consider the following code:

m_init();

m_make_theme("bold", $dc9ee0, $f2c5f5, $ffffff, $b469b9);

m_property_set_default( "all", "theme", "bold" );
m_property_set_default( "all", "shape.width", 200 );

var 
    _btn1 = instance_create_depth( 100, 100, 0, m_Button ),
    _btn2 = instance_create_depth( 100, 150, 0, m_Button );

MONO( _btn1, [
    [ "label", "Click Me!" ],
    [ "plan", [
        scr_message,
        "Hello World!",
    ] ]
] );

MONO( _btn2, [
    [ "label", "Or Me!" ],
    [ "plan", [
        scr_message,
        "Lorem Ipsum",
    ] ]
] );

You can see that we use the function m_property_set_default to set the values that all other Mono:UI elements will use thereafter.

The first argument, "all", in this case refers to a predefined target. Mono:UI comes with several such targets, that allow you to apply defaults to select groups of elements. In this case, the default Theme and width for all Mono:UI elements is set. If we change the argument to "button", another predefined target, only buttons will be affected.

What Next

Congratulations! You now understand the basics of how to operate Mono:UI.

After getting this far, you might want to take a look at a few of the following things:

Updated