The Script Editor

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:

Script Tabs

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.

Gutter

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:

Search/Replace

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".

Editing

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. It is important to note that
script comments can be formatted and parsed by the To-Do List so
that items can be added to the list automatically (for more
information see here).

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:

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.

Another very handy tool you have at your disposal when editing
your scripts is the use of Code Snippets. By pressing
F4 you will open the code snippet pop-up, which permits
you to select one of the commonly used code methods. You can also
define your own code snippets if you want to, saving them to
the directory where you installed GameMaker Studio 2 in the
following location: \GameMaker Studio
2\TextEditor\snippets.txt. You can edit this file with any
text editor following these rules:

Each snippet is on a separate line (there should be no blank
lines).

Each snippet 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 to see how it is
set up following the rules above, and it is strongly recommended
that you make a backup of it before you start changing anything,
and also back up any edits you make to the file, as should
re-installing the program or updating it revert the changes that
you make you can use the backup to redo them again.

Information

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:

gmcallback_create_button

Using the above script name would mean that the script
gmcallback_create_button will not be obfuscated and
so can be used in JavaScript extensions and other areas of your
game, for example, when using the clickable_*
functions.