Hello, Code Ninjas. This post will be somewhat brief. I discovered a neat thing about Game Maker's map data structures that wasn't made clear in the help file, although (if you dig deep enough) the new Game Maker Studio documentation mentions it without drawing attention to it. If you don't know about it already, it could be quite useful.
Basically, the neat thing is this: The keys (as well as the values) of key/value pairs in a ds_map can be strings as well as real numbers, e.g. the following is valid:
// set a string key to a value
ds_map_add(myMap, 'keyName', someValue);
// get a value from a string key
someValue = ds_map_find_value(myMap, 'keyName');
This gives one a lot of power over merely using reals, so you'd think that the documentation would brag about it; perhaps it was assumed to be obvious. It wasn't obvious to me. I gave it a try on a whim after a bout of Javascript programming which made me think of it, and it just happened to work.
Now if you are wondering how string keys are treated by functions such as ds_map_find_first(), ds_map_find_next(), etc. it's pretty simple - they are considered alphabetically. Where the help file talks about these functions as returning the "smallest" key or the "next largest" key, which makes sense in terms of real numbers, you can substitute "earliest alphabetically" or "next in alphabetical order". For example, "a" would be a "smaller" key than "b".
The alphabetisation is case sensitive and is strict about punctuation and numbers, so it won't always behave intuitively. For example, if you add the keys "1", "2", and "10", then "10" will be considered "smaller" than "2". Uppercase letters are considered "smaller" than lowercase, as well.
Finally, if you have a mix of real keys and string keys, all real keys are considered "smaller" than all string keys. A real key of 4000 is "smaller" than a string key of "0".
Hopefully I'm not just super clueless and this was all totally obvious from the get go, and somebody benefits from me pointing it out. :)
Constants are basically just like variables, only you can't change them at runtime; you can only change them using the constants form when developing the game. Having grown up with 16-bit video game consoles, I always visualise constants as being in ROM while variables are in RAM - this is purely an analogy, though, as it hardly describes what's really going on in a modern computer.
The cool thing about Game Maker's constants form is that it is more powerful than it really lets on. The documentation is fairly vague; it says "A value of a constant should be a constant expression. That is, it is either a constant number or a string (with quotes around it) or it is an expression." This hints at, but does not make explicit (especially for beginners), the fact that you can use functions for the value of your constants. Or more accurately, the return values of functions.
There are limitations, of course. You can only use Game Maker's built-in functions, and not your own scripts. But you can do stuff like the following example:
The constant DISPLAY_WIDTH will equal the result of the display_get_width() function (the width in pixels of the user's display at its current setting). Now, I must make it exceedingly clear, because this can confuse beginners (as once it did me), but the constant will be, well, constant. Using DISPLAY_WIDTH in your code will not call display_get_width() and give you a new result each time. Constants are evaluated at the very beginning of the game when it runs, so the only time display_get_width() gets called is then; the return value (and only the return value) is stored in DISPLAY_WIDTH.
(Of course display_get_width() is only used as an example, because it's a simple function to understand. In practice you may never use it, because the user (or the game itself) might change the display settings at some point.)
You can go even further, nesting functions like so:
So this is much like what you might do in code or a script, e.g.
There are two advantages to constants in my opinion. First, they are colour coded in Game Maker's code editor, and are also part of the auto-complete feature. This is very helpful when coding. And second, it's often cleaner to put them into the constants form that is already provided rather than writing a script full of globalvar and then calling it somewhere in your code.
So now that the basics of using functions for constants are established, I want to get to the "trick" that is the point of this post. Because Game Maker's data structures are created by calling a function, you can make constant data_structures, like so:
To be fair, the functions that create data structures return a reference, or "handle", for the newly created data structure, to be used with other data structure functions. The constants will only be the handle; the data structure itself can still be manipulated. However, because of the two advantages to constants mentioned above, this might still be something you want to do if you have a data structure which will exist for the entire duration of your game.
If this was all you did, then it would still be up to code or scripts to define the contents of the constant data structures. But you can fill in those constants using the constants form, as well. Observe:
Using a second constant, the ds_list_add() function is called, adding a value to the list pointed to by CONSTANT_LIST. The second constant is named using three underscores; it could be anything, but since we don't care to ever use it (it will only contain the return value of ds_list_add(), which is unimportant) the name should be something that won't cause conflicts.
It so happens that it's not possible to perform multiple functions per constant, e.g. separated by semicolons. You won't get an error if you try, but only the first function will be evaluated. But you can just use multiple constants to do as many functions as you want. And, because constants can be multiply defined, only one name need be used, like so:
Of course this might get rather silly after a while, filling your whole constant form with functions to fill a list. However, the data structure functions for reading and writing to strings will work just fine. So the following has the identical effect as the example above that added three values using separate function calls:
Maybe this trick will come in useful someday for you Code Ninjas. If not I hope it was interesting to those who are as fascinated by Game Maker exploits as I am.
Please note that the following only applies to Game Maker 8.0 using this shader extension. However, the principle can be applied to anything else that uses shaders.
Okay, time to get started. Let's say you have an image. It's made of pixels - obviously - and each pixel is a colour. Where things get interesting is how you choose to describe that colour, i.e what bits or bytes you use to signify it.
The simplest way is to use 1 bit per pixel - on or off. But that only gives you a monochrome image. What about colour? A very common way is to use 24 bits per pixel - one byte each for the red, green, and blue channels. This gives you 256 levels of intensity for each channel, allowing over 16 million vibrant colours, and indeed 24-bit colour is sometimes referred to as "true" colour.
The drawback to methods such as 24-bit true colour is that they use a large amount of memory. So, a common practice in old-school games was to use indexed colour: a palette contains the actual colours, while the pixels in an image are only described by a single value - the index (i.e. the address in the palette) of the colour to be used for that pixel. (Read more at Wikipedia.)
The indexing method, in addition to saving memory, has another big advantage. If you change a colour in the palette, any and all pixels that reference the index of that colour will change along with it. An otherwise static image can come to life in this way - lights can flash, water can flow, stars can twinkle - all without true animation of any kind. (See a beautiful example of this in action.)
As memory and CPU power improved, these little tricks largely fell by the wayside. Software such as Game Maker doesn't provide any functionality for palettes by default, which is bad news for anyone who wants to emulate the effects of old-school games.
Fortunately, LSnK has come to the rescue with his shader extension for Game Maker. (Sadly it is only compatible with version 8.0 of GM, but 8.0 is still a sufficient tool for making great games.) It allows one to use shaders in Game Maker with little more effort than setting the fog colour.
Shaders are quite a complicated subject, but for the purposes of palette effects (and this article) we will only be considering pixel shaders (also referred to as fragment shaders). You can think of a pixel shader as a tiny program that runs for each pixel that is drawn. If you activate a pixel shader and then use a drawing function, each pixel to be drawn is input to the shader, the shader runs, manipulating the pixel in some way, and finally the pixel is output to the screen.
There are a great many effects pixel shaders can achieve. A common example is drawing an image in greyscale: the red, green, and blue channels are used to determine the perceived brightness of the colour, and then that brightness value is output to all three channels, making the corresponding shade of grey.
Now, I'm not going to explain every little thing about how to use the shader extension or make a shader - there's plenty of instruction on how to do these things on its own page. Here I'm only concerned with explaining the idea behind emulating palette effects with a pixel shader. I'll also provide an example GMK at the bottom of the article to get you started.
So let's move on. First, we need a palette (any image that's one pixel in height with colours in horizontal sequence will do). Let's use Sonic's palette from Sonic 1 as an example.
We'll also need an image of Sonic.
The above image clearly won't do. It's already in colour; what we need is an image of Sonic where each pixel is an index in a palette. I've made a tool called Palettiser that lets you do exactly that. It'll analyse an image and replace all the pixels with shades of red - shades of red whose intensity corresponds to an index in a palette, for a max of 256 colours. Having completed that process one ends up with an image of Sonic that looks like this (since there are only about 16 colours in the palette, the shades of red are all very dark, almost black):
Now, both the palette image and the funky-looking converted image can be imported into Game Maker as a sprite or background resources.
The next step is to create a custom pixel shader. A shader that, when active, will perform the following operation on every pixel that is drawn:
Get the amount of red in the pixel.
Use that value as a horizontal coordinate, finding the colour at that position in the palette image.
Draw a pixel of that colour instead.
By drawing the converted image with the shader active, the original Sonic image can then be recreated correctly. But this time it will palettised - any change to the palette image colours will be reflected in the Sonic image immediately.
But how to change the palette image colours? It's a background or sprite, right? Well, what's cool is that a shader can also use surfaces. If you make your palette a surface, you can draw anything to it, and in so doing animate the palette.
But talk is cheap. It's much cooler to see this happen and play around with it in real time. To that end, here is an example GMK. (Be sure and install the shader extension first, of course!)
This is a bit of weird - and undocumented - behaviour.
When you write scripts in Game Maker, you can have them return a value by using the return statement, like so:
return true;
What value does the script return if you don't have any return statement, though? Does it always return true, or false, or maybe something else? I wanted to know, and I learned something surprising when I looked into it.
At first I thought the answer was that the script would always return false, but this rule didn't always hold. What's more, the return values I was getting were seemingly random and unpredictable.
Finally I discovered what was going on. A script returns the value of the most recent equation.
What does that mean exactly? Well, for example, a script containing only this line:
a = 10;
...will return 10. And, likewise:
a = 10;
b = 20;
...will return 20. Whatever the result of the most recent equation is becomes the return value!
This holds true for math operators like *=, +=, and so on. This:
argument0 *= argument0;
...will return the square of argument0.
How bizarre! Even if you leave out the return statement, you will still get "phantom" return values... I guess this might be the cause of odd behaviour once in a while, so it's good to know about.
This is a correction of a mistake in my last post.
The last section said this:
This is all very well and good for rounding, but what about flooring or ceiling a number? This trick always rounds up with a fractional part of 0.5 or above, and rounds down below that. In Game Maker, you can use the floor() function to always round down, and the ceil() function to always round up.
You're in luck, because you can do code like this:
a = number - 0.5 >> 0; // equivalent to a = floor(number)
// or
a = number + 0.5 >> 0; // equivalent to a = ceil(number)
These will still be very nearly twice as fast as their function equivalents!
The trouble is that only works if your number actually has a fractional part. If you try to floor or ceil an integer that way, you'll get the integer -1 and the integer +1, respectively.
I can still pull my fat out of the fire, though. Instead of using 0.5 as the value to be subtracted (for flooring) or added (for ceiling), you can use a constant that's just ever so slightly less than 0.5, such as:
0.5 - power(2,-43)
Just set this up as a constant (call it something like MATH_CEIL) and then make a second constant that's the negative of it (e.g. MATH_FLOOR = -MATH_CEIL). Then you can do:
a = number + MATH_FLOOR >> 0; // equivalent to a = floor(number)
// or
a = number + MATH_CEIL >> 0; // equivalent to a = ceil(number)
And everything I said still holds. You'll still get the job done twice as fast as using the function equivalents. (The use of constants doesn't slow it down at all.)
I suppose you might still technically run into a problem if you're using numbers that require a precision greater than power(2,-43), but for most purposes that'll never happen. Again, this is merely a trick to be used in code that requires optimisation at all costs, not everywhere in your program.
This post is nothing too special or groundbreaking, but it might be of interest to anyone who is as huge of a nerd as I am.
I noticed long ago that Game Maker automatically rounds numbers and variables when they are used as array indices. So, for example array[3.6] is precisely equivalent to array[4].
I also noticed that the same thing happens when performing binary operations:
1.1 & 1.9 is precisely equivalent to 1 & 2. The same principle holds for ^ and |.
3.7 << 8.4 is precisely equivalent to 4 << 8. The same principle holds for >>.
Knowing this is certainly useful; it can rid your code of unnecessary calls to the round() function.
But I got an evil thought - what would happen if I tried bit shifting a number by zero, e.g. 32 << 0 or 32 >> 0? Mathematically, a bit shift of zero should leave the number unaffected, but would Game Maker go ahead and round it anyway?
The answer is yes! 31.5 >> 0 is equal to 32. Therefore this code:
a = number >> 0;
Has the identical effect as this code:
a = round(number);
An interesting quirk; a titbit of trivia. So what?
Well, I suspected that it might be a faster operation than the calling of the round() function, and so I tested this hypothesis. The result?
Bit shifting by zero is twice as fast as using round(). Now, that function is hardly going to break the bank, but if you have code that relies on it heavily this is definitely something to consider with regard to optimisation.
You can also binary AND with bitwise NOT one, as in this code:
a = number & ~1;
It also has the effect of rounding the number, and is also much faster than round(), comparable to the speed of the bit shifting method. I just don't like the readability as much; the bit shift method >> 0 looks like it's knocking off digits past zero, which is a reasonable mnemonic for rounding.
This is all very well and good for rounding, but what about flooring or ceiling a number? This trick always rounds up with a fractional part of 0.5 or above, and rounds down below that. In Game Maker, you can use the floor() function to always round down, and the ceil() function to always round up.
You're in luck, because you can do code like this:
a = number - 0.5 >> 0; // equivalent to a = floor(number)
// or
a = number + 0.5 >> 0; // equivalent to a = ceil(number)
These will still be very nearly twice as fast as their function equivalents!
(The above about flooring and ceiling isn't perfect; be sure to read my correction!)
Okay, so maybe in practice this will make your code more confusing and less readable, but like I said: "huge nerd". =P
I've recently discovered a clutch of "rogue" operators in GML: operators that are fully functional but totally undocumented in the help file. While I wouldn't recommend using any of them (they might make your code less portable), they might be interesting to be aware of.
:=
When first n00bishly using GML, I did what I'm sure a lot of others did: I used the = operator for comparisons, e.g. if (a = b), as well as assignment, e.g. a = b. Turns out this is really bad practice if you ever plan on learning other languages (like, say, javascript), because they treat the two very differently. Assignments in javascript actually return the right-hand value, not true/false; so if you were to say if (a = 0) the conditions would never be true, just as if you'd said if (0). The solution, of course, is to use the comparison operator == for condition testing, e.g. if (a == b), and use = only for assignments.
So where does := come into all this? If GML matched other languages, it should be purely an assignment operator, e.g. a := b and not if (a := b). But since GML is special, it's merely a synonym for =. Yep, you can say if (background_color := c_blue) and it'll do the exact same thing as if (background_color = c_blue) or if (background_color == c_blue) in GML.
Dumb. Like I said, these aren't recommended.
<>
This is just a straight synonym for !=. It returns true if the left-hand and right-hand variables are not equal.
!<, !>
You would think these were cute alternatives for the <= and >= operators: whereas you might say if (a<=b) to test if a is less than or equal to b, you could also say if (a!>b) to test if a is not greater than b for the identical result. However, you would think wrong, even though there are some places around the net that suggest it's true. In GM 8.0, at least, these do not work; they throw a syntax error if used in code. (Though, oddly, they'll just be ignored if used as part of watchers in debug mode: a!>b will just return a no matter the right-hand variable is.)
|=, &=, ^=
Okay, so these are documented in the help, but not in the operators section, and there's also a confusing typo where they're listed (suggesting that one of them is &\). But they are very useful if you know them; they're the bitwise brethren to the +=, -=, *=, and /= operators. For example, a |= b is equivalent to a = a|b.
