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

NuggED: Script Reference

This page describes all commands available for XML scripts.
Commands are listed alphabetically within their category, but
related commands (such as lock/unlock) are paired together.

Script Flow · Gameplay · Objects · Graphics · Audio

Each command's parameters are listed (required ones are underlined).
The letter N means the parameter expects an integer.
The symbol # means the parameter expects a decimal number.
The symbol $ means the parameter expects some text.
The symbol 0/1 means the parameter expects 0 or 1 (false or true).
The letters RGB means the parameter expects
a hex-format color (RRGGBB, with no prefix).
The symbol ... means multiple values can be entered.
Multiple values should be separated by commas.

Script Flow
after	secs='#' 'r#' 'r#,#' frames='N' 'rN' 'rN,N' This will queue the script commands between the after tags, either immediately or after the number of seconds/frames specified. The 'r' prefix can be used to select a random time between 0 and the number specified, or between the two numbers specified.
call	sub='$' This will immediately queue a sub script stored elsewhere, specified by its unique id.
freeze	secs='#' 'r#' 'r#,#' frames='N' 'rN' 'rN,N' This will freeze the player and the current script. The amount of time is in the same format as after.
if else	entrance='$' speedrun='N' '+N' '-N' '!N' standing='0/1' gsum='N,...' '...+N' '...-N' '...=N' zsum='N,...' '...+N' '...-N' '...=N' zint='N,...' '...+N' '...-N' '...=N' This will queue the contained script if all of the specified conditions are true. Otherwise, it will queue the script between the contained else tags, if any. You can check the following conditions: • if the most recent entrance matches a certain name • if the speedrun "level" is equal to, greater than, less than, or not equal to N (typically 0 = not a speedrun, 1 = world speedrun, 2 = full-game speedrun) • if the player is standing on a block or not • if the sum of listed GFlags (gsum) is nonzero, greater than, less than, or equal to some value N • if the sum of listed ZFlags (zsum) is nonzero, greater than, less than, or equal to some value N • if the Zone Integer (zint) is nonzero, greater than, less than, or equal to some value N
ifset ifnotset	gflag='N' and='N,N,...' or='N,N,...' zflag='N' These are similar to if, and support the optional else sub-script. You can check if a single GFlag or ZFlag is set (or not set), or check if all (and) or at least one (or) of the listed GFlags is set. These are mostly obsolete and can be replaced with if gsum or if zsum.
killqueue	sub='$' This will cancel all queued scripts (excluding the active one), and then optionally re-queue the specified sub.
loop	up='N' This will re-queue the active script. By default, it loops only the commands at the current XML node "depth" or "level". You can queue farther up the script hierarchy by specifying the up parameter (default 1). For proper loop usage, see the Scripts page.
prompt	This will freeze the player and the current script, until the player presses Enter or Space.
wait	secs='#' 'r#' 'r#,#' frames='N' 'rN' 'rN,N' This will freeze the current script, like freeze, but the player is still allowed to move.

Gameplay Commands
adddeath	num='N' This will add N to the player's death count (1 by default). This is usually used within a zone's death script. The count is incremented automatically if the player dies in a zone without a custom death script.
camera	zoom='#' slow='#' fast='0/1' lookat='$' lock='0/1' This will change various camera parameters: • zoom (default = 100, smaller = zoom in) • slow (controls the pan speed of the camera, 20 is typical, higher value = slower movement) • fast mode (when enabled, the camera tracks the target block instantaneously, without lag) • lookat (the oname of the target block to follow, default is "you" or "-") • lock mode (when enabled, the camera parameters are retained indefinitely until lock is disabled. Normally, the camera parameters reset to defaults when the current script ends)
checkpoint	x='#' y='#' z='#' level='N' This used to change the player's checkpoint (restart) position. It does not have to correspond to any checkpoint block. It is recommended that you specify x, y, and z together (level is outdated).
die	This will trigger a player death, but not the zone's death script. If desired, you can give the death script a unique id and call it just like a sub script.
endspeedrun	level='N' '+N' '-N' This will officially finish the current speedrun if its "level" is equal to, greater than, or less than N (default 1). This has no effect outside of speedruns.
explode	vel='#' num='N' at='$' x='#' y='#' z='#' grav='#' w='#' h='#' color='RGB' trans='#' priority='N' This will generate a number (num, default 8) of dynamic scenic blocks at the given coordinates or the current location of the block specified by at oname. They will shoot in random directions with initial velocity vel (0 to 15) and they will fall with gravity factor grav (default 1.0). The width, height, color, transparency, and priority are optional (w and h should be specified).
lock unlock	z='#,#,.' levels='N,N,.' Lock or unlock the zone levels specified by either z-depth or numeric index. (A "locked" level means the player cannot leap to it.)
pause	color='RGB' Change the background color of the pause menu. (It is best to keep it bright, near white.)
reloadzone	entrance='$' Reload the current zone, from the most recent (or the specified) entrance.
savegame	Save your game progress including all GFlags (this is done automatically when you exit the game). This command is useful when the player reaches important points in the game, to backup his/her progress in case the game crashes or something else goes wrong.
set	entrance='$' restart='#,#' '#,#,#' frozen='0/1' nojumps='0/1' zint='N' '+N' '-N' quit='$' '$:$' timer='0/1' credits='#' '#,#' '#,#,#' trans='#' oname='$,$,...' This will set various gameplay properties: • entrance (sets the player's restart point to the specified entrance) • restart (sets the player's restart point to the specified (x,y) or (x,y,z) coordinates) • frozen mode (when enabled, the player cannot move at all, even outside of scripts) • nojumps mode (when enabled, the player can move but cannot jump or leap) • zint (set the Zone Integer to a specific number, add N to it, or subtract N from it) • quit (set which zone and entrance to restart at, if the player quits and re-opens the game) • timer (enable/disable the game timer; should only be disabled to lock in the time at the end of a speedrun that has more scripting to finish up) • credits (enters credits mode, which automatically scrolls all on-screen titles vertically; one to three values must be specified: height to be scrolled (1.0 = one screen height), normal scroll speed, and fast scroll speed when Enter/Space are pressed) • trans (block transparency between 0.0 and 1.0; at least one oname must be specified)
setcheck	oname='$' restart='0/1' This will activate the specified checkpoint block. Note: it will not change the player's reset point to the block's position unless restart is set to 1.
setgflags unsetgflags	gflags='N,N,...' These will set or unset the specified GFlags. (GFlags are saved until the player starts a new game.)
setzflags unsetzflags	zflags='N,N,...' These will set or unset the specified ZFlags. (ZFlags are reset whenever the zone changes.)
setzone	color='RGB' level='N' Change the zone background color of either the z-level the player is current at, or the z-level specified by its numeric index.
toggle on off	gflag='N' zflag='N' This will toggle the specified GFlag or ZFlag. You can also specify sub-scripts between on tags and off tags. The appropriate one will be triggered depending on the updated state of the flag.
unlockspeedrun	name='$' This will unlock the specified speedrun (and speedrun mode), if it has not been unlocked yet.
warp	zone='$' entrance='$' silent='0/1' This will warp the player to the specified zone and optional entrance. The silent option can be specified to trigger a seamless warp from an area to an entrance (see the entrance page for more information).

Object Commands
cycle	oname='$,$,...' count='N' freq='#' x='#' y='#' Changes the behavior of cyclic/motion blocks. Also a shorter way to combine setcount and setfreq. • oname - block names, required • count - change cyclic count ("-1" = no limit) • freq - change frequency (cycles per second) • x y - change the maximum x and/or y coordinate (minimum will be set to block's current position)
drop	oname='$,$,...' This will make blocks dynamic and immediately apply gravity to them.
effect	type='$' oname='$' secs='#' frames='N' This will apply a visual effect to the specified block (or the block attached to the script). The only effect currently supported is "flash". A time can be specified, otherwise it will continue until you stop it. Note: if "flash" and a time are specified, then after the timeout, the block will remain visible - unless its killed flag is set, then it will remain invisible.
flipcolor	oname='$,$,...' This will swap blocks' Color 1 and Color 2 properties.
hide unhide	oname='$,$,...' These will hide or unhide the specified blocks. This is a shorter way to write (un)setflags invisible.
kill slay	oname='$,$,...' This will hide and deactivate the specified or script-attached block. Kill is silent, while slay will play the death sound effect and trigger the block's die script.
look	oname='$' dir='-1/0/1' at='$' This will change where a block (with a face) is looking. You can specify dir to look left, center, or right, or at to look at another block (enter its oname).
move	oname='$' x='#' to='$' xv='#' impulse='1' yv='#' jump='#' leap='N' '+N' '-N' This is used to script movement of a dynamic block: • x specifies a target x-coordinate, and xv specifies speed. Alternately, to can be used to specify a target block to move toward. • impulse can be specified, then the block's velocity will instantly be set to xv and/or yv • jump will make the block jump with the specified velocity, such as 10.0, if it is standing • leap will make the block leap to z-level N, or out by N levels, or in by N levels
setcolor	oname='$,$,...' color='RGB' 'RGB,RGB' Changes the Color (or Colors) of the specified blocks. Color should either be in RRGGBB format, or the special case "-1" which is "only eyes are visible".
setcount	count='#' oname='$,$,...' Changes the count property of the specified cyclic blocks. Also resets their phase to 0°.
setflags unsetflags	flg='$,$,...' oname='$,$,...' Sets or unsets flags of the specified blocks. This is perhaps the most useful command for scripting block events. A description of valid flag names is given on the Blocks page. Also valid is the "killed" flag - which is automatically set when a dynamic block dies, but can be unset to keep it alive.
setfreq	oname='$,$,...' freq='#' fall='#' Changes the frequency of cyclic blocks. Usually you specify freq (in cycles per second), but fall is specified for proximity blocks (in distance per frame). A value of "0" will halt the block until further change.
setgrav	grav='#' oname='$,$,...' Changes the gravity of dynamic blocks, proportional to the default gravity (1.0 = default, 0.5 = half gravity). If no oname is specified, it will apply to all dynamic blocks in the zone.
shift	oname='$,$,...' abs='0/1' x='#' y='#' z='#' This will move the specified blocks by either a relative offset (abs = 0) or to an absolute location (abs = 1). • relative: x and y are optional, z has no effect • absolute: x and y are required, z is optional
swaplims	oname='$,$,...' This will swap the minimum and maximum x/y limits of the specified blocks.
minpos	oname='$,$,...' x='0/1' y='0/1' This will reset the minimum x and/or y limit of the specified blocks to their current coordinates. The maximum limits are not changed.
unscript	oname='$' Clears any standon or die scripts attached to the specified block (or the active block, if this is called from one of its own scripts).
you	color='RGB' 'RGB,RGB' Sets the player block color(s). This is a shorter way to write setcolor with oname set to "you".

Graphics Commands
cleartitles	This will clear all titles from the screen.
hidewb	text='$' state='0/1' This hides or unhides the wordbox specified by its text (0 is visible, 1 is hidden).
screen	flash='RGB' gray='1' invert='1' fade='#' shake='#' '#,#' swish='#' bg='RGB' halt='0/1' static='1' hom='0/1' Various screen effects: • flash (briefly flash the background a certain color) • gray (make everything grayscale - no easy undo!) • invert (invert everything's color - repeat to undo) • fade (fade everything toward black, by the specified factor, such as 0.9 - no easy undo!) • shake (shake the screen - either a constant amount, or an amount and a specified fade factor) • swish (a wavy screen effect, strength from 0 to 10) • bg (temporarily change the z-level's background color - resets if the player leaps away and back) • halt (when enabled, nothing but titles are drawn) • static (freezes everything, including dynamic and motion blocks - no easy undo!) • hom (enables the "hall of mirrors" effect)
srt	y='#' This changes the vertical position of the "speedrun timer", if in speedrun mode. Useful if you find the timer obstructs an important part of the screen. Use "-" or "0.8" for the default position.
title	text='$' x='#' y='#' '+#' h='#' color='RGB' alpha='#' '#,#' '#,#,#' cen='0/1' tname='$' This will create a title, a piece of text whose position and size are fixed on the screen. The following properties may be specified: • text (the displayed text) • x (screen x coordinate, typically 0.0 to 1.0) • y (screen y coordinate, typically 0.0 to 1.0, or you can prepend it with + to specify a distance below the most recently created title - makes credits easier) • h (text height, as a screen fraction, such as 0.1) • color (color of the text) • alpha (0.0 is fully transparent, 1.0 is fully opaque - title alpha can be specified in three ways: a single value, a target value and fade speed, or a starting value and target value and fade speed) • cen (center the text or not, default = 1) • tname (if a unique tname is specified at creation, you can call title again later with the same tname to modify an existing title's properties)
wordbox	text='$' x='#' y='#' z='#' size='#' color='RGB' back='RGB' oname='$' flg='$,$,...' This will create a wordbox, a piece of text whose position and size are fixed in the game world. • text (the displayed text - must be unique! - use '~' for a random garbage character) • x y z (position, in game coordinates) • size (text height, in game coordinates) • color (text color, in RGB) • back (background color, RGB or "-1") • oname (if a valid block is specified, the wordbox will "attach" to it) • flg (wordbox flags: "disappearing" means it will disappear when it moves off-screen, "invisible" means it is hidden by default)

Audio Commands
beat	bpm='N' dels='#' delb='#' sub='$' This allows you to synchronize the contained script (or a sub script) to the music. Specify the beats per minute (bpm) of the music, and it will automatically trigger the script on every beat. You can also specify a starting delay in seconds (dels) or beats (delb) before the script will begin to trigger. (The scripts, along with any starting delay, will repeat when the music loops!) Warning: Because beat scripts are continously being triggered, they should not contain any "blocking" commands (freeze, wait, prompt, etc.), only instant commands like sound effects or graphical changes.
killbeats	This will cancel any active beat scripts.
music	track='$' vol='N' fast='0/1' Plays a music track (ogg format) specified by file path, relative to the game file. Volume is optional (default 100) and fast may be set to start full volume instantly (normally the track will fade in slightly). You can stop the current music by specifying track="-".
sound	num='N,N,...' vol='N' Plays one or more sound effects specified by numeric index (see list here). Volume is optional, 0 to 100 (the default volume varies with each sound effect).

Index · Play Nugget · grudlux.com