Introduction to Scripting in PGM[]
Scripting in Pixel Game Maker MV (PGM) can allow one to create custom logic and handling using the built in runtime action commands. This can help simplify your objects runtime commands and even make them more efficient than building loops of logic using the visual programming PGM provides. This guide is intended to be a starting point and will not be exhaustive of all of the facets of the provided API for PGM. This guide will not be an exhaustive tutorial on how to program using JavaScript (JS) or CoffeeScript (CS). However, the guide is written with the laymen in mind with appropriate resources to help bridge the gap.
This guide is aimed at users familiar with PGM's interface and logic systems. If you're new to PGM, please come back to this later after you've mostly understood the engine.
Helpful Resources[]
When building scripts, the following programs and assets are highly recommend to assist in creating scripts.
PGM's API Document[]
You'll need this document to reference commands.
Notepad++[]
It is recommended to grab this program to allow you to write scripts more efficiently.
W3Schools[]
If you have no Javascript (JS) knowledge or struggle with finding the correct syntax and functions to do what you need to do, look no further than W3Schools and their database on JS.
File: project.json[]
This is where your project data is stored and can help you figure out how to formulate your commands for specific runtime actions. This is typically located in the "data" folder.
Formatting and Limitations for Scripting[]
Scripts in PGM can utilize IIFE (immediately invoked function expression). Because of this, this ensures that the scripts you write don't necessarily interact with other coded aspects of your game, causing undesired effects. Think of it as setting an "instance" that only things referenced inside of this "instance" will be contained and matter here at runtime. While this is optional for script events in an action node, this is required for scripts running as a link condition.
For the purposes of this document, everything will be written with IIFE in mind.
When creating your script with IIFE in mind, it must be wrapped accordingly:
(function () {
//Script Contents go here
})()
Outside of this, standard JS formatting rules apply (JS is case sensitive, semi-colons are needed to end JS statements, etc). W3Schools has more information on this.
From here, we'll dive into building a simple script to output some log data to the Runtime Log Console.
Building a Basic Script: Part 1 - Defining the Variables[]
When building a script, you'll need to define the script variables to be used in appropriate commands later on.
To reference switches and variables from a project level, your variable declarations at the beginning will look like the following:
(function () {
var enemy = Agtk.objectInstances.get(instanceId);
var shotgunMag = Agtk.variables.getIdByName("Shotgun Mag");
var bossCamera = Agtk.switches.getIdByName("Boss Camera");
})()
At this stage, I am grabbing the current instance of this specific object, creating/declaring the variables "shotgunMag" and "bossCamera",
and associating them with the appropriate variables named in the project in the common area.
Let's break down the following:
var shotgunMag = Agtk.variables.getIdByName("Shotgun Mag");
1 2 3 4 5
- "var" - This declares/creates a variable to be used in JS as a container. This is similar to how variables work in game.
- "var" Name - This is the name of the variable we'd track. JS is case sensitive, so best practice is to name the variable in a way that makes it easy to code and remember its purpose. W3Schools recommends using either camel case (thisVar) or pascal case (ThisVar).
- Namespace - This identifies the "scope" or "focus" of the following parameter afterwards. Globally called parameters will start with "Agtk". Everything else will start with the appropriate object instance variable you create in the beginning of your script (Ex. enemy.execCommandParticleShow(args);). All runtime commands will need to reference a specific object instance to execute/perform the desired command.
- Function Name & appropriate parameter - This is the name of the function you want to use along with the appropriate parameter. The API document for PGM displays all appropriate commands.
- Appropriate value to be referenced - This is contextual based on the Function Name/Parameter combo in use.The API document for PGM displays all appropriate command usages
Building a Basic Script: Part 2 - Make the data readable[]
Now that we've established our starter variables and switches, now we need to convert the data to be readable in JS.
You do this by doing the following:
(function () {
var enemy = Agtk.objectInstances.get(instanceId);
var shotgunMag = Agtk.variables.getIdByName("Shotgun Mag");
var bossCamera = Agtk.switches.getIdByName("Boss Camera");
var shotgunMagVal = Agtk.variables.get(shotgunMag).getValue();
var bossCameraVal = Agtk.switches.get(bossCamera).getValue();
})()
So before, we were establishing the appropriate needed variables. Now we need additional variables to be able to read that data. "Agtk.variables/switches.get" allows us to pull those values we established so they can be used; We just need to reference variables that store the results of this data.
Building a Basic Script: Part 3 - Using the data[]
Now that we've done so, it's time to print these values out into the Runtime Log Console. To do so, we're going to use the "log" function name to display this. Log works like this:
Agtk.log(content);
So, to display the values of the variable and switch we've grabbed values for, we're going to display them like this:
(function () {
var enemy = Agtk.objectInstances.get(instanceId);
var shotgunMag = Agtk.variables.getIdByName("Shotgun Mag");
var bossCamera = Agtk.switches.getIdByName("Boss Camera");
var shotgunMagVal = Agtk.variables.get(shotgunMag).getValue();
var bossCameraVal = Agtk.switches.get(bossCamera).getValue();
Agtk.log("Shogun Magazine has this many: " + shotgunMagVal):
Agtk.log("The Boss Camera Switch is the following: " + bossCameraVal);
})()
In order for our message to display in the log and we can see it, I wrote a message and encapsulated it's contents in parenthesis, and then printed the appropriate value by referencing the variable we got the value with. If done correctly,
your script should display the following in the log whenever the appropriate action node comes across the "Execute Script" runtime action in a PGM object:
Scripting Examples[]
So far, this was a very simple and rudimentary example on how to use scripting. But what about something more useful? Click the link below to go to a related article that contains a list of script examples by myself and others. If anyone has a custom script you'd like to share with every one, please let me know so it can be added to the list of examples!
Tips and Tricks[]
Coming Soon