Index · Editor · Blocks · Areas · Entrances · Game/Zone · Scripts/Reference · Tools · Shortcuts


[ ] NuggED: Scripts

Nugget features a custom scripting engine based on standard XML syntax.
Scripts follow a strict node-and-attribute format somewhat similar to the
function-and-parameter format of programming languages (comment
lines and interspersed text are ignored). Scripts are used throughout
the game to add interaction, cutscenes, effects, transitions, and more.
They can be associated with specific blocks, areas, or zones,
or even reusable through the entire game.

Jump to Types / Examples / Command List

[Scripts]

Single-line commands ("nodes" or "tags") are written between "less than"
and "greater than" brackets, and terminated with a forward slash.
One or more parameters can be specified in the name="value" style,
with the numeric or textual value in either single or double quotes.
Multi-line commands can contain sub-scripts between start and end tags.

<setcolor oname='you' color='00FF00' />
<ifset zflag='5'>
  <setflags oname='you' flg='sad' />
</ifset>

You can right-click in the script editor for easy access to
block onames, sounds, music, GFlags, etc.
A full description of all possible commands is available here.

Types of Scripts
Nametimes 1sub 2after 3applies to:
start···zones
death·"
standon·blocks
die··"
enter·areas
exit·"
action·"
class···game
speedrun···"

1 For block and area scripts, "times" can be specified to limit how many times it can be triggered (this is always reset upon zone load). This must be a positive integer, or "-1" for no limit (default).

2 Instead of duplicating a script in multiple places or attached to multiple objects, you can write it once inside "sub" tags (with a globally-unique "id"), then use the "sub" parameter to link scripts (as listed above) to it.
A "sub" script is usually written inside the "start" script of the
first zone that will use it.

3 Zone "death" scripts are a special case, because dying normally clears all queued scripts. If you want to force a specific "sub" script to trigger upon restarting at the last checkpoint, specify its "id" as the "after" property.

Example Scripts

Zone Start Script
Here is an example of a start script (press S while editing a zone):

<start>
  <pause color="C0FFC0" />
  <set quit="green1" />

  <-- Color the player block correctly -->
  <ifset gflag="5">
    <you color="00FF00" />
  <else>
    <you color="FF0000" />
  </else></ifset>

  <sub id="alert">
    <sound num='10' />
  </sub>

</start>

The pause command sets the appropriate pause menu color for this zone.
The set command sets which zone the player should restart in,
if he or she exits the game and loads it again later.
The text between <-- and --> is a comment (ignored).
The ifset script block makes the player green if gflag #5 is set, otherwise red.
The sub script, which plays a sound effect, is not triggered immediately
but can be called from other places or attached to blocks, areas, etc.


Attaching a Sub Script
Attaching a sub script is simple. Here, the "alert" sub is triggered when
the player stands on a solid block (or touches it, if it is a checkpoint):

<standon sub="alert" />

The pause command sets the appropriate pause menu color for this zone.
The set command sets which zone the player should restart in,
if he or she exits the game and loads it again later.
The if block makes the player green if gflag #5 is set, otherwise red.
The sub script, which plays a sound effect, is not triggered immediately
but can be called from other places or attached to blocks, areas, etc.


Warps and Deaths
This example shows how to warp to another zone, or force a player death,
within the enter script attached to an area:

<enter times="1">
  <if zsum="1,2,3+1">
    <setflags oname="you,npc1" flg="sad" />
    <freeze secs="1.5" />
    <warp zone="south" entrance="fromnorth" />
  </if>

  <after>
    <sound num="11" />
    <die />
  </after>
</enter>

The if zsum block executes the sub-script if the sum of zflags 1, 2, and 3
is greater than 1 (at least two are set). This syntax for "greater than" (and a
minus sign for "less than") is strange but necessary since the > and <
symbols are not directly allowed in XML text.
The setflags command will give sad eyes to the player and a block named "npc1".
Freeze will halt the gameplay for 1.5 seconds.
Warp will then warp the player to the specified zone and entrance.

If the zsum condition is not met, a sound will play and the player will die
(which adds to the death count and returns you to a checkpoint).
These commands are inside an after block (with no frames or secs delay)
so the script is handled in proper order. The if block (and similar script blocks)
do not act exactly like if blocks in most programming languages;
instead of executing their inner code truly "immediately", they actually queue
the inner code to run after the currently sequence has completed!
In this example, if the after tags were absent, sound and die would always
be executed before the setflags, freeze, and warp even got a chance to run!

(And any die command will then ignore the rest of the script, including warp.)
The after tags fix the order of execution by grouping sound and die in
their own script block, which is the last to be queued.


Loops
The loop command is a convenient way to create repeating script blocks.
It is almost always used with after tags and some time delay.
Proper usage can be tricky, due to the XML format of the scripts.
The up parameter is used to control how much "up" the XML hierarchy is looped.
This is best illustrated with an example, which may be placed in a zone's start script:

<after>
  <screen shake="10,0.9" />
  <sound num="1" />
  <after>
    <sound num="10" />
    <after secs="1">
      <loop up="1" />
    </after>
  </after>
</after>

If the up parameter is set to 1 as shown (or not specified), then
the screen shake and sound #1 will only be executed once,
and the inner sound #10 will be executed every second.
If the up parameter is set to 2, the shake and sound 1 will repeat with it.
If any other tags are inserted around the commands you want to repeat,
such as some if conditions, you will need to increment the up value accordingly.
* It is planned to make loops more intuitive in a future update!


Classes and Speedruns
Block classes and game speedruns are not really "scripts", but they are
edited in the same XML format with the same syntax rules.
For more information, see the game page.



Index · Play Nugget · grudlux.com