The skin struct - harpwood/Easy-Virtual-Joystick-for-GameMaker-LTS-2022 GitHub Wiki

Before creating the joystick, you can modify the joystick skin struct to customize its behavior according to your needs. However, you can still access and modify these parameters at any time after creating the joystick. For instance, if you want to change the color, you can access the color parameter as shown below:

vj_left.skin.color = c_red;

Now, let's explore the skin struct further.

The skin struct can be either SPRITE based or DRAW based. The SPRITE based skin uses a sprite, while the DRAW based skin uses the internal draw functions of GameMaker. The DRAW based skin is more expensive in terms of performance, especially if the circle precision is high. If no skin struct is supplied, a default DRAW based skin will be applied. The size of the default skin will be calculated based on the size of the GUI layer.

The SPRITE based struct

This is an example SPRITE based struct:

//example struct of SPRITE based skin
	vj_sprite_skin = {
				// sprite: (sprite) The sprite asset for the joystick
				sprite: s_joystick_1080p,
				// base_index: (number) The sprite index of the base
				base_index : 0,
				// knob_index: (number) The sprite index of the knob
				knob_index : 1,
				// color: (color) The blend color of the base and the knob
				color : c_white,
				// alpha: (number) The opacity of the base and the knob
				alpha : 1
			}

skin.sprite

// sprite: (sprite) The sprite asset for the joystick
sprite: s_joystick_1080p,

In the sprite parameter, you can assign the desired sprite to use as a joystick skin. The Easy Joystick Extension package includes four complimentary joystick skin sprites to use in your project: s_joystick_240p, s_joystick_360p, s_joystick_720p, and s_joystick_1080p. Alternatively, you can pass the name of the sprite as a string to the sprite parameter:

// sprite: (sprite) The sprite asset for the joystick
sprite: "s_joystick_1080p",

This is useful if you want to define or create the sprite skin dynamically during runtime. For example, you can store the size of the GUI layer in a global variable and use it to dynamically create the name of the sprite:

global.gui_size = "1080p";

var _skin = "s_joystick_" + global.gui_size;

vj_sprite_skin = {
				// sprite: (sprite) The sprite asset for the joystick
				sprite: _skin,
                
                // ...rest of struct...
                }

The base_index refers to the index of the sprite that will be used as the base for the joystick. Similarly, the knob_index is the index of the sprite that will be used as the knob for the joystick. Both of these sprites must be present in the same sprite asset. If base_index is not supplied it will be assumed as 0 index. If knob_index is not supplied, it will be assumed that knob_index = base_index + 1.

It is important to define these values when using a sprite asset that contains multiple skins. It is recommended to pair each base and knob with their indexes next to each other. For example, if a sprite asset contains two variations of a skin, the first variation should be defined with base_index : 0, knob_index : 1, and the second variation should be defined with base_index : 2, knob_index : 3.

skin.color

// color: (color) The blend color of the base and the knob
color : c_white,

The color parameter determines the color blend of the base and the knob sprites. This means that any non-transparent pixels in the base and knob sprites will be blended with the color parameter.

In the example code, the color is set to c_white, which means that the base and knob sprites will not be affected by any color blending. If you wanted to apply a different color to the joystick skin, you could set the color parameter to any valid GameMaker color value. For example:

color : c_red 

or

color: make_color_rgb(255, 0, 0); // Creates a red color

This would apply a red tint to the base and knob sprites of the joystick skin.

skin.alpha

// alpha: (number) The opacity of the base and the knob
alpha : 1

The alpha parameter determines the opacity of the joystick skin, including both the base and the knob sprites. The value of alpha should be a number between 0 and 1, where 0 represents fully transparent and 1 represents fully opaque.

If you wanted to make the joystick skin slightly transparent, you could set the alpha parameter to a lower value, such as 0.5:

alpha : 0.5

This would make the base and knob sprites 50% transparent, allowing whatever is behind them to show through to some extent.

Providing a sprite instead of a sprite struct

Instead of providing a sprite-based skin struct, you can simply provide the sprite or its name as a string. If strict evaluation of the struct is enabled, the script will create a sprite struct with default parameter values. If strict evaluation is not enabled, the sprite will be used as-is.

vj_left = new virtual_joystick(,,, s_joystick_1080p);

vj_left = new virtual_joystick(,,, "s_joystick_1080p");

We will explore the strict evaluation of structs in more depth in the next section.

The DRAW based struct

This is an example DRAW based struct:

// Example struct of DRAW based skin
	vj_draw_skin = {
			// base_radius: (number) The radius of the base of the joystick
			base_radius : 90,
			// knob_radius: (number) The radius of the knob of the joystick
			knob_radius : 60,
			// base_thic: (number) The thickness of the base's outline
			base_thic : 2,
			// color: (color) The color of the base and the knob
			color : c_grey,
			// circle_precision: (number) Determines how many sides the base and the knob will have (more equals more expensive)
			circle_precision : 24,
			// alpha: (number) The opacity of the base and the knob
			alpha : 1
		}

skin.base_radius

// base_radius: (number) The radius of the base of the joystick
base_radius : 90,

The base_radius parameter is used to set the radius of the base of the joystick skin. The radius determines how large the base of the joystick will be.

In the example code, the base_radius is set to 90. This means that the base of the joystick will have a radius of 90 pixels.

You can adjust the base_radius value to make the base of the joystick larger or smaller. For example, setting it to 50 would create a smaller joystick base, while setting it to 120 would create a larger joystick base.

skin.knob_radius

// knob_radius: (number) The radius of the knob of the joystick
knob_radius : 60,

The knob_radius parameter determines the radius of the knob of the joystick, which is the smaller circle that sits on top of the base circle. In a DRAW based skin struct, the knob is drawn as a filled circle. It is generally good practice to keep the knob_radius smaller than the base_radius.

skin.color

// color: (color) The color of the base and the knob
color : c_grey,

color is a parameter that defines the color of both the base and the knob of the joystick. The value for this parameter should be a color data type, which can be a constant value like c_grey or defined using the make_color_rgb() or make_color_hsv() functions.

skin.alpha

// alpha: (number) The opacity of the base and the knob
alpha : 1

The alpha parameter determines the opacity of the joystick skin, including both the base and the knob sprites. The value of alpha should be a number between 0 and 1, where 0 represents fully transparent and 1 represents fully opaque.

If you wanted to make the joystick skin slightly transparent, you could set the alpha parameter to a lower value, such as 0.5:

alpha : 0.5

This would make the base and knob sprites 50% transparent, allowing whatever is behind them to show through to some extent.

SPRITE based VS DRAW based structs

Generally, using a SPRITE based skin is better for performance, but when deciding between a SPRITE based or a DRAW based skin, it's important to consider various aspects of your game design, not just performance.

It's also worth noting that the script will automatically recognize whether a skin struct is SPRITE or DRAW based by inspecting its parameters. If the "sprite" parameter is found, it will be assumed to be a SPRITE based struct and any DRAW based parameters will be ignored. Conversely, if a skin struct is recognized as DRAW based, any SPRITE based parameters will be ignored. Any missing parameters will be provided with default values, which may vary depending on whether strict evaluation is enabled or not. We'll discuss strict evaluation in more detail in the next section.

Previous : The configuration struct Next : Structs Evaluation