You can use code in a number of places within GameMaker Studio 2 from objects, to rooms, to instances, and there are a number of built in functions that make your life easier when programming with GML or Drag and Drop. 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, which is why GameMaker Studio 2 gives you the ability to create scripts.
NOTE: While this section deals with scripts, the code window that you write your scripts in is the same as that for Events, room or instance creation code or Shaders, and the functionality outlined here applies to all of them.
NOTE: This page references GML for writing scripts, but you can also create scripts using Drag and Drop (see here) . No matter what you use to code your project, the information on this page is still valid for the editor itself.
Scripts are written using the scripting language GML (see the GML Overview section for more details), which is the built-in programming language that GameMaker Studio 2 uses. Once you become more familiar with GameMaker Studio 2 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. You can also write scripts using Drag and Drop, but that requires a different editor and is discussed in the section of the manual for Action Scripts
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 often referred to as parameters. To execute a script from an object or a time line you use the script name as if it were a function or by using the GML function script_execute. You can name the script by right-clicking on it in the resource tree and selecting Rename, but note that the script name must conform to the scripting rules for functions, so they must start with a letter and only contain letters, numbers or the "_" under-bar symbol.
As mentioned above, you can pass a number of arguments to a script (16 in total), 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 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 structured.
When you first create a resource the script editor window will open with the following options:
The script editor opens in a window with tabs across the top to let you have multiple scripts in one window (although this behaviour can be changed from the Preferences to give a new window to each script). You can click on a script and then drag it to re-order the tabs, or if you prefer, you can pull it out of the current window and place it on the workspace to create a new window for that script (or add it to a different window), and you can also maximise the script editor to create a new workspace too. If you drag a script tab out of the IDE window, then a new IDE will be spawned to hold this script resource, and it can be used as you would the Main window.
Note that if you are editing code from an object event in the script editor and you have maximised the script editor or have it on a separate window or workspace, then the right-click editor menu will have some extra options:
- Restore to workspace: This will take the script editor out of a maximised/workspace state and re-chain it to the object in the workspace.
- Go to Object: This will take you to the workspace that the object with the code is on and focus on the object.
- Add /Open Event: This permits you to add a new event to the object the current script belongs to, and will open a new code tab in the Script Editor for the added event. If the event selected already has code in it, then this will be opened in a new tab.
For information on the rest of the right-click menu options, see the section on Editing below.
The Gutter is used to show the line numbers for your code and also to convey some specific pieces of information. Most importantly, if you make mistakes or construct the code incorrectly, the GameMaker Studio 2 IDE will inform you of the issue by flagging the line of code that is causing the issue with a red exclamation mark . You can then mouse over the symbol to get a brief description of what the issue is:
The gutter will also mark any line of the script that has had a breakpoint added. A breakpoint is simply a place in the script where you want the debug module to pause the execution of your game when it is reached. You can toggle a breakpoint from any line of any script or object event by pressing "f9" or using the right-click menu. When you add a breakpoint, it will show up like this in the gutter:
Finally, the gutter will also show any bookmarked items too. To bookmark a line of code simply hold down / + + Number (from 0 to 9), and this will permit you to skip back to this line of code from anywhere in the IDE simply by using / + Number (from 0 to 9). To delete the bookmark, simply perform the same action as you used to add it on the line of code again. When a bookmark has been added, it will show like this:
While working in the script editor, you can press / + "F" to open up the Search box or / + "H" to open up Search And Replace:
Here you can perform a local search for the keyword you input and once you have entered your search term, you can then use the arrows at the top right of the search window to skip from one found term to the next in the script. You can change how the search operation is carried out by toggling the following buttons:
Whole Word Only: When you toggle this, the search function will only highlight those strings that match the whole input string. For example, with it off a search for "random" will show up all words that contain this string - like irandom(), or randomise() - while toggling it to on would only show the function random(). Case Sensitive: When this option is toggled, you are telling GameMaker Studio 2 to check not only the contents of the search string, but the case too. For example, if you have a sprite called "spr_Dog" and do a search for "dog" with this toggle off, then the sprite string will be highlighted, however if the toggle is on then it won't since "Dog" is no longer considered the same as "dog".
If you have opened the search window using / + "F", then the replace functionality will not be visible, so you need to click the Replace button to open it. Once open you can then enter a string that will be used to replace any given search string, using the following buttons to perform the action:
Replace Next: Clicking this will replace the next search string found in the script with the given replace string. Note that the "next" term is considered the next one after the current cursor position, and you can skip to different ones using arrow buttons at the top right of the search window. Replace All: Clicking this will replace all examples of the search string within the script using the given replace string.
Note that if you want to do a global search (ie: search the whole project rather than the current script), then you can press / + + "F".
The main script editor is where you'll write all your code to create the script or fill an object event. Scripts and code events are written following the general rules for GML syntax (see the GML Overview section for more details), and you can get help while writing your scripts from the auto-complete window:
This window will pop up while you are writing your code (normally after a slight pause, but this can be set in the Preferences) and give you a selection of "best-fit" answers in alphabetical order. While using the code editor you can click and drag the mouse to select a row of code or hold down then click and drag to select columns of code. Anything selected in this way can then be copied, cut and pasted using the standard window shortcuts of / + C, / + X and / + V.
It is worth noting that you can comment your code in various ways. 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 */". There are even two keyboard shortcuts to comment and uncomment selected lines of code: / + K to comment, and / + + K to uncomment. The following image illustrates a script using both these methods:
Scripts can also have certain JSDoc style comments added so that when you use them in your code they show up in auto-complete along with their arguments and other details. you can find out more about this from the section JSDoc Script Comments for more information.
Apart from comments you can also use special #region tags to mark a section of code for Code Folding. How this works is that you add a #region tag (along with any comment text) to the top of a section of code and then add a corresponding #endregion tag to the bottom of the section and then you can "fold" the code, ie: hide it away so you can cut down on the number of lines of code visible in the editor at any one time:
The actual code looks something like this:
#region This is an example region
width = sprite_get_width(sprite);
height = sprite_get_height(sprite);
xoff = sprite_get_xoffset(sprite);
yoff = sprite_get_yoffset(sprite);
#endregion Further comment here if required
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 as you can 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.
You can right-click anywhere in the editor too to open up the following menu:
Apart from the regular functions you'd expect to cut, copy and paste lines of code you also have the option to comment or uncomment any selected text, add or remove indents, as well split the code window into 1, 2 or 3 separate panes (note that the options relating to #regions will not be available if you have not defined any in the code being edited). These last options will split the window into different parts where you can then drag a script and have it show alongside the other ones for comparing and editing.
This is exceptionally useful for comparing two scripts or for viewing connected scripts at the same time, without needing another window or having to switch constantly between tabs. The other options in this menu are to toggle a breakpoint for use with the Debugger, and to convert the GML code into DnD™ or vice versa. Note that if converting code to DnD™, then it will not create individual actions for each line of code, but rather use a single code action to hold everything that was previously in the event or script.
The information bar at the bottom of the IDE shows you the current line number you are on and the position along the line. It is also where you can see the code helper, which is a line of text that shows the function you are currently editing along with the arguments it requires. As you fill in the function in the editor, the arguments will highlight to show you which one you are currently editing. If you have used the JSDoc Script Comments within a custom script then the information you have supplied will also show here.
Please note that if you are developing for Web (ie: targeting HTML5), then there is an additional script protocol that you can use, which is to preface a script name with gmcallback_, for example:
A very handy tool you have at your disposal when editing your scripts is the use of Code Snippets. When using the script editor, you can press F4 to open the code snippet pop-up, which permits you to select one of the commonly used code methods from a list:
From this window you can select with the mouse the snippet to use, or you can press the associated hotkey listed on the right. This will add the snippet to your code for editing.
You can also define your own code snippets if you want to. Before doing this, you'll need to create a file called "snippets.txt" in one of the following directories:
- Windows: %ProgramData%\GameMakerStudio2\User\
- macOS: /Users/Shared/GameMakerStudio2/User/
This folder is not modified during an update to GameMaker Studio 2, so your edited file will remain intact (but any edits to the base snippets file in the install directory will be reverted).
Once the file is created in the User directory, you can edit it with any text editor following these rules:
I - Instance Create:
I - Instance Create:instance_create_layer(x, y, |layer|, object);
The code that you add must also follow a specific format where:
See the examples that are already in the base snippets file to see how it is set up following the rules above. You can find the base file in the GameMaker Studio 2 install directory:
- \GameMaker Studio 2\TextEditor\snippets.txt