You can use code in a number of places within GameMaker:
Studio, from objects, to rooms and instances, and there are a
number of built in functions that make your life easier when
programming, however it is often necessary for you to create your
own functions to do a specific task, or to condense a large
section of code into a more manageable chunk, or even to be able to
re-use a particular code block in many different places. That is
why GameMaker: Studio gives you the ability to create
Scripts are written using GML (the Game
Maker Language, covered in the Reference section), which is the
built-in programming language that GameMaker: Studio uses.
Once you become more familiar with GameMaker: Studio and
want to use it to its fullest extent, it is advisable to start
learning to use this language, as it greatly expands your
possibilities when creating games.
A script (like any built-in function) can take different input variables, with real, string, boolean and special values like all or noone being accepted, and these input variables are generally called arguments, although they are also referred to as parameters. To execute a script from an object or a time line you can use the Execute Script action , but you can also call it in a code box using the actual script name as if it were a function or even by using the GML function script_execute. If you use the script action you can specify the script you want to execute, together with the up to five arguments, but if you are using the code editor to call a script, you can pass up to sixteen arguments.
As mentioned above, you can pass a number of arguments to a
script, and it will use these to perform the task you have written
it for. To understand this better, take, for example, an action (or
a code in GML) and think about how it works... you place it in an
event and specify a number of parameters and it will make your
instance do something. Scripts are exactly the same, with the only
difference being that you write them! Not only can you pass
arguments into a script, but you can also ask a script to
return a value too (using the return keyword), so
you can use them to build calculating methods (mathematical
methods) or give back an instance id after a complex collision
detection or any number of things. Please note, however, that using
return effectively ends the script, and so no code
after it has been used will be executed, and this means that a
certain amount of thought has to go into how your scripts are
You can save and load scripts from *.txt files into
GameMaker: Studio and in this way you can create collections
of scripts and store them for use in multiple projects. To load a
script (or a collection of scripts) into GameMaker: Studio,
simply right-click on the scripts resource folder (or any
sub-folder that you have created in that section) and select Add
Existing Script. This will open the file browser and you can
select either a script *.gmx, or a *.txt file. They will
then be loaded in to GameMaker: Studio.
For saving scripts it's a similar process, where you right-click on a script (or a script folder) and select Export Selected Script. This will open up a window asking you where to export to, and when you click on "Okay", the script will be saved as a *.txt file, with the name of the file being the same as the name of the script. If you have selected multiple scripts in a folder, they will all be saved, each with the name of the script they correspond to.
To create a script in your game, choose Create Script
from the Resources menu, or right click on the scripts
resource in the resource tree and select Create Script, or
just click the create script button on the toolbar at the top of
the main GameMaker: Studio screen. Whatever method you
choose will open the following window: Note: The script editor
window and the code editor window for objects have exactly the same
functionality. The only difference between them is that the script
editor has a name box whereas the code editor has the choice
of which instance is to run the code (self, other or object), just
like the D'n'D actions.
When you open the script editor, you should first give your new
script a name. This should be something sensible and easy to
remember and recognise, and must not start with a number or
have any symbols (except the under-bar "_" symbol). The name you
give the script is the one you will use later as a function in
code. It is also a good idea to write some comments at the start of
the script (see the above image) to outline the script arguments
and how it should be used, especially if you are going to work as
part of a team, or plan on using many scripts in your game.
Once you have done that you can start to write your script using standard GML functions and variables, using the many options along the Toolbar at the top to help you in this process. Here is a brief explanation of what each of the toolbar buttons does:
This will close the script editor and save any changes you have made. Be aware that there are no confirmation messages asking if you want to save.
Load A Script From A File
This will open the standard window for loading a script that has previously been saved as a text file. This will replace the existing script with the loaded one.
This will save your current script as a *.txt file, ready to be used in another game.
This will open a standard windows dialogue where you can select a printer and print out your current script on paper.
This will undo the last action, and you can repeatedly undo consecutive actions with this button, but note that the number of undos that can be performed is limited to 16.
If you have used the undo function, you can use this to go back to the state that you undid. This is limited to the number of undos that you have done previously.
You can use this to "cut" a section of your code out of the script. This code is stored to the clipboard and can then be pasted into another part of the same script, another script resource or even into some other program, independent of GameMaker: Studio.
This button will copy the currently selected code into the clipboard for use in another place, either the same script, another script or even an alternate program.
You can use this button to paste whatever text you have previously stored in the clipboard (with cut, or copy) into the current script.
Search And Replace
Clicking this button will open the search/find and replace tab in the script editor. See below for more details.
This button will toggle on and off the syntax checker of the script editor. When on, any errors in the code syntax will be highlighted in red (default) and a message will be displayed at the bottom of the editor explaining briefly what the problem is. Note that not all aspects can be tested at this stage but the syntax of your script will be tested, together with the existence of functions used.
When this is switched on, if you pause when typing something an auto-complete window will pop up and you can then use the cursor keys or mouse to navigate to the function that you are looking for. The image below illustrates this:
There are a number of keyboard shortcuts to help you navigate around the script editor, and each one is designed to help you get the most from this powerful tool:
- By pressing f2 you get the code snippet pop-up, which permits you to select one of the commonly used code methods. You can define your own code snippets if you want to, saving them to the Local App Data directory (ie: C:\Users\MyUserName\AppData\Local\GameMaker-Studio) for future use using the name "snippets.txt". If there are no snippets defined then GameMaker: Studio will copy the defaults from the Roaming directory (ie: C:\Users\MyUserName\AppData\Roaming\GameMaker-Studio). You can edit this file with any text editor, and each snippet is on a separate line (there should be no blank lines). It starts with the name of the snippet (which is what is shown in the menu) followed by the colon (:) followed by the actual snippet of code. Use # for a newline and put the text that needs to be selected first between | symbols. See the examples that are already in the file in the Roaming directory to see how it is set up, and it is strongly recommended that you make a backup of it before you start changing anything, although the base file will be re-installed when you update GameMaker: Studio (but the Local App Data version will remain).
- You can use f7 and f8 to change the size of the font within the editor.
- If you press f10 you can toggle on or off the colour coding for your code.
- Press <CTRL> + F to call up the search, find and replace options (see below).
- If you are using multiple scripts, then you can press f12 (or click the Middle Mouse Button) when the mouse is over any of the other script names to have it opened in a new window, ready for editing. If no script is selected, then the manual will be opened.
- You can press <Shift> + f12 (or <Shift> and the Middle Mouse Button) when the mouse is over any selected text to have it open the Search In Scripts window, already populated with the selected text. You can also do this on a function (without selecting it) and the function will be used to populate the search feild of the window.
- You can use <Ctrl> + Z for undo and <Ctrl> + <Shift> + Z for redo.
- The arrow keys move you around in the text, and you can use <Ctrl> with the left and right arrow key to move to the beginning of the previous or next word. If you use <Ctrl> with the up and down arrows you also scroll the text.
- You can hold the <Shift> key and move with the arrow keys to select text.
- The <Home> key moves the cursor to the beginning of the line and the <End> key to the end of the line, and if you also hold <Ctrl> they move to the start and end of the script. Holding the <Shift> key you can select the text too.
- Use <TAB> to indent selected lines and <Shift> + <TAB> to unindent selected lines.
- Hold <Ctrl> with the <Backspace> or <Delete> key to delete until the beginning of the previous or next word.
- You can force the auto-complete window to appear if you have it switched off in the Scripts Preferences by pressing <Ctrl> + <Space>, and you can cancel it at anytime by pressing <ESC>.
- You can drag a selection with the mouse. (Use <Ctrl> to copy it.) The new location is immediately shown.
- You can scroll through the text with the mouse wheel and with <Ctrl> pressed the cursor scrolls with the text. As with previous shortcuts, holding the <Shift> key selects text.
Commenting your code is very important for maintaining
productivity as it keeps things clear and separates sections of
code in such a way that it is obvious what each part does and why
it is there. It also means that if you are working in a team then
you can leave notes for other members and that they will know
exactly what you have done or what a specific section of code is
for. Even if you are a solo developer, leaving comments for your
code is important, especially if you have to leave the project and
come back to it at a later date.
Commenting your code is simple, as you just have to use "//" before any line of text or you can comment out whole paragraphs by using "/* text here */". The following image illustrates a script using both these methods: If you are in the code editor, then you can also give your code box a title by making a comment for the first line using the following format:
///Your Comment Here!
This comment will then be used for the "name" of that codebox (this works for codeboxes added to Timelines too) as illustrated by the following image: If you use make a comment in this way in the script editor, then the comment text will be used as the auto-complete text in the code editor when you type the script. So, in the example script image above above we have the script "MovePlayer", and it starts with a "///" comment, which would then show in the code editor like this:
When creating larger games, you will often require many, many
scripts and this can cause a certain amount of "clutter" in the
resource tree, and it can be hard to keep track or organise the
scripts in a coherent fashion. To help with this, the Script
Editor has child scripts available to you in the form of tabs.
So, say you have a player object with a create script, a movement
script, a collision script and a draw script. Instead of placing
them all in the resource tree, you would have a parent
script, with its name being the one shown in the resource tree, and
various child scripts. These child scripts are no different
to any other scripts in your game, and will work as they should.
However they will not appear in the resource tree, and to
access them you must first open the parent script. To create a new
child script you simply click on the empty tab that is always to
the right of the current tab (if you can't see this, then try
scrolling the rest of the tabs using the arrows in the top right
corner). This will create the new script which you should name, and
it will be stored within the parent script when you close and save
the script editor. You can also delete these scripts easily by
clicking on the "cross" icon that you can see on all the script
As you might have noticed, parts of the script text are
coloured. The script editor "knows" about existing objects,
built-in variables and functions, etc. and colour codes them
accordingly. colour-coding helps a lot in avoiding mistakes, in
particular, you see immediately if you have misspelled some name or
use a keyword as a variable, or have a syntax error. However, if
you don't like the colour coding, in the Preferences you
can switch it on and off (you can also use F10) as well as
customise the colours that are used.
When working with code, it is common that you will want to find
some piece you have written in a large section and then replace it
something different, or simply see at a glance where a line of code
lies within the function. To this end, the GameMaker: Studio
script editor has a search, find and replace function that can be
accessed by pressing the Search button in the toolbar. This will
open up a panel on the right of the code window which looks as
can type the find string at the top (note that in the code all
occurrences of the find string are immediately shown with a yellow
background), and you can indicate whether the search must be case
sensitive, which is normally what you want as variable and function
names in GML are also case sensitive, and whether you want to only
search for whole words. Note that the editor remembers your most
recent searches, and you can click on the drop down button to call
them up and re-select them. With the buttons underneath the search
string input you can now move to the previous, next, first, and
last occurrence of the find string, and this string will be
selected in the text so that you can edit it.
You can also use this panel to replace anything that you have previously searched for by simply typing in the new code that is to be used and pressing one of the buttons that are highlighted underneath. Now you can use the buttons to replace the previously selected, the next one to be selected, the first, the last or all occurrences of the code searched for. Note that since your scripts can be spread over multiple tabs in the same category, you are also provided with a Replace in all tabs option which, when checked, will use the search and replace terms to parse all the scripts in all tabs for that category, rather only the one currently selected.
The script editor permits you to bookmark a script so that you
can open it directly from the IDE using a key combination rather
than having to click through multiple windows and icons. This is a
very handy way to track script changes while testing your game, and
is activated simply by moving the cursor to the line of the script
you want to bookmark and the holding <Shift> +
<Control> + <NUM>, where <NUM> is a
number from 1 to 9 on the keyboard. The script editor will now show
your bookmark beside the code in the editor. To open the bookmarked script
again at any time, you should use the keyboard combination
<Control> + <NUM>, where <NUM> is
the number key of the bookmark.