Script Types#
This section describes the various different types of scripts, and how they differ from one another.
Global Scripts#
Global Script ~Init
global script Init
@InitScript()
no this-> pointer
No InitD[] available
Runs when a new save file is first created, for a single frame only.
All scripts with the @InitScript() annotation
as well as a script named global script Init will be “merged”,
all being run at this time.
Global Script Active
global script ScriptName
no this-> pointer
No InitD[] available
Starts running when the quest is launched, and continues until the script exits. Generally paired with an infinite loop to run forever during the entire quest, to run main global logic.
The script will stop (and restart thereafter) whenever the game ‘exits’, which includes:
The Hero dies (script will see the Hero’s HP as
0for a single frame first, and can revive them)The player opens the engine ‘F6 Menu’
Any script calls Game->Continue(), Game->End(), or other similar functions that ‘continue’ or ‘exit’ the game.
Global Script onExit
global script ScriptName
no this-> pointer
No InitD[] available
Runs when the game is exited, for a single frame only.
Global Script onSaveLoad
global script ScriptName
no this-> pointer
No InitD[] available
Runs when an existing save file is loaded (not for new files), for a single frame only.
Global Script onLaunch
global script ScriptName
no this-> pointer
No InitD[] available
Runs when the game is launched- this will run just after the
Global Script ~Init or Global Script onSaveLoad.
Runs for multiple frames, in frozen script mode, before the opening wipe.
Perfect for use cases such as a title screen. (you can keep track of if the player has already seen it using a global variable, and either skip it or behave differently as a result)
Global Script onContGame
global script ScriptName
no this-> pointer
No InitD[] available
Runs for a single frame only when the game is ‘continued’ (ex. Game->Continue(), F6->Continue, or Continue from the game over screen), prior to the opening wipe.
Global Script onSave
global script ScriptName
no this-> pointer
No InitD[] available
Runs for a single frame only whenever the game is saved. If the onExit script would
also run from the same condition (ex. Save and Quit), onExit will
run first.
Hero Scripts#
Hero Script Init
hero script ScriptName
this-> pointer type: Hero
No InitD[] available
Runs for a single frame only when the Hero is ‘created’- usually at the start of the game,
and upon respawning after death.
Hero Script Active
hero script ScriptName
this-> pointer type: Hero
No InitD[] available
Effectively identical to the Global Script Active.
Hero Script onDeath
hero script ScriptName
this-> pointer type: Hero
No InitD[] available
Runs when the Hero is dead, in frozen script mode. At this point they can already no longer be revived- however, this script may display a custom Game Over screen / continue menu (similar to the Global Script onF6Menu, but for death instead of manually triggering the menu).
The Quest Rule Hero OnDeath script runs AFTER engine death animation determines
if this script runs before or after the engine death animation, which can be
used to either allow your script to do a custom menu after the engine animation,
or to do your own custom death animation before your custom menu!
Hero Script onWin
hero script ScriptName
this-> pointer type: Hero
No InitD[] available
Runs when the Hero wins the game, in frozen script mode. Intended for custom scripted credits scenes and similar; the engine credits can be disabled via Game->SkipCredits.
Itemdata Scripts#
Itemdata Action Scripts
itemdata script ScriptName
this-> pointer type: itemdata
Available InitD[]: 8 (Shared with the item’s Pickup and Sprite scripts)
Runs when the item its attached to via the Item Editor is used by the Hero. It continues to run until it exits, and the item cannot be used again while its script still runs.
Incompatible with Itemdata Passive Scripts.
Itemdata Pickup Scripts
itemdata script ScriptName
this-> pointer type: itemdata
Available InitD[]: 8 (Shared with the item’s Action/Passive and Itemsprite scripts)
Runs when the item it’s attached to via the Item Editor is picked up by the Hero, for a single frame only.
Itemdata Passive Scripts
itemdata script ScriptName
this-> pointer type: itemdata
Available InitD[]: 8 (Shared with the item’s Pickup and Sprite scripts)
Runs when the item it’s attached to via the Item Editor is owned by the Hero. It continues to run until it exits, and starts again automatically when the Hero respawns.
Replaces the Itemdata Action Script, if the Constant Script flag is
checked in the Item Editor. Due to this, these are incompatible with
Itemdata Action Scripts.
Screen-Based Scripts#
Screen Scripts
screendata script ScriptName
this-> pointer type: Screen
Available InitD[]: 8
Runs starting when the screen it’s at is entered (after scrolling onto the screen)
Additionally runs for a single frame during the loading of the screen
(before scrolling onto it) if the flag Run On Screen Init is checked.
FFC Scripts
ffc script ScriptName
this-> pointer type: ffc
Available InitD[]: 8
Runs when the FFC it’s attached to via the FFC Editor exists with a combo set other than ‘0’ (after scrolling onto the screen)
Additionally runs for a single frame during the loading of the screen
(before scrolling onto it) if the FFC flag Run Script at Screen Init
is checked.
Combo Scripts
combodata script ScriptName
this-> pointer type: combodata
Available InitD[]: 8
Runs when the combo it’s attached to via the Combo Editor exists,
on any enabled layer (after scrolling onto the screen). The layers
can be set by enabling the Quest Rules Combos Run Scripts on Layer #
for each layer number.
Combo Scripts are the only scripts capable of accessing several combodata variables, accessible by this->X, this->Y, this->Pos, this->Layer. These values all are specific to the combo position on screen of the currently running script, rather than the combo ID.
‘Sprite’ Scripts#
‘Sprite’ scripts are any script types that refer to a sprite-typed object,
i.e. npc, itemsprite, lweapon, eweapon (hero excluded from this section)
Enemy Scripts
npc script ScriptName
this-> pointer type: npc
Available InitD[]: 8
Runs when the npc it’s attached to via the Enemy Editor is alive on-screen.
Itemsprite Scripts
itemsprite script ScriptName
this-> pointer type: itemsprite
Available InitD[]: 8 (Shared with the item’s Action/Passive and Pickup scripts)
Runs when the item it’s attached to via the Item Editor exists on-screen as a collectable object.
LWeapon Scripts
lweapon script ScriptName
this-> pointer type: lweapon
Available InitD[]: 8
Runs when the weapon it’s attached to via the Item Editor exists.
EWeapon Scripts
eweapon script ScriptName
this-> pointer type: eweapon
Available InitD[]: 8
Runs when the weapon it’s attached to via the Enemy Editor exists.
Subscreen & DMap Scripts#
Subscreen Scripts
subscreendata script ScriptName
this-> pointer type: subscreendata
Available InitD[]: 8
Runs when the Active Subscreen it’s attached to via the Subscreen Editor is open.
DMapData Active Scripts
dmapdata script ScriptName
this-> pointer type: dmapdata
Available InitD[]: 8
Runs starting when the DMap it’s attached to is entered. Continues running during screen scrolling.
DMapData Scripted Active Subscreen
dmapdata script ScriptName
this-> pointer type: dmapdata
Available InitD[]: 8 (Shared with Scripted Passive Subscreen)
If a script of this slot is assigned for the current dmap, then pressing
the START button will no longer open the engine Active Subscreen, but
will instead launch this script, in frozen script mode.
Quest Rules are available to allow the ‘DMapData Active Script’ and ‘DMapData Passive Subscreen Script’ to run during this script.
If you trigger a warp during this script to a dmap with a different script, that dmap’s script will be immediately loaded instead.
DMapData Scripted Passive Subscreen
dmapdata script ScriptName
this-> pointer type: dmapdata
Available InitD[]: 8 (Shared with Scripted Active Subscreen)
Runs starting when the DMap it’s attached to is entered. Continues running during screen scrolling. Has a Quest Rule to allow it to run during special timings (wipes/refills) when other scripts normally do not run.
DMapData Scripted Map
dmapdata script ScriptName
this-> pointer type: dmapdata
Available InitD[]: 8
If a script of this slot is assigned for the current dmap, then pressing
the MAP button will no longer open the engine Map, but will
instead launch this script, in frozen script mode.
If you trigger a warp during this script to a dmap with a different script, that dmap’s script will be immediately loaded instead.
Generic Scripts#
Generic scripts don’t really have separate slots, but there are 3 different ways to ‘design’ a generic script, which splits them up similarly.
All generic scripts settings in editor are set up in the Init Data menu.
Generic Script (Standard)
generic script ScriptName
this-> pointer type: genericdata
Available InitD[]: 8
A standard generic script will run as long as the related
genericdata->Running is true.
This can be set in Init Data to start as true at the start of a new
save, and becomes false if the script exits.
In addition to the standard Waitframe(), these scripts can use WaitTo() for additional precise timing control (ex. ‘right after the keyboard/controller input is read’)
Generic Script (Frozen)
generic script ScriptName
this-> pointer type: genericdata
Available InitD[]: 8
A generic script run in frozen script mode, either via genericdata->RunFrozen(), or other in-engine means such as SCCs or combo triggers.
Generic Script (Event Handler)
generic script ScriptName
this-> pointer type: genericdata
Available InitD[]: 8
A generic script can use WaitEvent()
to listen for one or more special ‘event timings’. Which timings it
listens for are set either in Init Data, or via
genericdata->EventListen.
Game->EventData[] can be used during an event timing to read many, and write some, data related specifically to that event- for example the damage the player is about to take from an enemy contact damage hit.
‘Frozen Mode’ scripts#
When a script runs in a ‘Frozen Mode’, everything (or, nearly everything) in the entire engine will be paused. Other scripts will not run either, unless specifically stated as an exception.