Game Start/End/Quit
*definelabel denoting the start of the definition block
*startlabel denoting the start of the program block
gameend definition block and execute game
resetreset game
defineresetforce total script reset
endend game and close window
Syntax Markers
*prefix for labels
;prefix for comments
:write and execute multiple commands on a line
%prefix for numeric variables
$prefix for character variables
?prefix for array variables
~destination point for jumpf/jumpb
/ignore linefeed
{}set variables within a text block
`enter single-byte text mode
0xprovide a numeric literal in hexadecimal format
^enter ponscripter text mode
Text Window
setwindowset up text window and character display attributes
setwindow2modify text window appearance
textoffhide text window
textonshow text window
windoweffectspecify an effect for the text window
erasetextwindowtoggle text display during effect runtime
btnnowindowerasetext window won't be removed while buttons are in effect
noterasemanpeople won't be erased when the text window is removed
gettextretrieve the contents of the text window
tateyokotoggle text display during effect runtime
windowchipshow the specified sprite whenever the text window is displayed
setwindow3same as setwindow, but doesn't clear Log buffer
textspeeddefaultchange to default text display speed
fontchange the text display font
Text Display
defaultfontspecify default font
!sset the character display speed
#change character color
textclearclear displayed text
locatechange the position of character output within the text window
puttextoutput a short bit of text (like after an if statement)
brinsert a carriage return into the displayed text
textspeedchange text display speed
shadedistancespecify the text shadow offset
setkinsokuset forbidden start/end characters for Japanese
addkinsokuadd forbidden start/end characters for Japanese
kinsokutoggle enforcement of forbidden Japanese start/end chars
englishuse NScripter English mode
textcolorchange the color for text output
languageset preferred text language
Click Wait
@enter click wait state
\enter new-page wait state
clickstrenter click wait state upon hitting any of the specified chars
linepagewait for click at the end of a line
_ignore the following click
clickvoiceplay a specified sound when a click occurs
autoclickwait for click at the end of a line
clickenter click wait state without displaying the click wait cursor
lrclickwait for either a left or right click
clickskippageskip to the new page clickwait upon click
Cursor
setcursorset graphic file and relative position for click wait cursor
abssetcursorset absolute position and graphic file for click wait cursor
mousecursorspecify file for general mouse cursor
mousemodetoggle mouse cursor display
movemousecursormove the mouse to a particular position on the screen
getnextlineget the text window coordinates of the start of the following line
Image Display
transmodechange alpha blend transparency mode
underlineset ground line for standing images
bgaliaset parameters for a nonstandard background
humanzdesignate overlap priority for sprites and standing images
windowbackinsert text window at the same overlap level as standing image(s)
bgset background image
ldset standing image
clerase specified standing image
talmodify standing image opacity
printdisplay images while removing those that should be hidden
lspload sprite into memory
lsphload sprite into memory (hidden)
cspdelete sprite from memory
vsptoggle display of a loaded sprite
spstrexecute the given control string for complex-button sprite display
mspchange sprite position (relative)
amspchange sprite position (absolute)
cellmanually designate the cell of a sprite
bltblit image onto screen instantaneously
ofscpytransfer an image drawn by blt to the offscreen buffer
repaintredraw screen
allsphidehide all sprites at the same time
allspresumeredisplay sprites hidden with allsphide
humanorderset priority levels for standing image positions
humanposset coordinates for standing image positions
bgcopycopy current screen to the background
getspsizereturn the sprite's size
getspmodereturn whether the given sprite is displayed
spfontset the font used for string sprites
strspcreate and display a sprite of a multi-line character string
strsphcreate a sprite of a multi-line character string, hidden
Visual Effects
effectdesignate an effect
effectblankdesignate wait duration after an effect is over
effectcuttoggle effect runtime during "skip to next choice" mode
effectskipspecify whether effects can be skipped
quakecause a shaking screen effect
quakexcause a horizontal shaking effect
quakeycause a vertical shaking effect
monocromake screen monochrome/color-toned
negaset negative screen display
flushoutexecute flushout effect
Character/Number/Bar Display
%display contents of numeric variable
$display contents of string variable
?display contents of array variable
barcreate and display a (graph) bar
barclearclear bar display
prnuminitialize a numeric label
prnumclearclear numeric labels
Music/SFX Playback
cdfadeoutspecify duration of CD-DA fade-out
chkcdfiledetermine if CD drive contains a file called "filename"
chkcdfile_exdetermine if CD drive contains a file called "filename"
mp3fadeoutspecify duration of BGM fade-out
playplay specified CD-DA track or MIDI file in a loop
playonceplay specified CD-DA track or MIDI file only once
playstopstop playback of CD track or MIDI file
waveplay a WAV file only once
wavelooploop WAV file playback
wavestopstop WAV file playback
mp3play compressed music file only once
mp3loopplay compressed music file in a loop
mp3saveif game saved during playback, resume playing upon reload
dsounddeclare that you are using DirectSound (unnecessary in latest versions)
dwaveplay WAV file using DirectSound only once
dwavelooploop-play a WAV file using DirectSound
dwavestopstop DirectSound WAV file playback
dwaveloadload WAV file into memory
dwaveplayplay a preloaded WAV file only once
dwaveplaylooploop-play a preloaded WAV file
stopstop all music playback
mp3stopstop playback of compressed music
mp3fadeinspecify duration of BGM fade-in
bgmplay compressed music file in a loop
bgmonceplay compressed music file only once
bgmstopstop playback of compressed music
bgmfadeoutspecify duration of BGM fade-out
bgmfadeinspecify duration of BGM fade-in
loopbgmplay intro, then loop repeatedly
loopbgmstopstop playback of loopbgm
mp3volchange BGM sound volume
chvolchange sound volume of the given dwave channel
voicevolchange voice sound volume
sevolchange SFX sound volume
bgmvolchange BGM sound volume
vvoice playback, shorthand cmd (wave)
dvvoice playback, shorthand cmd (dwave)
mvplayback an mp3 voice file
bgmdownmodetoggle turning down BGM volume when voices are played
Movie Playback
aviplayback an AVI file
mpegplayplayback an MPEG movie
movieplay a movie
Choices
selectcolordesignate the text colors for choices
selectvoicedesignate sound(s) to play during choice selection
selectcreate a choice
selgosubcreate a choice that jumps to a subroutine
selnumcreate a choice that returns a number based on selection
Jumps
gotojump to designated label
skipskip the next n lines of script
gosubcall a subroutine
returnreturn from a subroutine
jumpfjump forward to the next ~ symbol
jumpbjump back to the previous ~ symbol
tablegotojump to a label in the table based on the numeric value
Click Traps
trapjump to specified label on left click
r_trapjump to specified label on right click
lr_trapjump to specified label on left or right click
trap2jump to label on left click when "skip to next choice" mode is set
lr_trap2jump to label on left or right click when "skip to next choice" mode is set
Image Buttons
btndefload image file into button memory buffer
btninitialize image as button (method 1)
btnwaitdisplay image button and enter a click-wait state (method 1)
btnwait2display image button and enter a click-wait state (method 2)
spbtndesignate a sprite as an image button
cellcheckspbtndesignate a sprite as a button only if the sprite has at least 2 cells
getbtntimeracquire how much time passed during btnwait
btntimeset a time limit for image button functionality
btntime2same as btntime, but waits for voice to finish
exbtncreate a complex button
cellcheckexbtncreate a complex button only if the sprite has at least 2 cells
exbtn_dspecify default behavior for when complex buttons are used
transbtnignore transparent areas when creating a button from an image
Wait/Timer
!dwait for the specified time
!wwait for the specified time, ignoring clicks
delaycause a time delay (method 1)
waitcause a time delay (method 2)
resettimerreset the internal timer
waittimerwait until the internal timer reaches the specified time value
gettimerget the value of the internal timer
spwaitwait until the designated sprite's animation has ended
Variable Manipulation/Calculations
straliascreate an alias for a filename or character string
numaliascreate an alias for a numeric value
intlimitset the allowed range for a numeric variable
dimdeclare an array variable
movload a numeric/string variable with a value
mov3load numeric values into 3 consecutive variables
mov4load numeric values into 4 consecutive variables
mov5load numeric values into 5 consecutive variables
mov6load numeric values into 6 consecutive variables
mov7load numeric values into 7 consecutive variables
mov8load numeric values into 8 consecutive variables
mov9load numeric values into 9 consecutive variables
mov10load numeric values into 10 consecutive variables
movlload a line of numbers into an array
addadd/concatenate to variable
+do addition/concatenation
subsubtract a number from a variable
-do subtraction
incincrement a variable
decdecrement a variable
mulmultiply variable by a number
*do multiplication
divdivide variable by a number
/do division
modget the remainder (modulo)
rndgenerate a random number (method 1)
rnd2generate a random number (method 2)
itoaconvert a numeric value into a string
itoa2convert a numeric value into a fullwidth character string
atoiconvert a string into a numeric
lenfind the length of a character string
midget a substring of the given character string
splitsplit a character string using the given delimiter
sinfind the sine of the given angle
cosfind the cosine of the given angle
tanfind the tangent of the given angle
Conditionals/Loops
ifevaluate if a condition is true
notifevaluate if a condition is false
cmpcompare character strings
fchkcheck whether or not a image file has been loaded (and tagged)
lchkcheck whether or not a label has been accessed
forloop instruction
nextend a loop
breakbreak out of a for loop
Right-Click Functionality
rmenuinitialize menu to display upon right-click
menusetwindowinitialize window for right-click menu
savenamespecify names to use for savefiles in right-click menu
menuselectcolordesignate the text colors for choices
menuselectvoicespecify right-click menu system sounds
rlookbackjump to Log Mode upon right-click
rgosubset a routine to call upon right-click
roffignore right-clicks
rmodetoggle availability of right-click menu
Log Mode
lookbackbuttonspecify button images for Log Mode
lookbackcolordesignate text color for Log Mode
lookbackvoiceplay a sound when paging through Log Mode
lookbackspuse sprites instead of the default Log Mode buttons
maxkaisoupageset maximum number of pages to store for Log Mode
lookbackflushclear Log Mode buffer
lookbackoffstop accumulating Log Mode data
lookbackonbegin accumulating Log Mode data
Skip Mode
kidokuskipenable 'stop at unread' in Skip Mode
mode_wave_demoplay WAV files even during Skip Mode
skipoffturn off Skip Mode
kidokumodetoggle Skip Mode's 'stop at unread' setting
File Access Logs/Global Variables
filelogenable file access logging
globalonenable use of global variables
labellogenable label access logging
Save/Load
savenumberset the maximum number of saves allowed
savedirstore save data in the designated folder
loadgameload game from the designated savefile
savegamesave game in the designated savefile
savegame2store a particular character string along with the savefile
getsavestrretrieve the string stored with a savefile using savegame2
savefileexistcheck whether or not a savefile exists
saveonturn on Save Mode
saveoffturn off Save Mode
loadgosubset a routine to call immediately after loading a game
errorsaveautomatically save game status in savefile 999 when an error occurs
autosaveoffdisable (most) automatic save points
savepointupdate the save point
Miscellaneous
mesboxcreate a message box
okcancelboxcreate an OK/Cancel dialog box
yesnoboxcreate a Yes/No dialog box
inputstrwait for player to give character input (method 1)
inputnumwait for player to give numeric input
inputwait for player to give character input (method 2)
textfieldcreate a text input window
clickposretrieve the cursor coordinates at the last click
systemcallperform a function as though called from the right-click menu
fileexistcheck whether or not a file exists
fileremovedelete a file
labelexistcheck whether or not a label exists
noloaderrordon't generate an error when an image or sound can't be loaded
minimizewindowminimize the game window
Special Mode Settings
automodeallow use of Auto Mode
automode_timespecify delay time in Auto Mode when sounds aren't being played
defvoicevolset default volume for voices (dwave channel 0)
defsevolset default volume for SFX
defmp3volset default volume for mp3 files (BGM channel)
defbgmvolset default volume for BGM channel
mode_sayause special mode created for "Saya ~Labyrinth of Immorality~"
mode_extallow use of Auto Mode created for "Gin'iro"
mode800set screen size to 800x600
mode400set screen size to 400x300
mode320set screen size to 320x240
valuechange the starting number for global variables
gameidgive a name to use for an ONScr game save folder
Plugins/Archives
soundpressplginload compressed audio functionality via plugin/dll (can just use DirectSound instead)
spiload compressed image functionality via plugin/dll
arcuse specified archive
nsaenable NSA archive access
nsadirdesignate folder where NSA archives are located
addnsadiradd a directory to check for NSA archives
exec_dllcall a DLL
getretretrieve value returned from a DLL
setlayercreate a layer
layermessagesend a message to a layer
Console
versionstrchange the version information
captionchange the game window title
Data Acquisition
dateretrieve the current year, month and date
timeretrieve the current hour, minute and second
savetimeretrieve the date and time of the given savefile
getversionget the version number of the current NScripter build
getwindowsizeget the area of the window client
getregread from the registry
getiniread from an ini file
readfileread file contents into a string variable
Window Menubar
killmenuerase a menubar item
resetmenuclear menubar for definition of a custom menu
insertmenuadd a menubar menu option
deletemenuremove the Windows menubar from NScripter
defaultspeeddesignate text display speeds selectable via the menubar
!sduse a text display speed provided via defaultspeed
menu_fullenter fullscreen mode
menu_windowenter windowed mode
isfullretrieve whether or not fullscreen mode is active
menu_click_pageenter single-page text display mode
menu_click_defenter default text display mode
menu_dwavvoldisplay the volume setting dialog window
menu_waveonenable main volume
menu_waveoffdisable (mute) main volume
System Customization
*customsela label that interacts with the csel command
cselgive choices to present via system customization
cselbtncreate custom buttons for choice text
cselgotojump to a label created by csel
getcselnumget the total number of csel choices
getcselstrget the character string of a csel choice
nextcselreturns whether or not the next command is csel
selectbtnwaitenter click wait state within a *customsel
textgosubdefine a label for handling system customization during click wait states
textbtnwaitenter click wait state within a custom wait routine
getskipoffretrieve skipoff keystrokes at textbtnwait
getmouseoverreturn on mouseover of buttons at a button wait
checkkeycheck for a specified keypress
texecremove text for a page-wait condition
texec2remove text for a page-wait condition (method 2)
getcursorposget current position of text cursor
getcursorpos2get top-left pixel coordinates of the last text character
isskipget current progress mode
ispageretrieve whether or not in a new page clickwait
defsubcreate a user-defined command name
getparamretrieve the parameters given to a user-defined command
luacallreplace default NScripter functionality with a Lua callback
luasubcreate a user-defined instruction that calls a Lua function
Screenshot
getscreenshotgrab a screenshot
savescreenshotsave a screenshot image
savescreenshot2save a screenshot image
deletescreenshotremove a screenshot image from memory
Button Extensions
btnareaset an area for detecting mouse cursor entry
btndownset to return from button command while mouse button is pressed
isdownreturn whether or not the mouse button is pressed
getmouseposretrieve mouse cursor position
spclclkset the Spacebar to work the same as a left-click
usewheelhave button commands detect mouse wheel movement
useescspchave button commands detect Esc and Spacebar keypresses
getcursorhave button commands detect left/right/up/down arrow keys
getenterhave button commands detect Enter key
gettabhave button commands detect Tab key
getfunctionhave button commands detect Function keys
getpagehave button commands detect PageUp/PageDown keys
getinserthave button commands detect Insert key
getzxchave button commands detect Z/X/C keys
getmclickdetect middle-button mouse clicks
Ruby Text
()produce ruby text
rubyoffturn off ruby mode
rubyonenter ruby mode
rubyon2enter this ruby mode only when ruby text appears
Demo Draw Commands
drawsend images created via demo draw commands to the screen
drawclearpaint the screen black
drawfillpaint over the screen with a specific color
drawbgdraw the background to the screen
drawbg2draw the background to the screen in a special manner
drawtextdraw the text window
drawspdraw a sprite
drawsp2draw a sprite (scaled and rotated)
drawsp3draw a sprite with linear transformation
Log Mode Customization
checkpagecheck whether a backlog page is available
getlogget the character string for a backlog page
logspcreate a sprite from backlog text
logsp2create a sprite from backlog text with custom text size
getlogtextget the character string for a backlog page (for use with strsp)
gettaglogget the last pretext tag of a backlog page
texthidehide text while leaving the text window visible
textshowreshow text hidden with texthide
Pretext Tags
pretextgosubset a routine to jump to just before text display
[]specify tag data available to a pretextgosub routine
gettaguse within a pretextgosub routine to get tag data
indentwhen linebreaking, indent the next line by the given amount
pagetagonly process pretext tags at the start of a page
zenkakkoallow use of 【】 as pretext tag brackets
Development Support
bmpcutsplit a BMP file into multiple pieces while preserving the original
bw2agenerate an NScripter alpha image
bw2a3generate an NScripter alpha image
chainbmpglue image files together
createdummycreate a dummy image file
debugloglog debug messages
External Command Execution
shellopens an external program, file, or URL via Explorer
winexecexecute an external program
CSV File Manipulation
csvopenopen a CSV file
csvreadread data from an open CSV file
csvwritewrite data to an open CSV file
csveofdetect whether or not at the end of an open CSV file
csvcloseclose an open CSV file
Text Buttons
<>set a text button
linkcolorset textbutton colors
textbtnstartspecify starting number for unnumbered textbuttons
gettextbtnstrretrieve the text of a particular textbutton
erasetextbtnclear a pressed textbutton
textexbtncreate a complex textbutton (similar to exbtn)
textbtnoffinactivate textbuttons
Extended Sprites
lsp2load an extended sprite into memory
lsph2load an extended sprite into memory (hidden)
lsp2addload an extended sprite using additive composition
lsph2addload an extended sprite using additive composition (hidden)
lsp2subload an extended sprite using subtractive composition
lsph2subload an extended sprite using subtractive composition (hidden)
csp2delete extended sprite from memory
vsp2toggle display of a loaded extended sprite
msp2change extended sprite position (relative)
amsp2change extended sprite position (absolute)
allsp2hidehide all extended sprites at the same time
allsp2resumeredisplay extended sprites hidden with allsp2hide
New Button Processing
bclearclear button definitions
bspcreate a button from a sprite
bdefspecify behavior for when no sprite button is moused over
btimespecify button processing timeout duration
bexecexecute button processing
bcursorreturn cursor key input during button processing
bdownreturn from button processing while button is pressed
btransignore transparent areas during button processing
PONScripter Commands
~set a ponscripter formatting tag region
pmapfontmap a font file to a ponscripter font slot
prenderingconfigure ponscripter text rendering
pfontstyleset the default font style
pligateadd or remove a ligature or shortcut sequence
pindentstrspecify characters that cause indents
pbreakstrspecify characters that allow linebreaks
localestringlocalize a right-click menu message string
h_mapfontmap a font file to a ponscripter font slot
h_renderingconfigure ponscripter text rendering
h_fontstyleset the default font style
h_ligateadd or remove a ligature or shortcut sequence
h_indentstrspecify characters that cause indents
h_breakstrspecify characters that allow linebreaks

[Definition/Program Block]( NScr2.10, ONScr, ONScr-EN, PONS )
-

Variable Manipulation/Calculations

NUM'-'NUM

NUMNumeric value to be subtracted from
NUMNumeric value to subtract

Builds an expression, where the second number is subtracted from the first number.
The expression result is used as a numeric argument for a command.


sub /
page top / list / main

[Special Text Command]( NScr, ONScr, ONScr-EN, PONS )
!d

Wait/Timer

!dNUM

NUMAmount of time to wait (msec)

Waits for the specified number of milliseconds, then continues. This state can be canceled with a click.
The given number must be a normal number, not a variable - if you want to use a variable, please use the delay command.


delay /
page top / list / main

[Special Text Command]( NScr, ONScr, ONScr-EN, PONS )
!s

Text Display

!sNUM

NUMCharacter display speed (msec)

Changes the speed of text display (in milliseconds).
The number must be a normal number, not a numeric variable. To use a variable, try the textspeed command instead.


textspeed /
page top / list / main

[Special Text Command]( NScr, ONScr, ONScr-EN, PONS )
!sd

Window Menubar

!sd

Sets text display to the current default speed. You may set the three possible default speeds with the defaultspeed command.


defaultspeed /
page top / list / main

[Special Text Command]( NScr, ONScr, ONScr-EN, PONS )
!w

Wait/Timer

!wNUM

NUMAmount of time to wait (msec)

Waits for the specified number of milliseconds, then continues. This state cannot be canceled with a click.
The given number must be a normal number, not a variable - if you want to use a variable, please use the wait command.


wait /
page top / list / main

[Special Text Command]( NScr, ONScr, ONScr-EN, PONS )
#

Text Display

#rrggbb

Changes the color of the text, using HTML hexadecimal color codes (e.g. #000000 for black, #ffffff for white, and #ffffaa for pale yellow).
Please note that it only changes the color of text displayed after this command, and not any of the text that came before.


page top / list / main

[Reserved Syntax]( NScr, ONScr, ONScr-EN, PONS )
$

Syntax Markers

'$'NUM

NUMVariable number (0 - 4095)

Works much as for numeric variables -- like the general vs. global designation -- except for character strings.
The default value for character variables is "".

*
The starting global variable value can be adjusted with the value directive. (by Mion)

% / globalon / value /
page top / list / main

[Special Text Command]( NScr, ONScr, ONScr-EN, PONS )
$

Character/Number/Bar Display

$NUM

NUMString variable number

Tag for character string variables. Use this to access their contents within text.


% /
page top / list / main

[Reserved Syntax]( NScr, ONScr, ONScr-EN, PONS )
%

Syntax Markers

'%'NUM

NUMVariable number (0 - 4095)

Numeric variables can range from %0 to %4095 -- 4096 total.
0 to 199 are general variables, while 200 and above are globals.
General variables are reinitialized upon game restart, reset, and such, while global variables retain their values.
In other words, general variables are saved and loaded on savetime and loadtime, but global variables remain constant throughout.
Therefore, it's best to use general variables when doing math, and to use global variables for things like stage-clear flags, etc.
To use global variables, you'll have to specify the command globalon in the definition block.

The default value of a numeric variable is 0.

*
The starting global variable value can be adjusted with the value directive. (by Mion)

$ / globalon / value /
page top / list / main

[Special Text Command]( NScr, ONScr, ONScr-EN, PONS )
%

Character/Number/Bar Display

%NUM

NUMNumeric variable number

Tag for numeric variables. Use this to access their contents within text.


$ /
page top / list / main

[Special Text Command]( NScr2.03, ONScr, ONScr-EN )
()

Ruby Text

'('STR'/'STR')'

STRMain text to show ruby text above
STRRuby text (displayed smaller, spread above main text)

This text command produces ruby text, often used for furigana (Japanese phonetic characters that show the pronunciation of a kanji phrase).

Example:
Sample script using ruby text
*define
rubyon
game
*start
setwindow 10,10,20,20,24,24,0,12,0,1,1,#ffffff,0,0,639,479
ルビ機能の(暫定仕様/ざんていしよう)です。@
rubyon時、(文字/もじ)は(下詰/したづめ)で表示されます。@
(縦/たて)の(字間/じかん)を、ルビが入る分とって下さい。@
「(承/うけたまわ)」る、とか、「(論理的/ロジカル)」みたいに、文字幅をあわせようとする機能がついてます。
ルビは折り返し改行されませんのでご注意ください。\
end
ONScripter Example:
Ruby text example with ONScripter (note the '(', '/', and ')' must be outside single-byte mode).
*define
rubyon
game
*start
setwindow 10,10,20,20,24,24,0,12,0,1,1,#ffffff,0,0,639,479
`This is a script that displays ruby text.@
`You can use it with Japanese examples, `(文字/もじ)`, for example.@
br
`In ONScripter-EN you can even do things like `(文字/moji)` or `(`DREADFUL`/horrible)`, if not very well.@
`Be sure to use vertical spacing or insert a blank line above rubied text, so that the ruby doesn't overlap earlier lines.\
end

rubyoff / rubyon /
page top / list / main

[Reserved Syntax]( NScr, ONScr, ONScr-EN, PONS )
*

Syntax Markers

'*'NAME

NAMELabel name

Creates a label with the given name. You can use statements like goto to jump to this label.
The name may contain numbers (except in the first position), single-byte characters, and underscores, but nothing else.

OK:
*HAJIMARI
*Mike_Tom
*day01

NOT OK:
*始まり (uses double-byte chars)
*Mike&Tom (uses ampersand)
*01day (starts with a number)

*
Hyphens aren't allowed; use underscores instead.
Since names are case insensitive, "*HAJIMARI" and "*hajimari" are considered to be the same. (by senzogawa)
Example:
*asterisk

gosub / goto /
page top / list / main

[Definition/Program Block]( NScr2.10, ONScr, ONScr-EN, PONS )
*

Variable Manipulation/Calculations

NUM'*'NUM

NUMNumeric value to multiply
NUMNumeric value to multiply

Builds an expression, where the first number is multiplied by the second number.
The expression result is used as a numeric argument for a command.


mul /
page top / list / main

[Reserved Syntax]( NScr, ONScr, ONScr-EN, PONS )
*customsel

System Customization

*customsel

Jumps to this label whenever a csel command is executed.
Code for handling a custom select display follows this label.

Example:
This defines handling routines for csel.
*customsel
skipoff
*csel_st
btndef clear
getcselnum %0
getcursorpos %1,%2
cselbtn 0,500,%1,%2
add %2,21
cselbtn 1,501,%1,%2
if %0>2 add %2,21:cselbtn 2,502,%1,%2
if %0>3 add %2,21:cselbtn 3,503,%1,%2
if %0>4 add %2,21:cselbtn 4,504,%1,%2

*csel_loop
selectbtnwait %0
if %0=-2 systemcall lookback:goto *csel_loop
if %0=-1 gosub *rclk:goto *csel_st
if %0>=500 & %0<=504 saveon:sub %0,500:cselgoto %0
goto *csel_loop

csel / cselbtn / cselgoto / getcselnum / getcselstr / selectbtnwait /
page top / list / main

[Reserved Syntax]( NScr, ONScr, ONScr-EN, PONS )
*define

Game Start/End/Quit

*define

A special label that denotes the start of the definition block.

Example:
A definition block that does nothing
*define
game

definereset / game /
page top / list / main

[Reserved Syntax]( NScr, ONScr, ONScr-EN, PONS )
*start

Game Start/End/Quit

*start

This label denotes the start of the program block proper.

Example:
A program block that does nothing
*start
end

game /
page top / list / main

[Special Text Command]( NScr, ONScr, ONScr-EN, PONS )
/

Syntax Markers

/

If you write a newline directly after this slash, then the newline will be ignored.


jumpb / jumpf /
page top / list / main

[Definition/Program Block]( NScr2.10, ONScr, ONScr-EN, PONS )
/

Variable Manipulation/Calculations

NUM'/'NUM

NUMNumeric value to divide
NUMNumeric value to use as divisor

Builds an expression, where the first number is divided by the second number.
The expression result is used as a numeric argument for a command.


div /
page top / list / main

[Reserved Syntax]( NScr, ONScr, ONScr-EN, PONS )
:

Syntax Markers

SENTENCE ':' SENTENCE

You can use colons in place of carriage returns to separate out distinct commands.
These are most often used in if statements, e.g.
if CONDITION command1:command2:command3 ...

Example:
On a right-click, hide sprites and then enter Log Mode
btnwait %0
if %0=-1 allsphide:systemcall lookback

page top / list / main

[Reserved Syntax]( NScr, ONScr, ONScr-EN, PONS )
;

Syntax Markers

;

A command that starts with ';' is a comment - Nscr will skip these.

Example:
defsub abs ; This is just a comment.

page top / list / main

[Reserved Syntax]( NScr, ONScr, ONScr-EN, PONS )
?

Syntax Markers

'?'NUM

NUMArray number (0 - 199)

An array variable, declared via the dim command.
They may range from ?0 to ?199 -- 200 in total.
Arrays may not be used as global variables.


dim /
page top / list / main

[Special Text Command]( NScr1.97, ONScr, ONScr-EN, PONS )
?

Character/Number/Bar Display

?NUM

NUMArray number

Tag for array variables. Use this to access their contents within text, but note that you must reference exactly one array element within the array range(s) defined by dim.

Example:
An example of array usage in text
*define
dim ?0[10][20]
start
;populate ?0[2][5] with value 20.
mov ?0[2][5],20
;used in text
VAL=?0[2][3]@
ONScripter Example:
An example of array usage in single-byte text
`Array value = `?0[2][5]`.@

dim / % /
page top / list / main

[Special Text Command]( NScr, ONScr, ONScr-EN, PONS )
@

Click Wait

@

Enters click wait state.


\ /
page top / list / main

Ver.2.46[Special Text Command]( NScr, ONScr, ONScr-EN, PONS )
[]

Pretext Tags

'['STR']'

STRTag data elements, delimited by "/"

Specifies tag data accessible to gettag within a pretextgosub routine, called immediately before the following text is displayed.

Example:
This calls a pretextgosub routine before "「太郎の台詞」" is displayed, where gettag will extract "太郎" and "0001.wav".
[太郎/0001.wav]「太郎の台詞」
ONScripter Example:
This calls a pretextgosub routine before "Taro speaking." is displayed, where gettag will extract `Taro Mendo` and "0001.wav".
[`Taro Mendo`/0001.wav]`Taro speaking.`

gettag / pretextgosub /
page top / list / main

[Special Text Command]( NScr, ONScr, ONScr-EN, PONS )
\

Click Wait

\

Enters end-of-page wait state -- any new characters following this symbol on the same line are ignored. Once the player clicks, he is sent to the next page.


@ /
page top / list / main

[Special Text Command]( PONS )
^

Syntax Markers

^

Use this character to enter ponscripter text mode.

The following text commands work within ponscripter text mode:
@ / \ !w !s !d !sd $VAR %VAR #rrggbb

You may use '#' before any of the characters @, /, \, $, %, !, #, and _ to display the literal character, thereby preventing it from parsing as a text command.

PONScripter text mode supports ~-marked formatting tags; a literal ~ can be displayed with '~~'.

Also note that carets can be used in place of double-quotes for string arguments to commands (e.g. puttext ^Hello there^). Strings delimited in this manner are parsed like regular double-quoted strings, but with additional parsing for ~ formatting tags (e.g. ^~b~Hello~b~ there^ displays as "Hello there").


~ /
page top / list / main

[Special Text Command]( NScr1.98, ONScr, ONScr-EN, PONS )
_

Click Wait

_

If you write a click-wait char (or newline, if linepage is active) immediately after this underscore, then the wait state/page feed is ignored.

*
This command got added to NScr ver1.98, but didn't work properly until ver2.48. (by Mion)

@ / \ / clickstr / linepage /
page top / list / main

[Special Text Command]( ONScr20040909, ONScr-EN, PONS )
`

Syntax Markers

`

Use this character to enter single-byte text mode.
Japanese ONScripter must be compiled with ENABLE_1BYTE_CHAR defined to use this mode; ONScripter-EN has it available by default.

The following text commands work within single-byte mode:
@ / \ !w !s !d !sd $VAR #rrggbb

You may use '$$' to produce the character '$'. Other text commands must be outside single-byte mode to work - the backquote can work as a toggle in these cases:
`I have ` %0 ` apples.@

Also note that backquotes can be used in place of double-quotes for string arguments to commands, to have the strings be used in single-byte mode (e.g. puttext `Hello there`; otherwise, backquotes may be used within strings to toggle single-byte mode (e.g. ":s;#FF0000`Red text sprite")

*
When textgosub is defined, the clickwait @ should be toggled out of single-byte mode (e.g. `Hello.`@` This is text`@), otherwise single-byte text after the clickwait won't display correctly. (by Mion)
*
In ponscripter, this use of ` is only available in onscripter compatibility mode (i.e. when run on SJIS scripts). (by Mion)
ONScripter Example:
Example ONScripter script with commands that use single-byte mode.
*define
numalias name,0
clickstr `.?"`,2
savename `Save the scene`, `Load the scene`, "Memory "
rmenu `Save to file`,save,`Load from file`,load
game

*start
`Hi, this is a test.
`#FF0000This is another test.#FFFFFF
`_"He said so."
`_"She said so."
`Does it work??
mov $name,`Mion Sonozaki`
`Hello there $name.@ How are you?@
br
selgosub `Say "Turn to the right."`, *right, `Say "Turn to the left."`, *left, "`Do nothing.", *nothing
end 

*right
`You turned to the right.\
return

*left
`You turned to the left.\
return

*nothing
`You didn't do anything.\
return

page top / list / main

[Special Text Command]( NScr2.65, ONScr-EN )
{}

Syntax Markers

'{'$VAR|%VAR,STR|NUM[,...]'}'

VARA string or numeric variable
STRProvide a string value if VAR was a string variable
NUMProvide a numeric value if VAR was a numeric variable

This allows assigning a value to a variable from within a text block.
To do so, enclose the variable and value within parentheses.
Please note that aliases may not be used - only regular variable numbers, numeric and string values.
If multiple variable/value pairs are provided, as in { Var, Value, Var, Value }, then all the given substitutions will be executed.

*
The substitutions will be available for the next command, but not later within the same text block. (by Mion)
Example:
Sets %2 to 15 and $3 to 'テキスト' within a text command.
mov %2,4 : mov $3,"いない"
;the following text sets values
ここでは %2 $3 、@このように{%2,15,$3,テキスト}。@
ここでは %2 $3。\
ONScripter Example:
Sets %2 to 15 and $3 to 'TEXT' within a text command (using single-byte mode).
mov %2,4 : mov $3,`zilch`
;the following text sets values
`Right now we have `%2` $3,@ and want to change`{%2,15,$3,`TEXT`}` values.@
`Now we have `%2` $3.\

page top / list / main

[Reserved Syntax]( NScr, ONScr, ONScr-EN, PONS )
~

Syntax Markers

~

Tags that are targets for jumpf and jumpb.
Please do not place any display text between a jumpf/jumpb command and a ~.


jumpb / jumpf /
page top / list / main

[Special Text Command]( PONS )
~

PONScripter Commands

'~'FTAG[...]'~'

FTAGA ponscripter formatting tag value

Sets a PONScripter formatting tag region, which can contain one or more of the following formatting tag values (possibly delimited by spaces):

Font Style:
(Note that most of the tags in this section assume a font slot layout as described in the pmapfont command definition.)
cNUMselect the font in slot NUM (0-7)
dselect the default font style (same as c0)
rdisable italics (default)
itoggle italics
tdisable bold (default)
btoggle bold
fselect the 'text' face (default)
sselect the 'display' face

Text Size:
(In this section, 'base size' refers to the font size for the active window, while 'current size' refers to the current font size as specified using prior text size formatting tags.)
=NUMset the current size to exactly NUM pixels (0 will reset to the base size)
%NUMset the current size to NUM-percent of the base size
+NUMincrease the current size by NUM pixels
-NUMdecrease the current size by NUM pixels

Text Position:
xNUMset the horizontal text position to NUM pixels right of the active window's left margin
yNUMset the vertical text position to NUM pixels below the active window's top margin
x+NUMadjust the current horizontal text position NUM pixels to the right
y+NUMadjust the current vertical text position NUM pixels down
x-NUMadjust the current horizontal text position NUM pixels to the left
y-NUMadjust the current vertical text position NUM pixels up

Indentation:
nset the indent to the current horizontal position; new text lines will start from this offset until the end of the current page
ureset the indent to the left margin; note that this will only apply to later text lines, so use it at the end of the last line of an indented section
The indent is also set automatically when the first character of a page is an indenting character, as set using pindentstr.

PONScripter Example:
Displays the text "Hello there" using font style 1.
puttext ^~c1~Hello there^
PONScripter Example:
Produces a section of indented text followed by unindented text.
^Bruce: ~n~What's that you say?@
^You don't understand indenting?~u~@
br
^Rick shuffled his feet.\
PONScripter Example:
Displays the text "Heading" in italics, 120% of the base font size, 20 pixels left and 40 pixels up from the current position. The italics and font size are reset afterwards.
^~i %120 x-20 y-40~Heading~i =0~

pmapfont / pindentstr /
page top / list / main

[Definition/Program Block]( NScr2.10, ONScr, ONScr-EN, PONS )
+

Variable Manipulation/Calculations

NUM'+'NUM

NUMNumeric value to add
NUMNumeric value to add

STR'+'STR

STRCharacter string to be augmented
STRCharacter string to concatenate

Builds an expression, where the second number/string is added/concatenated to the first number/string.
This will cause an error if the arguments are not both strings or both numbers.
The expression result is used as a numeric/string argument for a command.

*
String concatenation with '+' was added in ver2.72.
Example:
Adds 1 to the value of Array 0 Element 0.
mov ?0[0],?0[0]+1
Example:
Assigns "●" to $1, then sets $2 to the concatenation of "あいうえお", $1, and "さしすせそ".
mov $1,"●"
mov $2,"あいうえお"+$1+"さしすせそ"
;Now $2 contains "あいうえお●さしすせそ".
ONScripter Example:
Assigns "Text" to $0, then concatenates " String" onto it.
mov $0,`Text`
mov $0,$0+` String`
;Now $0 contains "Text String".

add /
page top / list / main

[Special Text Command]( NScr, ONScr-EN )
<>

Text Buttons

'<'[NUM]STR'>'

NUMTextbutton number, must be nonnegative (optional)
STRTextbutton display text

A character string enclosed by '<' and '>' is converted into a text button.

ONScripter Example:
A textbutton numbered 3
`This is a `<3`textbutton`>`.@

linkcolor / textbtnstart / gettextbtnstr / erasetextbtn / textexbtn /
page top / list / main

[Reserved Syntax]( PONS )
0x

Syntax Markers

'0x'HNUM

HNUMHexidecimal number (any combination of digits 0-9, a-f, A-F)

This syntax allows providing a numeric literal value in hexidecimal instead of regular decimal, which can be more convenient in some cases.
PONScripter allows this format almost everywhere regular numeric literals are allowed, with the exception of ! and ~ text directives and tags.

PONScripter Example:
Defines a numeric alias using hexadecimal.
numalias ascii_slash,0x2F

page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
abssetcursor

Cursor

abssetcursor NUM,STR,NUM,NUM

NUMCursor number (0: click-wait cursor, 1: page-wait cursor)
STRCursor image filename
NUMCursor position X-coordinate
NUMCursor position Y-coordinate

This works the same as setcursor, but uses absolute onscreen coordinates, not text-relative coordinates.


setcursor /
page top / list / main

[Definition/Program Block]( NScr, ONScr, ONScr-EN, PONS )
add

Variable Manipulation/Calculations

add %VAR,NUM

VARNumeric variable
NUMNumeric value to add

add $VAR,STR

VARString variable
STRCharacter string to concatenate

Add a number to a numeric variable. If used with strings, performs string concatenation instead.

Example:
Replace the value stored at %0 with %0 + 6.
add %0,6
Example:
Take the string variable $5 and tack "ああああ" to the end.
add $5,"ああああ"

sub /
page top / list / main

[Definition Block Only]( NScr2.70, ONScr-EN )
addkinsoku

Text Display

addkinsoku STR,STR

STRString of characters forbidden at line start
STRString of characters forbidden at line end

This specifies additional characters to be treated as "kinsoku" - forbidden at line start/end - beyond the default sets of kinsoku characters.
The first string contains characters forbidden at the start of a line, while the second string contains characters to be forbidden at the end of a line.


setkinsoku /
page top / list / main

[Definition/Program Block]( NScr2.20, ONScr-EN )
addnsadir

Plugins/Archives

addnsadir STR

STRDirectory to check for NSA archives

Adds a directory to check for NSA archives.


nsadir /
page top / list / main

[Program Block Only]( NScr2.80, ONScr, ONScr-EN, PONS )
allsp2hide

Extended Sprites

allsp2hide

Hides all extended sprites at the same time. (Works essentially the same as allsphide.)


allsp2resume / allsphide / allspresume /
page top / list / main

[Program Block Only]( NScr2.80, ONScr, ONScr-EN, PONS )
allsp2resume

Extended Sprites

allsp2resume

Redisplays the extended sprites that were hidden by allsp2hide. (Works essentially the same as allspresume.)


allsp2hide / allsphide / allspresume /
page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
allsphide

Image Display

allsphide

Hides all sprites at the same time.


allspresume /
page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
allspresume

Image Display

allspresume

Redisplays the sprites that were hidden by allsphide.


allsphide /
page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
amsp

Image Display

amsp NUM,NUM,NUM[,NUM]

NUMSprite number (0 - 999)
NUMX-coordinate
NUMY-coordinate
NUMOpacity (0 - 255)

Similar to msp, but moves the sprite to an absolute instead of relative position.

Example:
This moves Sprite 2 to position (5,2) and gives it an opacity of 100 (out of 255).
amsp 2,5,2,100

msp /
page top / list / main

[Program Block Only]( NScr2.80, ONScr, ONScr-EN, PONS )
amsp2

Extended Sprites

amsp2 NUM,NUM,NUM,NUM,NUM,NUM[,NUM]

NUMExtended-sprite number (0 - 255)
NUMCenter X-coordinate
NUMCenter Y-coordinate
NUMScaling factor X (%)
NUMScaling factor Y (%)
NUMRotation angle (degrees, counterclockwise)
NUMOpacity value (optional, default 255)

Similar to msp2, but this command changes the given extended sprite's position, scale, rotation, and opacity to absolute values instead of relatively.

Example:
Takes Extended-Sprite 0 and moves its center to (10,20) while setting its scale factors to 10% and its rotation to 5 degrees.
amsp2 0,10,20,10,10,5

lsp2 / lsph2 / lsp2add / lsph2add / csp2 / vsp2 / msp2 /
page top / list / main

[Definition Block Only]( NScr )
arc

Plugins/Archives

arc STR

STRPlugin specification

Designate an archive decompression plugin.
The character string's form is "archive-name|plugin-dll-name".
Although this can dearchive sounds, music, and images, it will not run archived scripts.

By combining this with registry read commands, you can do many things. For instance, as in the second example below, you could easily read the Windows registry, find out that the machine had "To Heart" installed, and designate the proper archive to decompress accordingly.

Example:
This specifies using "scrunarc.dll" to open an "arc.sar" archive file.
arc "arc.sar|scrunarc.dll"
Example:
This specifies the archive file and plugin for "To Heart", using registry data.
getreg $0,"software\leaf\toheart","datadir"
add $0,"\lvns3dat.pak|axlfpak.spi"
arc $0

page top / list / main

[Definition/Program Block]( NScr, ONScr, ONScr-EN, PONS )
atoi

Variable Manipulation/Calculations

atoi %VAR,STR

VARNumeric result variable
STRCharacter string to convert

Converts a character string into a numeric variable. This works the same way as the corresponding command in C.

*
This won't convert full-width digit strings. (by senzogawa)
Example:
Populates %0 with 123, and %3 with the number extracted from $0.
atoi %0,"123"
atoi %3,$0

page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
autoclick

Click Wait

autoclick NUM

NUMClick-wait time (msec)

If the designated time (in milliseconds) passes during a click wait state, proceed automatically as if the mouse button was clicked. This command is especially useful in engine cutscenes.
If the number specified is 0, then this command will not activate.


page top / list / main

[Definition Block Only]( NScr, ONScr, ONScr-EN, PONS )
automode

Special Mode Settings

automode

This is a command developed especially for the commercial software "Gin'iro". When you use this command, you can enter Auto Mode from the menu. It is similar in concept to the "skip to next choice" option, but displays characters much more slowly (with a delay defined by automode_time). This makes it almost like a mode in which the computer reads the text to you.

You can adjust sound playback volume from the NScr menus while Auto Mode is progressing (MP3(BGM), voice(DWAVE 0), and SE(DWAVE 1+) are all active and adjustable).

There are future plans to add more functionality to this command, and to make things conform to predefined syntaxes.


page top / list / main

[Definition Block Only]( NScr, ONScr, ONScr-EN, PONS )
automode_time

Special Mode Settings

automode_time NUM

NUMWait time during Auto Mode (msec)

When in Auto Mode (as defined by mode_ext), and when text display is not instantaneous, this sets the delay at clickwaits in milliseconds.


page top / list / main

Ver.2.93[Definition Block Only]( NScr )
autosaveoff

Save/Load

autosaveoff

Disables automatic save points beyond the first displayed sentence.
saveon and saveoff commands will be ignored if this is used.
(Savepoints will still be updated at the beginning of a display sentence, as usual.)
Use the savepoint command to manually update savepoints at places other than the beginning of sentences (e.g. at a clickable map).
Timing issues may slow down returns from data updates, for example when recording a save point after drawing over the entire screen, so please use common sense.


savepoint / saveoff / saveon /
page top / list / main

[Program Block Only]( NScr )
avi

Movie Playback

avi STR,NUM

STRMovie filename
NUMInterrupt flag (0: play whole thing, 1: click-interruptible)

Plays the designated AVI file. If the number is 1, then if the player clicks in the middle of movie playback, the movie will be cut short. If the number is 0, then the player is forced to watch the movie in its entirety.


page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
bar

Character/Number/Bar Display

bar NUM,NUM,NUM,NUM,NUM,NUM,NUM,COLOR

NUMBar number
NUMBar current value
NUMTop-left X-coordinate
NUMTop-left Y-coordinate
NUMBar width
NUMBar height
NUMBar maximum value
COLORBar color

Initializes and displays a (horizontal) bar. The width and height variables denote how large the bar will be when it is at max value. When it is not at max value, the bar will be proportionally smaller, of course. The bar is left-justified. As the bar simply is filled in left-to-right in the designated color, please make sure that the background color for the non-filled in area doesn't match the bar color itself. Finally, if you do not call a print command (or something similar), then of course the bar (or the bar's current status) will not be displayed onscreen.


page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
barclear

Character/Number/Bar Display

barclear

Clears out bars.
You can think of the bars as being like life bars in fighting games, kind of.


bar /
page top / list / main

Ver.2.93[Program Block Only]( NScr )
bclear

New Button Processing

bclear

Clears defined buttons.

*
The same as btndef clear? (by Mion)

btndef /
page top / list / main

Ver.2.94[Program Block Only]( NScr )
bcursor

New Button Processing

bcursor

By default (since ver.2.94), bexec won't return on arrow key or Spacebar/Enter keypresses.
To force returning those keypresses as well, execute bcursor after bclear and before bexec.


getcursor /
page top / list / main

Ver.2.93[Program Block Only]( NScr )
bdef

New Button Processing

bdef STR

STRDefault sprite control string

Specifies behavior for when no sprite buttons are being moused over. Uses the same control string format as exbtn and spstr.

Example:
Sets to hide Sprite 0 whenever none of the sprite buttons are moused over.
bdef "C0"

exbtn_d /
page top / list / main

Ver.2.94[Program Block Only]( NScr )
bdown

New Button Processing

bdown

If bdown is executed after bclear and before bexec, bexec will return on a left-click even before the mouse button press is released.


btndown /
page top / list / main

Ver.2.93[Program Block Only]( NScr )
bexec

New Button Processing

bexec $VAR[,%VAR]

VARInput result var
VARNumeric result var (0 or more: button sprite number, -1: anything else)

Executes button processing. Both a string variable and a numeric variable may be provided as arguments.
Button processing settings remain until bclear is executed.
Both the timeout setting and elapsed button processing time remain until btime is executed.

Possible string variable return values:
"LCLICK" - on mouse left-click anywhere but a sprite button
"S(sprite-num)" - on mouse left-click within a sprite button, e.g. clicking Sprite 12 returns "S12"
"TIMEOUT" - on button processing timeout
"RCLICK" - on mouse right-click
"MCLICK" - on mouse middle-click
Letter/digit/symbol keypresses return the pressed key character (e.g. "1", "W"); note that alphabet letters will be uppercase.
Other keypress return values:
"SPACE" - Spacebar
"RETURN" - Return or Enter key
"CTRL" - any Ctrl key
"SHIFT" - any Shift key
"UP", "DOWN", "LEFT", "RIGHT" - Up, Down, Left, or Right arrow keys
"F1" to "F12" - Function keys
"PAGEUP", "PAGEDOWN" - PageUp or PageDown keys

The numeric variable (if provided) will contain the sprite number of the button that was left-clicked, if applicable; if button processing ends without a sprite button being pressed, the numeric variable will have a return value of -1.

Since bexec will finish on any kind of click or keypress, be sure to put this command within a loop if you need to check for a desired return condition.

*
The 20090422 release added support for middle-button clicks.
Note that ver.2.93 returns CCLICK instead of MCLICK from ver2.94 forward.
Also, ver.2.94 changed the default behavior for bexec so that it won't return on arrow key or Spacebar/Enter keypresses. This allows using arrow keys to move between buttons and the Spacebar/Enter key to "click" the current button.
Example:
Executes button processing, storing input results in $0 and %0.
bexec $0,%0

btnwait /
page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
bg

Image Display

bg STR,EFFECT

STRImage filename
EFFECTEffect for displaying background

bg COLOR,EFFECT

COLOR#rrggbb color for background
EFFECTEffect for displaying background

bg {black|white},EFFECT

ENUMUse basic black/white for background
EFFECTEffect for displaying background

Loads the background image, using the given effect and final image/color.


bgalia / effect /
page top / list / main

[Definition Block Only]( NScr, ONScr, ONScr-EN, PONS )
bgalia

Image Display

bgalia NUM,NUM,NUM,NUM

NUMTop-left X-coordinate
NUMTop-left Y-coordinate
NUMBackground width
NUMBackground height

This command should be used when you wish to create a background of special size or position.
A background pane of dimensions (width, height) is set at absolute screen position (X, Y).


bg /
page top / list / main

[Program Block Only]( NScr2.50, ONScr, ONScr-EN, PONS )
bgcopy

Image Display

bgcopy

The same as bgcpy; the current screen gets copied to the background screen.
The text window, etc. can be displayed on top of this.

*
Since ver2.51, NScr has been able to properly save the background created by this command.

draw /
page top / list / main

[Program Block Only]( NScr1.99, ONScr, ONScr-EN, PONS )
bgm

Music/SFX Playback

bgm STR

STRMusic filename

Plays the given compressed music file in a loop. Equivalent to the mp3loop command.

Example:
Plays "bgm01.mp3" in a loop
bgm "bgm01.mp3"

bgmonce / bgmvol /
page top / list / main

[Definition/Program Block]( NScr2.30, ONScr-EN20091230 )
bgmdownmode

Music/SFX Playback

bgmdownmode NUM

NUM0: off, 1: on

Sets whether the BGM volume should be lowered while a voice sound is playing.

Example:
Sets to have music volume turned down during voice playback.
bgmdownmode 1

page top / list / main

[Definition/Program Block]( NScr2.24, ONScr-EN )
bgmfadein

Music/SFX Playback

bgmfadein NUM

NUMBGM playback fade-in time (msec)

The same as bgmfadeout, except that this is for fadein time.


bgmfadeout /
page top / list / main

[Definition/Program Block]( NScr2.21, ONScr-EN )
bgmfadeout

Music/SFX Playback

bgmfadeout NUM

NUMBGM playback fade-out time (msec)

Sets BGM fadeout time in milliseconds.


bgmfadein /
page top / list / main

[Program Block Only]( NScr1.99, ONScr, ONScr-EN, PONS )
bgmonce

Music/SFX Playback

bgmonce STR

STRMusic filename

Plays the given compressed music file one time through. Equivalent to the mp3 command.

Example:
Plays "bgm01.mid" once
bgm "bgm01.mid"

bgm / bgmvol /
page top / list / main

[Program Block Only]( NScr2.01, ONScr, ONScr-EN, PONS )
bgmstop

Music/SFX Playback

bgmstop

Stops playback of compressed music.


page top / list / main

[Program Block Only]( NScr2.21, ONScr, ONScr-EN, PONS )
bgmvol

Music/SFX Playback

bgmvol NUM

NUMSound volume (0-100)

Changes the volume of the BGM. This applies to both bgm and mp3 commands.

*
Volume changes are not saved, so manage them manually or with variables.
This does not affect the play instruction. (by senzogawa)
Example:
Sets BGM volume to maximum (100)
bgmvol 100

chvol / mp3vol / voicevol / sevol /
page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
blt

Image Display

blt NUM,NUM,NUM,NUM,NUM,NUM,NUM,NUM

NUMOnscreen top-left X-coordinate
NUMOnscreen top-left Y-coordinate
NUMOnscreen width
NUMOnscreen height
NUMIn-buffer top-left X-coordinate
NUMIn-buffer top-left Y-coordinate
NUMIn-buffer width
NUMIn-buffer height

Use this command if you want to blit images instantaneously on screen (as in AIR's opening engine-driven cutscene, for instance).
This utilizes the button image buffer, so please populate said buffer using btndef beforehand.
In cases where the width of the image button is larger than the width of the screen, the image scales accordingly.
(For instance, if one were to load 4 half-sized images and then use blt, then they would instantly be blitted one after another with no afterimage effects, like a high-speed animation. This effect was used in AIR.)
This command writes directly to the screen, not to the backbuffer. Therefore, after the end of the blitting, the contents of the screen may be uncertain, in which case you should use ofscpy (to save the old state) followed by bg (to load a new background).

Even if one saves in the midst of this blitting, the images will not be screenshotted for the save caption.
Therefore, please limit your usage of this technique (for instance, a demo, or a status screen/save/load menu in an SLG).


btndef / ofscpy /
page top / list / main

[Program Block Only]( NScr )
bmpcut

Development Support

bmpcut STR,NUM,NUM

STRImage filename
NUMNumber of horizontal pieces (num. of horiz. cuts + 1)
NUMNumber of vertical pieces (num. of vert. cuts + 1)

Splits a BMP image file into multiple pieces (new files) while preserving the original file. The piece files are named accordingly based on the original filename and the piece position.

Example:
Cuts "test.bmp" into three pieces horizontally and in half vertically.
bmpcut "test.bmp",3,2

page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
br

Text Display

br

Inserts a linefeed into the text window.
Use this when you want a blank line or something similar.


page top / list / main

[Definition/Program Block]( NScr, ONScr, ONScr-EN, PONS )
break

Conditionals/Loops

break

Breaks out of a single loop, proceeding to the line immediately after the loop's next statement.

You cannot use this command by itself to break completely out of nested loops - you'll need to first break out of the inner loop, then break out of the outer loop.

Unrecommended method:
BREAK *(label name)
This syntax does exist; it has the same functionality as a goto statement.
It can break you out of nested loops, but leaves the state of the inner loop intact.
This causes a fragmentation of the stack, making it hard to debug your script later, so use this syntax with extreme caution.

Example:
This displays "%0, %1", with %0 increasing from 1 to 8, and the inner loop counter %1 decreasing as the sequence (6,4,2). However, it breaks out of the inner loop after displaying a %0 or %1 that's equal to 4.
*define
game
*start
for %0=1 to 8
for %1=6 to 2 step -2
%0, %1
if %0=4 & %1=4 break
next
next
click
end

for /
page top / list / main

Ver.2.93[Program Block Only]( NScr )
bsp

New Button Processing

bsp NUM[,STR,STR,STR]

NUMSprite number
STRSprite control string for mouseoff
STRSprite control string for mouseover
STRSprite control string for mousepress

Creates a button from the given sprite.
If the optional parameters are omitted, the sprite displays like so: Cell 0 on mouseoff, Cell 1 on mouseover, and (if the sprite contains at least 3 cells) Cell 2 on mousepress.
The three optional parameters are sprite control strings, with the same format used for exbtn and spstr. The first string executes when the mouse is not over the button (mouseoff), the second on mouseover of the button, and the third on mousepress of the button.
Since a control string "" does nothing, use empty control strings when you don't want one of the three mouse button events to change the display.

*
This command had a bug when handling control strings, but was fixed in the 20090417 release.
Example:
Creates a button from Sprite 1.
bsp 1
Example:
Creates a button from Sprite 2, setting sprite control strings for mouseoff, mouseover, and mousepress.
bsp 2,"P3,0","P3,1","P4,1"

spbtn / exbtn /
page top / list / main

Ver.2.93[Program Block Only]( NScr )
btime

New Button Processing

btime NUM[,NUM]

NUMTimeout duration (ms)
NUMVoice-wait flag (1: wait for voice)

Specifies timeout duration for button processing.
If an optional parameter 1 is given after the timeout value, button processing will allow the voice channel (dwave 0) to finish playing before counting down the timeout; this is used for auto mode, etc.

Example:
Sets button timeout to 2 seconds.
btime 2000
Example:
Sets button timeout to 1 second for after voices have finished.
btime 1000,1

btntime /
page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
btn

Image Buttons

btn NUM,NUM,NUM,NUM,NUM,NUM,NUM

NUMButton number
NUMTop-left X-coordinate
NUMTop-left Y-coordinate
NUMButton width
NUMButton height
NUMX-shift
NUMY-shift

From left to right, this is: button #, x, y, width, height, x3, y3.
This is the command you use to create and initialize buttons. Button numbers start from 1.
The resultant button starts at position (x,y) and is (width,height) big.
When a mouse cursor comes over the button, it will shift leftward and upward by x3 and y3 pixels, respectively.
Look in the "btndemo" folder of the SDK for an example script.


page top / list / main

[Program Block Only]( NScr1.97, ONScr-EN20091122 )
btnarea

Button Extensions

btnarea NUM

NUMY-coordinate setting for the area

Use this after a call to btndef. It will set a region of the screen that, during a btnwait, will return -4 upon mouseover.
If the given Y-value is positive, the mouseover area goes from top of screen to Y; if the Y-value is negative, the mouseover area goes from -Y to bottom of screen.

*
If there's more than one btnarea command, it seems that only the last one will work. (by senzogawa)
Example:
Sets from Y=400 to the bottom of the screen as a mouseover area for btnwait.
btndef clear
btnarea -400

btndef / btnwait2 /
page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
btndef

Image Buttons

btndef STR

STRbutton image filename

btndef clear

Sets up an image button. The previously-defined button is cleared.
For an example, see the "btndemo" folder in the NScr SDK.


page top / list / main

[Program Block Only]( NScr1.97, ONScr, ONScr-EN, PONS )
btndown

Button Extensions

btndown NUM

NUMdown-flag (1: return while mouse button pressed, 0: return after click & release)

Use this between btndef and btnwait commands.
If the given flag value for btndown is 1, then btnwait will return even while the mouse button is down (normally it only returns after the mouse button has been released after a click).

Example:
Sets to return from btnwait while a mouse button is pressed.
btndown 1

btndef / btnwait / isdown /
page top / list / main

[Definition Block Only]( NScr )
btnnowindowerase

Text Window

btnnowindowerase

The text window won't be erased when buttons are active.


page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
btntime

Image Buttons

btntime NUM

NUMTime limit for button wait (msec)

This designates a time limit in milliseconds for the next btnwait or btnwait2 period. When this command is used and a btnwait is activated, and if nothing happens in the specified time period, then btnwait will return -2.

*
If usewheel is set, then btnwait will return -5 instead of -2 in this case. (by senzogawa)

page top / list / main

[Program Block Only]( NScr2.00, ONScr, ONScr-EN, PONS )
btntime2

Image Buttons

btntime2 NUM

NUMTime limit for button wait (msec)

This is the same as btntime, except that the timeout will wait for voices to finish.

Example:
Sets so the next btnwait will have a 1 second timeout.
btntime2 1000

btntime /
page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
btnwait

Image Buttons

btnwait %VAR

STRNumeric result variable

This serves as a button listener. The result value of the button is returned in the numeric variable.

Return Values:
0: no button was clicked
-1: A right-click occured
>=1: Number of clicked button

If btnwait returns a value <=0 (no button clicked), then you can invoke btnwait again to enter the identical button wait state. But if btnwait returns a value >=1 (some button was pressed), then the images will stay, but all button definitions will be cleared (to save memory).
Please consult the "btndemo" folder in the SDK for examples.


page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
btnwait2

Image Buttons

btnwait2 %VAR

VARNumeric result variable

This serves as a button listener. The result value of the button is returned in the numeric variable.

Unlike btnwait, this command does not clear any button definitions. Therefore, it will keep reading the button graphic files.
Since the buttons remain in memory even after there is no use for them, you should call btndef "" after you're finished using them in order to free up the memory.

All Possible Return Values for btnwait (most require a separate cmd to activate):
>=1: Number of clicked button (user-defined via spbtn)
0: left-click, not on a button
-1: right-click

-2: btntime timeout (without usewheel)
-2: mouse wheel-up (if usewheel)
-3: mouse wheel-down (if usewheel)
-4: btnarea mouse-over (if btnarea)
-5: btntime timeout (if usewheel)

-10: Esc key (if useescspc)
-11: Spacebar (if useescspc)
-12: PageUp key (if getpage)
-13: PageDown key (if getpage)
-19: Enter key (if getenter)
-20: Tab key (if gettab)
-21 to -32: F1 to F12 key (if getfunction)
-40 to -43: ↑→↓← key (if getcursor)
-50: Insert key (if getinsert)
-51 to -53: Z, X, C key (if getzxc)
-60: Skip Mode turned off (if getskipoff)
-61: Auto Mode turned off (if getskipoff)
-70: Mouse middle-button click (if getmclick)


page top / list / main

Ver.2.94[Program Block Only]( NScr )
btrans

New Button Processing

btrans

Executing btrans after bclear and before bexecwill cause button processing to treat transparent areas of sprite buttons as outside the respective buttons.


transbtn /
page top / list / main

[Definition/Program Block]( NScr )
bw2a

Development Support

bw2a STR

STRResulting image filename (without .BMP extension)

When given a string "(imagename)", this generates an NScripter-style alpha image from the two files "(imagename)_w.bmp" and "(imagename)_b.bmp".
This produces the same output as the bw2aconv.exe program included with the NScr SDK.

Example:
Generates an NScr-style alpha image from "test_w.bmp" and "test_b.bmp".
bw2a "test"

page top / list / main

Ver.2.49[Definition/Program Block]( NScr )
bw2a3

Development Support

bw2a3 STR

STRResulting image filename

When given an image filename, this looks for image files by that name in folders "w" and "b", then generates an NScripter-style alpha image from them.
This works much the same as bw2a otherwise.

Example:
Generates an NScr-style alpha image from "w\test.bmp" and "b\test.bmp".
bw2a3 "test.bmp"

page top / list / main

[Definition/Program Block]( NScr, ONScr, ONScr-EN, PONS )
caption

Console

caption STR

STRString to use for the window title

Sets the window title.


page top / list / main

[Definition Block Only]( NScr )
cdfadeout

Music/SFX Playback

cdfadeout NUM

NUMCD playback fade-out time (msec)

Designate the fade-out time of CD-DA audio, in milliseconds.

*
Currently, (P)ONScripter cannot support this command, as SDL does not support changing the CD volume. (by Mion)

page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
cell

Image Display

cell NUM,NUM

NUMSprite number (0 - 999)
NUMCell number (0 - numcells-1)

Designate the displayed cell for a sprite. As this is an internal state change only, it is your duty to have it reflected on the screen afterward with a print command or other such method.


page top / list / main

[Program Block Only]( NScr2.49, ONScr, ONScr-EN, PONS )
cellcheckexbtn

Image Buttons

exbtn NUM,NUM,STR

NUMSprite number
NUMButton number
STRSprite control string

This is the exbtn version of cellcheckspbtn, with the same arguments as exbtn.
It will only generate a complex button for sprites with two or more cells.
Check the Samples and Customization for more information on making complex buttons.

Example:
Creates Button 100 from Sprite 1, which will display Cell 1 of Sprite 1 and Sprite 2 when moused-over - but only if Sprite 1 has at least two cells.
cellcheckexbtn 1,100,"P1,1P2"

exbtn / cellcheckspbtn /
page top / list / main

[Program Block Only]( NScr1.99, ONScr, ONScr-EN, PONS )
cellcheckspbtn

Image Buttons

cellcheckspbtn NUM,NUM

NUMSprite number
NUMButton number

Works the same as spbtn, except that it doesn't make buttons from sprites with less than two cells.
This can be used effectively during CG mode.
(In other words, this version of spbtn can be quickly looped over a set of thumbnails that may have single cells.)

Example:
Makes buttons from Sprites 0-9, but only for each sprite with more than one cell
for %0=0 to 9
  cellcheckspbtn %0,%0+1
next

spbtn /
page top / list / main

Ver.2.20[Definition/Program Block]( NScr )
chainbmp

Development Support

chainbmp STR

STRImage filename

Attaches the given image onto the right-side edge of "out.bmp".
This creates "out.bmp" from the image if it does not already exist.

*
The image should be the same height as "out.bmp".

page top / list / main

[Program Block Only]( NScr2.92, ONScr-EN20091230 )
checkkey

System Customization

checkkey %VAR,STR

VARNumeric variable (1: got specified keypress, 0: didn't)
STRKey type

Checks if there was a specified keypress at the last btnwait command, returning 1 if the desired key was pressed.
Allowed key types are single half-width alphabet characters, digits, or spaces, or else one of the following macros:
"SPACE" - Spacebar
"RETURN" or "ENTER" - Enter key
"CTRL" - any Ctrl key
"UP"/"DOWN"/"LEFT"/"RIGHT" - Up/Down/Left/Right arrow key
"F1" ... "F12" - the given Function key
"PAGEUP"/"PAGEDOWN" - PageUp/PageDown key
"SHIFT" - any Shift key

Example:
Does a btnwait. %1 is set to 1 if the Spacebar was pressed, 0 otherwise; %2 is set to 1 if Enter key was pressed, 0 otherwise.
btnwait %0
checkkey %1," "
checkkey %2,"ENTER"

btnwait / selectbtnwait / textbtnwait / textgosub /
page top / list / main

[Program Block Only]( NScr2.49, ONScr, ONScr-EN, PONS )
checkpage

Log Mode Customization

checkpage %VAR,NUM

VARResult numeric variable
NUMPrevious page (number of pages back; 0 = current page)

Checks whether the log string of a backlog page is available (to getlog, for example).
The second parameter tells the number of pages prior to the current one to check for.
The first parameter will be set to 1 if the page is available, 0 if not.
Please provide a value of 1 or more for the second parameter, noting that, since 0 is the current page, it would always be available.

Example:
Set %5 based on whether or not the last page backlog is available.
checkpage %5,1

getlog /
page top / list / main

Ver.1.99[Definition Block Only]( NScr )
chkcdfile

Music/SFX Playback

chkcdfile STR,STR

STRFile name to check for
STRError message to display

This checks for the given file on the CD drive.
If it cannot find the file, it displays the given error message in a popup box with buttons "Retry" and "Cancel".

Example:
This checks the CD for "file.dat".
chkcdfile "file.dat","CDがありません"

chkcdfile_ex /
page top / list / main

Ver.2.20[Definition Block Only]( NScr )
chkcdfile_ex

Music/SFX Playback

chkcdfile_ex %VAR,STR

VARResult numeric variable
STRFile name to check for

This checks for the given file on the CD drive.
It sets the result to 1 if it finds the file, 0 otherwise.

Example:
This checks the CD for "file.dat" and assigns the result to %0.
chkcdfile_ex %0,"file.dat"

chkcdfile /
page top / list / main

[Program Block Only]( NScr2.00, ONScr, ONScr-EN, PONS )
chvol

Music/SFX Playback

chvol NUM,NUM

NUMDWAVE channel number (0 - 49)
NUMSound volume (0-100)

Changes the volume of the given DWAVE channel.

*
Channel volume changes are not saved, so manage them manually or with variables.
Example:
Sets Channel 3 volume to maximum (100)
chvol 3,100

page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
cl

Image Display

cl {l,c,r,a},EFFECT

ENUMstanding pic position (l: left, c: center, r: right, a: all)
EFFECTEffect for removing standing picture(s)

Clear a standing image from the current picture.
If you specify 'a', then that will clear all of them.


effect / ld /
page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
click

Click Wait

click

Wait for a click.


lrclick /
page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
clickpos

Miscellaneous

clickpos %VAR,%VAR

VARX-coordinate at last click
VARY-coordinate at last click

Returns the position of the last click - the first variable is x, the second variable is y.


page top / list / main

[Definition Block Only]( NScr2.60, ONScr-EN )
clickskippage

Click Wait

clickskippage

The script will wait at clickwaits as usual, except that if a click happens while text is being output, then display will jump to the next pagewait (instead of the next clickwait as normal).


page top / list / main

[Definition Block Only]( NScr, ONScr, ONScr-EN, PONS )
clickstr

Click Wait

clickstr STR,NUM

STRClickwait characters
NUMLines left on page to activate pagewait

This function forces a click wait state when the interpreter encounters one of the characters in the given string.
However, if there happens to be a click wait command directly after that character, or if that character is prefaced by a 1-byte underscore (_), then this forced click wait state will not occur.
The second parameter decides whether this will be a simple click-wait or a new-page wait. If the clickstr char occurs on a line past (max textwindow lines - number), then it will use a new-page wait.
This function is convenient, but be careful -- exceptionally long lines may still overflow the textarea. In such situations, you may want to use a standard new-page wait or some other manual adjustment.
Please note that the character string should only contain double-byte chars.

Example:
Cause a clickwait at characters '」', '。', '!', '?'
clickstr "」。!?",2

@ / \ / _ /
page top / list / main

[Definition Block Only]( NScr, ONScr, ONScr-EN, PONS )
clickvoice

Click Wait

clickvoice STR,STR

STRSound for click-wait
STRSound for page-wait

Specifies sounds to play when a button is clicked during a click wait state. The first string is the name of the WAV file played for a click wait state, while the second string is the WAV file played for a new-page click wait state.


page top / list / main

[Definition/Program Block]( NScr, ONScr, ONScr-EN, PONS )
cmp

Conditionals/Loops

cmp %VAR,STR,STR

VARNumeric variable for result of comparison
STRCharacter string #1
STRCharacter string #2

Compares two character strings. Returns 0 if equal, a positive value if the first string comes before in sorting order, and a negative value if the second string comes before in sorting order.

*
In recent NScripter, if you just need to see if strings are equal, == and != will do the job - you needn't use cmp. (by senzogawa)

page top / list / main

[Definition/Program Block]( NScr2.25, ONScr, ONScr-EN, PONS )
cos

Variable Manipulation/Calculations

cos %VAR,NUM

VARNumeric result variable
NUMAngle (in degrees)

Acquires the trigonometric cosine of the given angle, and returns the value multiplied by 1000.

Example:
Assigns the cosine of 60 degrees to %1.
cos %1,60
;%1=500, since cos(60)=0.5

sin / tan /
page top / list / main

Ver.2.20[Definition Block Only]( NScr )
createdummy

Development Support

createdummy STR

STRDummy image filename

Creates a dummy 640x480 image file of the given name.
The image will contain the file name in large black letters on a white background.

*
The image will be 640x480 even if the screen size was changed, like with mode800. (by senzogawa)
Example:
Creates a dummy image file called "test.bmp".
createdummy "test.bmp"

page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
csel

System Customization

csel STR,LABEL[,STR,LABEL[,...]]

LABELChoice string to display
LABELChoice select destination

Sets a selection of choices to display using system customization. *customsel is called to handle the customized display. This command uses the same syntax as select.

Example:
Sets up a customized selection where "Choice1" goes to *s1, "Choice2" goes to *s2, and "Choice3" goes to *s3.
csel "Choice1",*s1,"Choice2",*s2,"Choice3",*s3

*customsel / cselbtn / cselgoto / getcselnum / getcselstr / selectbtnwait /
page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
cselbtn

System Customization

cselbtn NUM,NUM,NUM,NUM

NUMChoice index number (starting at 0)
LABELTop-left X-coordinate
LABELTop-left Y-coordinate

Creates a button from the text of the given choice number - no need to specify the string or sprite number.

*
Giving coordinates that are not within the text window will cause an error. It is necessary to use getcselstr and a different button command to display the choice text outside the text window. (by senzogawa)
Example:
Displays the first choice string as button 500 at position (%1,%2).
cselbtn 0,500,%1,%2

csel / *customsel / cselgoto / getcselnum / getcselstr / selectbtnwait /
page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
cselgoto

System Customization

cselgoto NUM

NUMChoice index number (starting at 0)

Jumps to the label of the given choice index set by csel.

Example:
Jumps to the choice label indexed by the number in %0.
cselgoto %0

csel / *customsel / cselbtn / getcselnum / getcselstr / selectbtnwait /
page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
csp

Image Display

csp NUM

NUMSprite number (0 - 999), or -1 for all

Erases the given sprite.
If the given value is -1, it erases all sprites.


page top / list / main

[Program Block Only]( NScr2.80, ONScr, ONScr-EN, PONS )
csp2

Extended Sprites

csp2 NUM

NUMExtended-sprite number (0 - 255), or -1 for all

Erases the given extended sprite.
If the given value is -1, it erases all extended sprites.


lsp2 / lsph2 / lsp2add / lsph2add / vsp2 / msp2 / amsp2 /
page top / list / main

Ver.2.63[Definition/Program Block]( NScr )
csvclose

CSV File Manipulation

csvclose

Closes an open CSV file. Please use this command when finished with the file; otherwise it will remain open.


csvopen /
page top / list / main

Ver.2.63[Definition/Program Block]( NScr )
csveof

CSV File Manipulation

csveof %VAR

VARnumeric result variable (0: not at end of file, 1: at end of file)

(For use in read mode only)
Detects whether or not the end of a CSV file has been reached.
Returns 1 if so, 0 if not.

Example:
Sets the value of %1 depending on the end status of the CSV file.
csveof %1

csvread /
page top / list / main

Ver.2.63[Definition/Program Block]( NScr )
csvopen

CSV File Manipulation

csvopen STR,STR

STRCSV file name
STRfile access mode

Opens a given CSV file, using the given file access mode.
The possible modes are:
"r" - read mode; reads a standard CSV file
"rc" - read encrypted mode; reads a CSV file written in "wc" mode
"w" - write mode; write to a standard CSV file
"wc" - write encrypted mode; writes an encrypted CSV file

Note that it's possible to open a CSV file inside an NSA archive, but only for reading.

*
The CSV file will be closed automatically at a reset command. (by senzogawa)
Example:
Opens "test.csv" for reading.
csvopen "test.csv","r"
Example:
Opens "angou.csv" for encrypted writing.
csvopen "angou.csv","wc"

csvread / csvwrite / csveof / csvclose /
page top / list / main

Ver.2.63[Definition/Program Block]( NScr )
csvread

CSV File Manipulation

csvread %VAR|$VAR[,...]

VARnumeric or string variable for extracted CSV item

(For use in read mode only)
Reads data items from a CSV file, in the specified order.

Example:
Reads 4 data items from a CSV file and assigns them to $0, $1, %0, and %2 (in that order).
csvread $0,$1,%0,%2

csvopen /
page top / list / main

Ver.2.63[Definition/Program Block]( NScr )
csvwrite

CSV File Manipulation

csvwrite STR|NUM[,...]

VALnumeric or string value to write

(For use in write mode only)
Writes data items to a CSV file, in the specified order.

Example:
Writes 4 data items to a CSV file: 12, "test", %1, and $2.
csvwrite 12,"test",%1,$2

csvopen /
page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
date

Data Acquisition

date %VAR,%VAR,%VAR

VARNumeric variable for the retrieved year
VARNumeric variable for the retrieved month
VARNumeric variable for the retrieved date

Retrieves the current date, in numeric values.


page top / list / main

Ver.2.61[Definition/Program Block]( NScr )
debuglog

Development Support

debuglog NUM

NUMDebug logging flag (0: off, 1: on)

If enabled, saves the message displayed in the debug window to "debuglog.txt".


page top / list / main

[Definition/Program Block]( NScr, ONScr, ONScr-EN, PONS )
dec

Variable Manipulation/Calculations

dec %VAR

VARNumeric variable to decrement

Decrements said variable by 1.


page top / list / main

[Definition Block Only]( NScr )
defaultfont

Text Display

defaultfont STR

STRFont name

Defines a default font.
NScripter defaults to MS Gothic if this command is not used.

*
In NScripter, until "envdata" file is erased, changing or adding this command will not affect a game font. (by senzogawa)
*
ONScripter(-EN) technically allows this command, but doesn't do anything with the given font (using a local "default.ttf" font file instead).
PONScripter sets fonts using pmapfont.
Neither use Windows system fonts, only local font files. (by Mion)

page top / list / main

[Definition Block Only]( NScr, ONScr, ONScr-EN, PONS )
defaultspeed

Window Menubar

defaultspeed NUM,NUM,NUM

NUMSlow default text display speed
NUMMedium default text display speed
NUMFast default text display speed

Designate text speeds (character delays, in msec) to use when the interpreter encounters textspeeddefault or the special text command !sd.
From left to right, the numbers correspond to 低速(Slow), 普通(Medium), and 高速(Fast) in the textspeed menu.

*
Although (P)ONScripter does not provide a menubar, you can select among the textspeeds using keystrokes: '1' for slow, '2' for medium, '3' for fast, and '0' to toggle between all three.
Example:
Sets the default text speeds as 50 for "Slow", 20 for "Medium", and 0 for "Fast".
defaultspeed 50,20,0

!sd / textspeeddefault /
page top / list / main

[Definition Block Only]( NScr2.37, ONScr-EN )
defbgmvol

Special Mode Settings

defbgmvol NUM

NUMDefault volume (0 - 100)

Sets the default volume for BGM, from a range of 0-100. Is 100 by default.


page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
definereset

Game Start/End/Quit

definereset

This is a special reset command that forces reinterpretation of the script starting at *define.


*define /
page top / list / main

[Definition Block Only]( NScr1.97, ONScr, ONScr-EN, PONS )
defmp3vol

Special Mode Settings

defmp3vol NUM

NUMDefault volume (0 - 100)

Sets the default volume for mp3s (BGM), from a range of 0-100. Is 100 by default.


page top / list / main

[Definition Block Only]( NScr1.97, ONScr, ONScr-EN, PONS )
defsevol

Special Mode Settings

defsevol NUM

NUMDefault volume (0 - 100)

Sets default volume for sound effects (DWAVE 1+). Ranges from 0 to 100. Is 100 by default.


page top / list / main

[Definition Block Only]( NScr2.40, ONScr, ONScr-EN, PONS )
defsub

System Customization

defsub NAME

NAMESubroutine label name

This creates a user-defined command.
It will be called as a subroutine (i.e. via gosub). Even though this follows variable naming conventions, user-defined command names may not begin with "_".

*
It's possible to define a user command with the same name as a built-in command.
When this is the case, please use _name instead of name to call the original command - see the second example.
Example:
Defines and calls the "subname" subroutine.
defsub subname
; stuff happens here
subname
; just returned from calling *subname
end
*subname
; got here via a gosub or call to user-def command
return
Example:
Defines and calls the "texton" subroutine while also using the "texton" command.
*define
defsub *texton
game

*start
texton ; does "gosub *texton"
_texton ; calls the original "texton" command

getparam /
page top / list / main

[Definition Block Only]( NScr1.97, ONScr, ONScr-EN, PONS )
defvoicevol

Special Mode Settings

defvoicevol NUM

NUMDefault volume (0 - 100)

Sets default volume for voices (DWAVE 0). Ranges from 0 to 100. Default value is 100.


page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
delay

Wait/Timer

delay NUM

NUMAmount of time to wait (msec)

Causes a delay of specified time (in milliseconds) that may be escaped out of by clicking.
This works the same as the special text command '!d', but here you can supply a variable as the argument.


!d /
page top / list / main

Ver.2.03[Definition Block Only]( NScr )
deletemenu

Window Menubar

deletemenu

Completely removes the Windows menubar from NScripter.


killmenu / resetmenu / insertmenu /
page top / list / main

[Program Block Only]( NScr2.30, ONScr-EN, PONS )
deletescreenshot

Screenshot

deletescreenshot

Removes a screenshot image from memory.
This command is meant to be used with savescreenshot2.


getscreenshot / savescreenshot / savescreenshot2 /
page top / list / main

[Definition Block Only]( NScr1.97, ONScr, ONScr-EN, PONS )
dim

Variable Manipulation/Calculations

dim '?'NUM'['NUM']' [ '['NUM']'... ]

NUMArray number (0 - 199)
NUMDimension length (actual # of elements is length+1)

This defines BASIC-style arrays. For example, "dim ?0[10][20]" makes an array named ?0, with array slots from 0-10, and each slot has subslots from 0-20.
In this fashion, you can use arrayed variables as if they were simple numeric variables.
You can also make your code easier to read by using numalias, as in the second example.

*
Remember, the contents of an array start at 0, so please be careful when allocating them!
Example:
An example of array usage
mov ?0[2][5],20
;populates ?0[2][5] with value 20.
mov %4,?0[3][1]
; populates %4 with the value from ?0[3][1].
VAL=?0[2][3]@
;used in text
Example:
Using an alias with an array
numalias enemyparam,10
dim ?enemyparam[10]

page top / list / main

[Definition/Program Block]( NScr, ONScr, ONScr-EN, PONS )
div

Variable Manipulation/Calculations

div %VAR,NUM

VARNumeric variable
NUMNumeric value to divide by

Divides the variable by the number, truncating the remainder.


page top / list / main

[Program Block Only]( NScr2.31, ONScr, ONScr-EN, PONS )
draw

Demo Draw Commands

draw

Sends images created via demo draw commands (e.g. drawbg, drawsp) directly to the screen.
Otherwise, the results of the draw commands will not be displayed.

Example:
Displays "bg.bmp" while rotating it counter-clockwise.
*test
saveoff
;Demo image processing is faster with saveoff. Don't forget to reenable saveon when you're done!
mov %0,0
bg "bg.bmp",1
*lp
resettimer
drawclear
drawbg2 320,240,100,100,%0*2
draw
wait 5
;ウェイトを多少いれないと、メッセージ処理が遅れがちになります。
gettimer %1
if %1>=50 add %0,%1/50
if %1<50 waittimer 50:inc %0
;掛かった処理時間に比例して変数を変化させます。
goto *lp

page top / list / main

[Program Block Only]( NScr2.31, ONScr, ONScr-EN, PONS )
drawbg

Demo Draw Commands

drawbg

Draws the background image to the screen.
Must be followed by the draw command.

*
Note that neither the sprites, standing images, nor text window will be displayed.

draw /
page top / list / main

[Program Block Only]( NScr2.31, ONScr, ONScr-EN, PONS )
drawbg2

Demo Draw Commands

drawbg2 NUM,NUM,NUM,NUM,NUM

NUMCenter X-coordinate
NUMCenter Y-coordinate
NUMWidth scaling factor (%)
NUMHeight scaling factor (%)
NUMRotation angle (degrees, counter-clockwise)

Draws the background image to the screen, using the given center coordinates, scaling factors, and rotation.
The previous image can still be seen in sections outside the rotated image rectangle; use drawclear beforehand if this is undesirable.
This command must be followed by the draw command.

*
Note that neither the sprites, standing images, nor text window will be displayed.
Also note that this command uses center coordinates, not top-left coordinates like most other commands.
Example:
Draw the background image centered at (320,240), scaled times 2 in width, times 3 in height, and rotated 15 degrees counter-clockwise.
drawbg2 320,240,200,300,15

draw / drawclear /
page top / list / main

[Program Block Only]( NScr2.31, ONScr, ONScr-EN, PONS )
drawclear

Demo Draw Commands

drawclear

Paints over the entire screen with the color black.
Must be followed by the draw command.


draw /
page top / list / main

[Program Block Only]( NScr2.31, ONScr, ONScr-EN, PONS )
drawfill

Demo Draw Commands

drawfill NUM,NUM,NUM

NUMRed component of RGB color (0-255)
NUMGreen component of RGB color (0-255)
NUMBlue component of RGB color (0-255)

Paints over the entire screen with the given color, as provided with separate R,G,B levels.
Must be followed by the draw command.

Example:
Paints over the screen with color #FF0080.
drawfill 255,0,128

draw /
page top / list / main

[Program Block Only]( NScr2.31, ONScr, ONScr-EN, PONS )
drawsp

Demo Draw Commands

drawsp NUM,NUM,NUM,NUM,NUM

NUMSprite number
NUMCell number (of sprite)
NUMOpacity (0-255)
NUMTop-left X-coordinate
NUMTop-left Y-coordinate

Draws a sprite to the screen, using the given sprite number, cell number, opacity, and top-left coordinates.
The position and show/hide status of the actual sprite are not used, just the image itself.
The sprite will be drawn on top of previous drawn items, like from other drawsp or drawtext.
This command must be followed by the draw command.

Example:
Draw Sprite 2, Cell 1 with top-left at (20,40) and half-transparency (128).
drawsp 2,1,128,20,40

draw / drawtext /
page top / list / main

[Program Block Only]( NScr2.31, ONScr, ONScr-EN, PONS )
drawsp2

Demo Draw Commands

drawsp2 NUM,NUM,NUM,NUM,NUM,NUM,NUM,NUM

NUMSprite number
NUMCell number (of sprite)
NUMOpacity (0-255)
NUMCenter X-coordinate
NUMCenter Y-coordinate
NUMWidth scaling factor (%)
NUMHeight scaling factor (%)
NUMRotation angle (degrees, counter-clockwise)

Draws a sprite to the screen, using the given sprite number, cell number, opacity, center coordinates, scaling factors, and rotation.
The position and show/hide status of the actual sprite are not used, just the image itself.
The sprite will be drawn on top of previous drawn items, like from other drawsp or drawtext.
This command must be followed by the draw command.

*
Note that this command uses center coordinates, not top-left coordinates like most other commands.
In Nscr ver2.51 and earlier, this command had a bug when applying the opacity parameter to sprites with alpha values: 0 was treated as opaque, and 255 as transparent.
When running a script created using an earlier NScr version, the third parameter of drawsp2 must be corrected to work properly with NScr ver2.52 and above.
Example:
Draw Sprite 2, Cell 1 at half-transparency (128), centered at (20,40), with 150% width, 60% height, and rotated 10 degrees clockwise.
drawsp2 2,1,128,20,40,150,60,-10

draw / drawsp /
page top / list / main

[Program Block Only]( NScr2.60, ONScr, ONScr-EN, PONS )
drawsp3

Demo Draw Commands

drawsp3 NUM,NUM,NUM,NUM,NUM,NUM,NUM,NUM,NUM

NUMSprite number
NUMCell number (of sprite)
NUMOpacity (0-255)
NUMTop-left X-coordinate
NUMTop-left Y-coordinate
NUMMatrix top-left coefficient
NUMMatrix top-right coefficient
NUMMatrix bottom-left coefficient
NUMMatrix bottom-right coefficient

Like drawsp, this command draws a sprite to the screen - but it first applies a linear transformation.
It uses the given sprite number, cell number, opacity, and linear transformation matrix.
The given matrix coefficients will be divided by 1000 before being applied, so that, for example, a parameter of 1600 yields a coefficient of 1.6.
This command must be followed by the draw command.

Example:
Draw Sprite 2, Cell 1 at half-transparency (128), with top-left at (20,40), after applying the linear transformation [ 1.5, 0.3; 0.8, 1.2 ].
drawsp3 2,1,128,20,40,1500,300,800,1200

draw / drawsp /
page top / list / main

[Program Block Only]( NScr2.31, ONScr, ONScr-EN, PONS )
drawtext

Demo Draw Commands

drawtext

Draws the text window.
Sprites drawn earlier (e.g. with drawsp) will appear below the text, and sprites drawn after this command will appear above the text.
This command must be followed by the draw command.


draw / drawsp /
page top / list / main

[Definition Block Only]( NScr, ONScr, ONScr-EN, PONS )
dsound

Music/SFX Playback

dsound

You use this in the define block in order to turn on DirectSound. You'll need DirectX 2+ in order to use this command. In the later versions of NScripter (1.97+), it is no longer necessary to set this command.


page top / list / main

[Program Block Only]( NScr1.97, ONScr, ONScr-EN, PONS )
dv

Music/SFX Playback

'dv'NUM':'

NUMVoice file number

This is a shorthand command for playing voice files.
It is equivalent to dwave 0,"voice\(num).wav".

Example:
This plays "voice\0001.wav" via the dwave command on channel 0 before outputting text.
dv0001:「これが0001番のせりふだよー」

dwave / v /
page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
dwave

Music/SFX Playback

dwave NUM,STR

NUMChannel number (0 - 49)
STRWAV filename

Plays a WAV file using DirectSound, using the specified number as the channel number (from 0-49). Different WAV files will be mixed automatically this way as they are encountered. If you wanted all voices to be played in succession (text waits for voice) in Auto Mode, you'd set all voices to channel 0. Only PCM files can be played using this command.
This command is used in the same way as the wave command, with the added advantage of the mixing -- so if you were playing an mp3 as background music, you'd want to use dwave for voices and sound effects.

*
If a WAV file from an NSA archive is played via the wave command, and then an attempt is made to play it with dwave without first using wavestop or stop, this will cause an error (since Ver.2.54). (by senzagawa)
*
The number of available channels was increased from 50 to 200 (0-199) in NScr ver2.82. (by Mion)
Example:
This plays "test.wav" in channel 0 just once.
dwave 0,"test.wav"

dwavestop /
page top / list / main

[Program Block Only]( NScr1.97, ONScr, ONScr-EN, PONS )
dwaveload

Music/SFX Playback

dwaveload NUM,STR

NUMChannel number (0 - 49)
STRWAV filename

Loads a WAV file into memory for use with the commands dwaveplay and dwaveplayloop.

*
Trying a dwaveplay without first loading will cause an error. (by senzagawa)
Also, this command can't be used with OGG files. (by senzogawa)
Example:
This loads "test.wav" into channel 0, then plays it just once.
dwaveload 0,"test.wav"
dwaveplay 0

page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
dwaveloop

Music/SFX Playback

dwaveloop NUM,STR

NUMChannel number (0 - 49)
STRWAV filename

The same as dwave, but in this case it loops the WAV file.

*
If a WAV file from an NSA archive is played via the wave command, and then an attempt is made to play it with dwaveloop without first using wavestop or stop, this will cause an error (since Ver.2.54). (by senzagawa)

dwavestop /
page top / list / main

[Program Block Only]( NScr1.97, ONScr, ONScr-EN, PONS )
dwaveplay

Music/SFX Playback

dwaveplay NUM

NUMChannel number (0 - 49)

Plays the file loaded by dwaveload.

*
Trying a dwaveplay without first loading will cause an error. Also, this command can't be used with OGG files. (by senzogawa)
But it doesn't cause a error (in NScr) if you use ogg.dll. (by senzogawa)
After this instruction, it seems you need to use chvol to change the volume. (by senzogawa)

dwaveload /
page top / list / main

[Program Block Only]( NScr1.97, ONScr, ONScr-EN, PONS )
dwaveplayloop

Music/SFX Playback

dwaveplayloop NUM

NUMChannel number (0 - 49)

Loops the WAV file loaded by dwaveload.


dwaveload /
page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
dwavestop

Music/SFX Playback

dwavestop NUM

NUMChannel number (0 - 49)

Silences that particular channel.


page top / list / main

[Definition Block Only]( NScr, ONScr, ONScr-EN, PONS )
effect

Visual Effects

effect NUM,NUM[,NUM[,STR]]

NUMEffect number (2 - 255)
NUMBuilt-in effect number (1 - 18,)
NUMDuration (msec)
STRMask filename

Build an Effect Number from a built-in effect.
Once you have an Effect Number assigned, you can use it in image display commands.
From left to right, the variables are: effect number, built-in effect index, effect runtime (in milliseconds), and pattern image filename.
For some built-in effects, you may omit the last two variables.

Effect 0 is reserved for storing image changes to be displayed at the next image display command, so please number your effects starting at 1.
When you use Effect 0, please remember to call an image display command as soon as possible afterwards.

By default, built-in effect 1 is not an effect at all - it sets the effect runtime to 0 for instantaneous display.

Built-in effect index:
1. Instantaneous display. No runtime variable needed.
2. Left-sided shutter
3. Right-sided shutter
4. Upwards shutter
5. Downwards shutter
6. Left-moving curtain
7. Right-moving curtain
8. Upwards curtain
9. Downwards curtain
10. Pixelwise crossfade
11. Left-moving scroll
12. Right-moving scroll
13. Upwards scroll
14. Downwards scroll
15. Fade via mask pattern. You must provide a filename pointing to a mask image (of either 256 colors or full color). Within a masked image, the white areas fade slowly, and the black areas fade quickly.
16. Mosaic out. After this effect is called, the state of the screen will be uncertain (like with Effect 0), so please call a display command, like print, immediately afterwards.
17. Mosaic in
18. Crossfade via mask. This works similarly to Effect 15, except it is far more processor intensive, so use it with care.

Special Plugin Effects: (added NScr ver2.03)
99. This "built-in effect" is a placeholder for plugin-provided effects, but cannot be used to define an Effect Number using effect (in Nscripter). It may be used anywhere else an effect specification is allowed. See print for more details.

Example:
Sets Effect 2 to be an upwards shutter of one second.
effect 2,4,1000
Example:
Sets Effect 3 to be a two second masked fade.
effect 3,15,2000,"m3.bmp"

print /
page top / list / main

[Definition Block Only]( NScr, ONScr, ONScr-EN, PONS )
effectblank

Visual Effects

effectblank NUM

NUMWait time before next command (msec)

This simply sets (in milliseconds) how long the interpreter should wait after an effect is finished before interpreting the next command.
If the effect was built-in effect 1, then the delay from this command doesn't take place.


page top / list / main

[Definition Block Only]( NScr1.97, ONScr, ONScr-EN, PONS )
effectcut

Visual Effects

effectcut

Skip all effects in "skip to next choice" mode.


page top / list / main

[Program Block Only]( NScr2.92, ONScr-EN )
effectskip

Visual Effects

effectskip NUM

NUMEffect skip flag (0: skip not allowed, 1: skip allowed)

Specifies whether effects can be skipped if a click occurs during the effect.
The default value is 1 (skip allowed); setting this to 0 means effects cannot be skipped using mouse clicks.

Example:
Allows skipping during an effect with click.
effectskip 1

effect / print /
page top / list / main

[Definition/Program Block]( NScr, ONScr, ONScr-EN, PONS )
end

Game Start/End/Quit

end

End the program and close the window.


game /
page top / list / main

[Definition Block Only]( NScr2.82 )
english

Text Display

english

Enables NScripter English mode. Only half-width alphabetical sentences will be displayed correctly.
Please begin text with the ">" character when using this mode.

*
This seems to have been added in the 2007/11/04 release. Note that standard text commands like #rrggbb and !sd do not work in this mode; see the related commands for alternatives. (by senzogawa)
*
ONScripter may support this somewhat, but considering its existing support for single-byte text, and the fact that NScripter english mode doesn't work with most text commands, why bother using it? (by Mion)
Example:
Displays the text "Peter Piper picked a peck of pickled peppers;"
*define
english
game
*start
>Peter Piper picked a peck of pickled peppers;@
end

textcolor / textspeed / textspeeddefault / delay / wait /
page top / list / main

[Program Block Only]( NScr2.65, ONScr-EN )
erasetextbtn

Text Buttons

erasetextbtn

After exiting a button wait, if a textbutton was pressed, then this command will set the textbutton back to its original color.


<> /
page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
erasetextwindow

Text Window

erasetextwindow NUM

NUMFlag (0: leave window as is, 1: remove during effects)

If 0, the text window stays during effect runtime.
If 1 (this is the default), the text window is hidden during effect runtime.


page top / list / main

Ver.1.99[Definition Block Only]( NScr )
errorsave

Save/Load

errorsave

This command specifies that, when an error occurs, the current game state should be stored automatically in Savefile 999; this may be useful for game debugging purposes.


page top / list / main

[Program Block Only]( NScr1.97, ONScr, ONScr-EN, PONS )
exbtn

Image Buttons

exbtn NUM,NUM,STR

NUMSprite number
NUMButton number
STRSprite control string

This is exactly the same as spbtn, with the addition of a trailing control string.
In short, when the player mouses over a button controlled by exbtn, the button isn't just shifted - control over screen graphics is exerted as per the sprite control string.

The control string can contain any of the following commands:
"C(sprite-num)": hides the sprite with the given number.
"P(sprite-num)": displays the sprite with the given number.
"P(sprite-num),(cell-num)": displays a particular cell of the given sprite.
"M(sprite-num),(x),(y)": moves the given sprite to coordinates (x,y).
"S{channel-num},({sound-file})": plays the given sound file.
For example: "S1(beep.wav)" plays "beep.wav" on channel 1.

You can combine any number of these options in your control string.

When using composite buttons, there needs to be an assignment for what occurs when the mouse cursor isn't touching any part of the button - set this using exbtn_d.

Buttons, like any other graphic, can be loaded as image filename character strings or as sprites.

Example:
Clears Sprite 10.
spstr "C10"
Example:
Clears Sprite 11 and displays Sprite 10.
spstr "C11P10"
Example:
Clears Sprite 11, displays cell 2 of Sprite 10, and displays Sprite 9.
spstr "C11P10,2P9"

exbtn_d /
page top / list / main

[Program Block Only]( NScr1.97, ONScr, ONScr-EN, PONS )
exbtn_d

Image Buttons

exbtn_d STR

STRSprite control string

Determines the state of the composite button when the mouse cursor is on no part of it. See the documentation for exbtn for the format of the control string.

Example:
When the mouse is off the composite button, this displays Sprite 3, clears Sprites 4 5 & 6, and displays cell 0 of Sprite 7.
exbtn_d "P3C4C5C6P7,0"

page top / list / main

[Definition/Program Block]( NScr2.03, ONScr, ONScr-EN, PONS )
exec_dll

Plugins/Archives

exec_dll STR

STRDLL filename followed by parameters

Calls the given DLL with the specified parameters.

*
(P)ONScripter recognizes this command but does a value lookup in a text file called "dll.txt" using the DLL name and parameters, instead of calling an actual DLL; note that this is more a crutch than an implementation. (by Mion)
Example:
Calls "execdll.dll" with the parameter string "テストですよー。".
exec_dll "execdll.dll/テストですよー。"

page top / list / main

[Definition/Program Block]( NScr, ONScr, ONScr-EN, PONS )
fchk

Conditionals/Loops

fchk STR

STRFilename of image to confirm

Checks to see whether an image tag has been recorded in the file log.
This is used as a conditional for an if statement. If the image has been loaded and may be used in-game, this returns true; if not, or if the filename was incorrect, this returns false.

Example:
ld c,":a;test.bmp",1
if fchk ":a;test.bmp" ;returns true
if fchk "test.bmp"    ;same result

page top / list / main

[Program Block Only]( NScr2.01, ONScr, ONScr-EN, PONS )
fileexist

Miscellaneous

fileexist %VAR,STR

VARResult for file check (1: exists, 0: not found)
STRFilename

Assigns 1 to the given variable if the file exists, 0 if not. This will also check within NSA archives.


fileremove /
page top / list / main

[Definition Block Only]( NScr, ONScr, ONScr-EN, PONS )
filelog

File Access Logs/Global Variables

filelog

This allows for creation of a file log.
Every single resource used by the program will be recorded in that file log as a tag.
If you specify neither this command nor globalon, then nscr.exe will not generate any files, and will be able to run from CD.


page top / list / main

Ver.(undoc)[Program Block Only]( NScr )
fileremove

Miscellaneous

fileremove STR

STRFilename

Deletes the given file.


fileexist /
page top / list / main

[Program Block Only]( NScr2.48, ONScr-EN20100102 )
flushout

Visual Effects

flushout NUM

NUMDuration (msec)

Special effect; may be graphic-intensive.
Ends with a white background, so please load a background in one of the next instructions.


bg /
page top / list / main

Ver.2.67[Program Block Only]( NScr )
font

Text Window

font STR

STRFont name

Changes the text display font.
If the text window is already displayed, the new font will only take effect the next time the window is cleared.

Example:
Changes display text font to "MS 明朝"
font "MS 明朝"

page top / list / main

[Definition/Program Block]( NScr, ONScr, ONScr-EN, PONS )
for

Conditionals/Loops

for %VAR=NUM to NUM[ step NUM]

VARNumeric variable used as counter
NUMInitial value for counter
NUMEnding value for counter
NUMIncrement step for counter

This is essentially the same as a BASIC loop. The for loop starts at the first number, and then increments (or decrements) by the step value until it has gone beyond the second number (or below, in the case of a negative step). The step value is 1 by default.

If you use commands like goto or select inside a for loop, this will leave the NScripter stack in an inconsistent and easily-crashable state - so please don't do that.

All commands in the loop between the FOR and the NEXT will be executed. If you wish to prematurely break out of the loop, issue a BREAK command.
You can also use gosub commands to no ill effect within a loop; thus, it is highly recommended that you compartmentalize what is inside a loop from what is outside of it.

Example:
Looping %0 from 1 to 10, add each value of the counter to %1.
for %0=1 to 10
add %1,%0
next

next /
page top / list / main

[Definition Block Only]( NScr, ONScr, ONScr-EN, PONS )
game

Game Start/End/Quit

game

Ends the definition block and begins the game.


*define / *start /
page top / list / main

[Definition Block Only]( ONScr-EN, PONS )
gameid

Special Mode Settings

';gameid' STR

STRName to use for the game save folder

Sets a name to use for a (P)ONScripter game savedata folder, which is filed in AppData (or similar applicable directory for non-Windows operating systems).
If a gameid is not specified, (P)Onscripter creates a savedata folder name from a hash of the game script.

*
Since a ;mode directive must be in the first line of a script, a ;gameid directive must be in the second line - no exceptions! (by Mion)
ONScripter Example:
Sets the game folder name to "ToHeart-Extra".
;gameid ToHeart-Extra

page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
getbtntimer

Image Buttons

getbtntimer %VAR

VARNumeric variable for elapsed time

Gets the amount of time (in milliseconds) spent in btnwait. You would use this to, say, restart the button timer in its proper place after a pause initiated by the player (by right-clicking, perhaps).


page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
getcselnum

System Customization

getcselnum %VAR

VARNumeric variable for total number of choices

Retrieves the total number of csel choices.

*
If you retrieve value %n with this command, be sure not to give a value greater than %n-1 as the choice index for cselbtn. (by senzogawa)
Example:
Assigns the total number of csel choices to %0.
getcselnum %0

csel / *customsel / getcselnum / cselgoto / getcselstr / selectbtnwait /
page top / list / main

[Program Block Only]( NScr2.34, ONScr, ONScr-EN, PONS )
getcselstr

System Customization

getcselstr $VAR,NUM

VARString variable for choice
NUMIndex number of the desired choice string

Acquires a character string given as a csel choice.

Example:
Grabs the 0th (first) choice string provided by csel and assigns it to $0.
getcselstr $0,0

csel /
page top / list / main

[Program Block Only]( NScr2.00, ONScr, ONScr-EN, PONS )
getcursor

Button Extensions

getcursor

Use this between btndef and btnwait commands.
The wait command will return -40 on up-arrow keypress, -41 on right-arrow, -42 on down-arrow, and -43 on left-arrow.


btndef / btntime / btntime2 / btnwait / btnwait2 / spclclk / usewheel / useescspc / getenter / gettab / getfunction / getpage / getinsert / getzxc /
page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
getcursorpos

System Customization

getcursorpos %VAR,%VAR

VARVariable for the text-window X-coordinate of the text cursor
VARVariable for the text-window Y-coordinate of the text cursor

Retrieves the text-window position of the text cursor - where a character would next be displayed.

Example:
Stores the text cursor position in (%0,%1).
getcursorpos %0,%1

textgosub / textbtnwait / texec /
page top / list / main

Ver.2.92[Program Block Only]( NScr2.92, ONScr-EN20100105 )
getcursorpos2

System Customization

getcursorpos2 %VAR,%VAR

VARVariable for the top-left pixel X-coordinate of the text character
VARVariable for the top-left pixel Y-coordinate of the text character

The same as getcursorpos, except that this command returns the pixel coordinates of the top-left of the last displayed text character.

Example:
Stores the top-left pixel coordinates of the last text character in (%0,%1).
getcursorpos2 %0,%1

getcursorpos / textgosub / textbtnwait / texec / texec2 /
page top / list / main

[Program Block Only]( NScr2.00, ONScr, ONScr-EN, PONS )
getenter

Button Extensions

getenter

Use this between btndef and btnwait commands.
The wait command will return -19 when the Enter key is pressed.


btndef / btntime / btntime2 / btnwait / btnwait2 / spclclk / usewheel / useescspc / getcursor / gettab / getfunction / getpage / getinsert / getzxc /
page top / list / main

[Program Block Only]( NScr2.00, ONScr, ONScr-EN, PONS )
getfunction

Button Extensions

getfunction

Use this between btndef and btnwait commands.
The wait command will return -21 to -32 for presses of keys F1 to F12.


btndef / btntime / btntime2 / btnwait / btnwait2 / spclclk / usewheel / useescspc / getcursor / getenter / gettab / getpage / getinsert / getzxc /
page top / list / main

[Definition/Program Block]( NScr, ONScr, ONScr-EN, PONS )
getini

Data Acquisition

getini $VAR,STR,STR,STR

VARString variable for the registry key/value result
STRAn INI filename
STRINI section name
STRINI key name

Opens an ini file and reads a variable.


page top / list / main

[Program Block Only]( NScr2.25, ONScr, ONScr-EN, PONS )
getinsert

Button Extensions

getinsert

Use this between btndef and btnwait commands.
The wait command will return -50 when the Insert key is pressed.


btndef / btntime / btntime2 / btnwait / btnwait2 / spclclk / usewheel / useescspc / getcursor / getenter / gettab / getfunction / getpage / getzxc /
page top / list / main

[Program Block Only]( NScr2.49, ONScr, ONScr-EN, PONS )
getlog

Log Mode Customization

getlog $VAR,NUM

VARResult variable for backlog string
NUMNumber of pages back

Retrieves the character string of the given backlog page, including newlines and ruby text data.
The second parameter gives the backlog page number, the same as provided to checkpage.

Example:
Sets $0 to the backlog string from %5 pages back
getlog $0,%5

checkpage / logsp /
page top / list / main

Ver.2.70[Program Block Only]( NScr )
getlogtext

Log Mode Customization

getlogtext $VAR,NUM

VARResult variable for backlog string
NUMNumber of pages back

Works the same as getlog, but intended to be used in combination with strsp.
Later versions of NScr (and ONScripter) have a strsp command that can work with getlog text, so this command is basically unnecessary.


getlog / strsp /
page top / list / main

[Program Block Only]( NScr2.94, ONScr-EN20091122 )
getmclick

Button Extensions

getmclick

Use this between btndef and btnwait commands, like with getfunction.
The wait command will return -70 if the middle mouse button is clicked.


btndef / btntime / btntime2 / btnwait / btnwait2 / spclclk / usewheel / useescspc / getcursor / getenter / gettab / getfunction / getpage / getinsert / getzxc /
page top / list / main

[Program Block Only]( NScr2.49, ONScr-EN20091122 )
getmouseover

System Customization

getmouseover

NUMMinimum button number to return mouseovers
NUMMaximum button number to return mouseovers

Set this between btndef and btnwait to collect button mouseovers during the wait.
It will only exit the btnloop for mouseovers of buttons within the given range, returning the applicable button number.

Example:
This will wait and return if any of buttons 0-9 are moused over.
btndef clear
getmouseover 0,9
btnwait %0

btndef / btnwait /
page top / list / main

[Program Block Only]( NScr1.97, ONScr, ONScr-EN, PONS )
getmousepos

Button Extensions

getmousepos %VAR,%VAR

VARresult numeric variable for mouse cursor X-coordinate
VARresult numeric variable for mouse cursor Y-coordinate

Sets the given result variables to the current mouse cursor coordinates.
Unlike clickpos, this command can collect cursor position without first waiting for a click.

Example:
Assign the current mouse cursor coordinates to %0 and %1.
getmousepos %0,%1

clickpos /
page top / list / main

[Program Block Only]( NScr, ONScr-EN20100105 )
getnextline

Cursor

getnextline %VAR,%VAR

VARNumeric variable for the text window X-coordinate of the following line
VARNumeric variable for the text window Y-coordinate of the following line

Retrieves the position of the start of the following line of text in the text window.

Example:
This puts the X and Y coordinates of the next line in %0 and %1.
getnextline %0,%1

page top / list / main

[Program Block Only]( NScr2.20, ONScr, ONScr-EN, PONS )
getpage

Button Extensions

getpage

Use this between btndef and btnwait commands.
The wait command will return -12 on PageUp keypress and -13 on PageDown.


btndef / btntime / btntime2 / btnwait / btnwait2 / spclclk / usewheel / useescspc / getcursor / getenter / gettab / getfunction / getinsert / getzxc /
page top / list / main

[Definition/Program Block]( NScr2.40, ONScr, ONScr-EN, PONS )
getparam

System Customization

getparam %VAR|$VAR|s%VAR|i%VAR[,...]

VARArgument storage variable

Takes the values provided as parameters to a user-defined command and assigns them, in order, to the given variables. For example, given the following subroutine call/getparam code:
defsub usercmd1
. . .
usercmd1 %14,$15,2,"blat"
. . .
*usercmd1
getparam %0,$0,%1,$1
After the getparam command, %0 will contain the numeric value of %14, $0 the string value of $15, %1 the numeric value 2, and $1 the numeric value "blat".

The s%VAR and i%VAR argument types allow for passing variables by reference - s%VAR for a string variable, i%VAR for a numeric variable.
For example, in this code:
defsub usercmd2
. . .
usercmd2 %14,$15
; same result as inc %14 : add $15,"/"
. . .
*usercmd2
getparam i%0,s%1
inc %%0 : add $%1,"/" : return
After the getparam command, %0 will contain the numeric value 14 and %1 the numeric value 15 - the reference numbers of the provided variables. The variables are then accessed or modified by referring to %%0 and $%1.

Finally, label names may be passed and accessed as string values, as follows:
defsub usergoto
. . .
usergoto *alabel
. . .
*usergoto
getparam $0
goto $0
; goto "*alabel" same as goto *alabel

*
Since NScripter treats all variables as global, it would be best to designate a set of variable numbers for subroutines only, and not use them within the main program, in order to keep "local" and "global" variables separate. For example, use %0-%49 as main program variables, and %50-%99 only within defsub routines.

defsub /
page top / list / main

[Definition/Program Block]( NScr )
getreg

Data Acquisition

getreg $VAR,STR,STR

VARString variable for the registry key/value result
STRA registry key
STRA registry variable

Opens the Windows registry and queries for a variable.
Will search only in HKEY_CURRENT_USER.

Example:
getreg $0,"software\leaf\toheart","datadir"

page top / list / main

[Definition/Program Block]( NScr2.03, ONScr, ONScr-EN, PONS )
getret

Plugins/Archives

getret %VAR|$VAR

VARVariable to hold either a numeric or string value returned by a DLL

Retrieves a value returned from a DLL call via exec_dll. Numeric and string values may be collected separately.
This command may also be used to retrieve a value returned by textfield or a call to layermessage.


exec_dll / textfield / layermessage /
page top / list / main

[Program Block Only]( NScr2.60, ONScr, ONScr-EN )
getsavestr

Save/Load

getsavestr $VAR,NUM

VARResult string variable
NUMSavefile number

Retrieves the character string that was stored with a particular save number using savegame2.

Example:
Gets the string stored with Save Game 12 by savegame2 and assigns it to $1.
getsavestr $1,12

savegame2 /
page top / list / main

[Program Block Only]( NScr2.25, ONScr, ONScr-EN, PONS )
getscreenshot

Screenshot

getscreenshot NUM,NUM

NUMScreenshot image width
NUMScreenshot image height

Collects a screenshot. This only stores the image in memory - you will need to call savescreenshot to save it to a file.

Example:
Grabs a screenshot of size 160x120.
getscreenshot 160,120

savescreenshot / savescreenshot2 / deletescreenshot /
page top / list / main

[Program Block Only]( NScr2.49, ONScr-EN20091230 )
getskipoff

System Customization

getskipoff

Set this between btndef and textbtnwait to collect skipoff keystrokes during the wait. textbtnwait will return -60 if skip mode off is requested, -61 if auto mode off.

Example:
This will wait for user input and call *clearskipicon if skip mode off was requested.
btndef clear
getskipoff
textbtnwait %0
if %0=-60 gosub *clearskipicon

btndef / textbtnwait /
page top / list / main

[Program Block Only]( NScr2.61, ONScr, ONScr-EN, PONS )
getspmode

Image Display

getspmode %VAR,NUM

VARResult numeric variable
NUMSprite number

This returns 1 if the given sprite is displayed, 0 if the sprite is hidden.

Example:
Sets %2 to 1 if Sprite 10 is displayed, 0 if it is hidden.
getspmode %2,10

lsp / lsph /
page top / list / main

[Program Block Only]( NScr2.53, ONScr, ONScr-EN, PONS )
getspsize

Image Display

getspsize NUM,%VAR,%VAR[,%VAR]

NUMSprite number
VARResult numeric variable for sprite width
VARResult numeric variable for sprite height
VAROptional result numeric variable for sprite cell

Retrieves the size of the given sprite.
This will also return the sprite cell number if the optional variable is provided.

*
The optional cell variable argument was added in ver2.54.
Example:
Grabs the size of Sprite 0 and assigns %0 its width, %1 its height, and %2 its current cell.
getspsize 0,%0,%1,%2

page top / list / main

[Program Block Only]( NScr2.00, ONScr, ONScr-EN, PONS )
gettab

Button Extensions

gettab

Use this between btndef and btnwait commands.
The wait command will return -20 when the Tab key is pressed.


btndef / btntime / btntime2 / btnwait / btnwait2 / spclclk / usewheel / useescspc / getcursor / getenter / getfunction / getpage / getinsert / getzxc /
page top / list / main

[Definition/Program Block]( NScr2.46, ONScr, ONScr-EN, PONS )
gettag

Pretext Tags

gettag $VAR|%VAR[,...]

VARNumeric or string variable to receive a tag data element

This command is called from within a pretextgosub routine in order to extract data from a pretext tag.
It is not necessary to use split - the gettag command itself will do the job, delimiting on "/".
If there is no tag data for a variable (no tag was provided, or there are more parameters to gettag than elements in the tag), then the variable in question is given a null value: "" for strings, 0 for numerics.

If a tag [太郎/0001.wav] is processed via the command gettag $0,$1, then as a result $0 will be "太郎" and $1 will be "0001.wav".
If gettag $0,$1 is called but no tag was provided, then as a result both $0 and $1 will be "".

Pretext tag processing is especially intended for handling names and voice files for dialog text.

Example:
Processes a pretext tag, assigning the first two elements to $0 and $1.
gettag $0,$1

[] / pretextgosub /
page top / list / main

[Program Block Only]( NScr2.72, ONScr, ONScr-EN, PONS )
gettaglog

Log Mode Customization

gettaglog $VAR,NUM

VARResult variable for backlog string
NUMNumber of pages back

Retrieves the last pretext tag of the given backlog page.
This can be convenient for custom backlogs in scripts that provide character name and voice file via tags.

Returns the empty string if no pretext tag was available.
Note that this command does not split the tag and populate variables automatically, like gettag does; such functionality may be added later.


gettag /
page top / list / main

[Program Block Only]( NScr2.00, ONScr, ONScr-EN, PONS )
gettext

Text Window

gettext VAR

VARString variable to hold text window contents

Retrieves the text currently displayed in the text window.

Example:
Retrieves the contents of the text window and stores in $0.
gettext $0

page top / list / main

[Program Block Only]( NScr2.65, ONScr-EN )
gettextbtnstr

Text Buttons

gettextbtnstr $VAR,NUM

VARResult string variable
NUMTextbutton number

Retrieves the text of the textbutton with the given number.
Returns a value of "" if the textbutton doesn't exist.

Example:
Gets the text of textbutton number 12 and assigns it to $0.
gettextbtnstr $0,12

<> /
page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
gettimer

Wait/Timer

gettimer %VAR

VARCurrent value of the internal timer (msec)

Retrieves the current state of the internal timer.
This returns a value in milliseconds corresponding to the amount of time that has elapsed since resettimer was last called.


page top / list / main

[Program Block Only]( NScr1.97, ONScr, ONScr-EN, PONS )
getversion

Data Acquisition

getversion %VAR

VARNumeric variable for the current NScr version

Gets the current version string, as a 3-digit number: for instance. version 1.90 would be returned as 190.


page top / list / main

Ver.2.54[Program Block Only]( NScr )
getwindowsize

Data Acquisition

getwindowsize %VAR,%VAR

VARNumeric variable for window width
VARNumeric variable for window height

Retrieves the size of the program window (the drawing area, not including the menubar). By default, the return values are 640 and 480.

Example:
Assign the screen window width to %0 and height to %1.
getwindowsize %0,%1

page top / list / main

[Program Block Only]( NScr2.25, ONScr, ONScr-EN, PONS )
getzxc

Button Extensions

getzxc

Use this between btndef and btnwait commands.
The wait command will return -51 on Z keypress, -52 on X, and -53 on C.


btndef / btntime / btntime2 / btnwait / btnwait2 / spclclk / usewheel / useescspc / getcursor / getenter / gettab / getfunction / getpage / getinsert /
page top / list / main

[Definition Block Only]( NScr, ONScr, ONScr-EN, PONS )
globalon

File Access Logs/Global Variables

globalon

Turns on the use of global variables. If you enable this or filelog, nscr.exe cannot be run from write-protected media.


page top / list / main

[Definition/Program Block]( NScr, ONScr, ONScr-EN, PONS )
gosub

Jumps

gosub LABEL

LABELJump destination

Jumps to and begins execution at the given label name.
Jumps back to the command directly after the original gosub when a return command is encountered.


return /
page top / list / main

[Definition/Program Block]( NScr, ONScr, ONScr-EN, PONS )
goto

Jumps

goto LABEL

LABELJump destination

Jump to the given label name. (Can cause spaghetti code.)


page top / list / main

[Definition/Program Block]( PONS )
h_breakstr

PONScripter Commands

h_breakstr STR

STRBreak characters

h_breakstr basic

ENUMKeyword for the standard linebreaking characters

Specifies characters that allow linebreaks. Equivalent to the pbreakstr command.

PONScripter Example:
Sets space, comma and hyphen as break characters.
h_breakstr ^ ,-^

pbreakstr /
page top / list / main

[Definition/Program Block]( PONS )
h_fontstyle

PONScripter Commands

h_fontstyle STR

STRfont style tag

Sets the default text styling. Equivalent to the command pfontstyle.

PONScripter Example:
Displays text in italic display font (slot 5).
h_fontstyle ^si^
^Here is a page of italic text.\
^And it's still italic!\
h_fontstyle ^d^ ;back to regular style

pfontstyle /
page top / list / main

[Definition/Program Block]( PONS )
h_indentstr

PONScripter Commands

h_indentstr STR

STRIndent characters

h_indentstr basic

ENUMKeyword for the standard indenting characters

Specifies characters that will set an indent. Equivalent to the pindentstr command.

PONScripter Example:
Sets quote marks (undirected and left) as indenting characters.
h_indentstr ^"'‘“^

pindentstr /
page top / list / main

[Definition/Program Block]( PONS )
h_ligate

PONScripter Commands

h_ligate STR,NUM|STR

STRShortcut matching text
NUMUnicode codepoint for shortcut result (if numeric)
STR(Unicode) char for shortcut result (if string)

h_ligate STR,remove

STRShortcut matching text
ENUMKeyword to remove the defined matching shortcut

h_ligate {none|default|basic|punctuation|f_ligatures|specials|all}

ENUMKeyword for a preset shortcut set

Adds or removes shortcut sequences. Equivalent to the command pligate.


pligate /
page top / list / main

[Definition/Program Block]( PONS20061124 )
h_mapfont

PONScripter Commands

h_mapfont NUM,STR[,STR]

NUMFont slot (0-7)
STRFont filename
STRFont metrics file (Type 1 fonts only)

Maps a font file to the given font slot. Equivalent to the command pmapfont.

PONScripter Example:
Maps font slot 0 to "myprettyfont.ttf".
h_mapfont 0,"myprettyfont.ttf"

pmapfont /
page top / list / main

[Definition/Program Block]( PONS20061124 )
h_rendering

PONScripter Commands

h_rendering {none|full|light},{integer|float}[,{light|normal}]

ENUMHinting (either none, full, or light)
ENUMPositioning (either integer or float)
ENUMOptional Freetype rendering mode (light or normal)

Configures the Freetype text rendering mode. Equivalent to the command prendering.


prendering /
page top / list / main

[Program Block Only]( NScr2.25, ONScr, ONScr-EN, PONS )
humanorder

Image Display

humanorder STR,EFFECT

STRStanding image positions in priority order, e.g. "lcr"
EFFECTTransition effect to use during image priority change

Specifies the overlapping priority for standing images.

Example:
Sets the standing picture priorities to display right atop center atop left.
humanorder "rcl",1

humanz /
page top / list / main

Ver.(undoc)[Definition/Program Block]( NScr2.03, ONScr-EN20091010 )
humanpos

Image Display

humanpos NUM,NUM,NUM

NUMStandard X-coordinate for "l" standing image position
NUMStandard X-coordinate for "c" standing image position
NUMStandard X-coordinate for "r" standing image position

Specifies the standard x-coordinates for standing image positions "l", "c", and "r".
The center vertical axis of a standing image will be matched to the coordinates given by this command.
The default values are 160, 320, and 480.

*
This command was allowed in the program block since ver2.92.

ld /
page top / list / main

[Definition Block Only]( NScr, ONScr, ONScr-EN, PONS )
humanz

Image Display

humanz NUM

NUMSprite number right above the standing image layer

Designates the image priority when sprites and standing pictures overlap (the z-order).
The sprite of the given number will be drawn immediately above the standing images.

The default value is 25.


ld / windowback /
page top / list / main

[Definition/Program Block]( NScr, ONScr, ONScr-EN, PONS )
if

Conditionals/Loops

if CONDITION[{&&,&} CONDITION[...]] SENTENCE

CONDITIONRelative operation, check instruction, or some other truth-value returning expression
SENTENCECommand(s) to execute if the condition was True

The commands following the if statement are executed if the conditional statement(s) evaluate true; if you want branch control in which a command executes if a conditional statement is false, use notif.
The conditions compare numerical values, else you can employ fchk.
& and && are logical 'ands', and are equivalent to each another.

Conditions:
(numerical variable) {>,<,=,>=,<=,==,!=,<>} (numeric variable)
- or -
fchk (character string)

<, >, =, >=, and <= should already be known to you.
== and = are identical, as are != and <>.
fchk returns true when the image whose name corresponds to the character string is being used.

Example:
If %0 equals 1, do a 1/2 second horizontal screen shake.
if %0=1 quakex 2,500 ;basic conditional form
Example:
End the program if %0 equals 1 and %2 equals 5.
if %0=1 && %2=5 end ;more complex form - both conditionals must be true
Example:
If %0 equals 2, assign 1 to %1 and then skip the next 2 lines.
if %0=2 mov %1,1:skip 2 ;execute multiple commands sep. by ':'

notif /
page top / list / main

[Definition/Program Block]( NScr, ONScr, ONScr-EN, PONS )
inc

Variable Manipulation/Calculations

inc %VAR

VARNumeric variable to increment

Increments the value of the numerical variable by one.


page top / list / main

[Program Block Only]( NScr2.46, ONScr, ONScr-EN, PONS )
indent

Pretext Tags

indent NUM

NUMThe number of (fullwidth) characters to indent a continuing line

When continuing a line after a line break, it will indent by the amount specified via this command.
For example, a pretextgosub routine could use this command to add indenting for a line of dialog, but then set the indent level to 0 for regular text.

Example:
Indent continuing lines by 2 (fullwidth) spaces
indent 2

pretextgosub /
page top / list / main

[Program Block Only]( NScr )
input

Miscellaneous

input $VAR,STR,STR,NUM,NUM

VARInput result string variable
STRMessage to display
STRDefault input string
NUMMaximum input length
NUMForce double-byte input (0: allow half-width, 1: full-width only)

Presents a text input box, much like inputstr; however, input must have a default character string.
Depending on whether the double-byte flag is 0 or 1, you can force your user to input 2-byte characters or not.

*
(P)ONScripter "supports" this command by assigning the default string to the result variable.

inputstr / inputnum / textfield /
page top / list / main

Ver.(undoc)[Program Block Only]( NScr )
inputnum

Miscellaneous

inputstr %VAR,STR[,NUM,NUM,NUM,NUM]

VARInput result numeric variable
STRMessage to display
NUMWindow width (optional)
NUMWindow height (optional)
NUMInput area width (optional)
NUMInput area height (optional)

Creates an input dialog that assigns the user's input to the given numeric variable.
The character string serves as the dialog message text.
The last 4 arguments may be omitted; in order they are (window size x), (window size y), (text input window size x), (text input window size y).


input / inputstr / textfield /
page top / list / main

[Program Block Only]( NScr )
inputstr

Miscellaneous

inputstr $VAR,STR,NUM,NUM[,NUM,NUM,NUM,NUM]

VARInput result string variable
STRMessage to display
NUMMaximum input length
NUMForce double-byte input (0: allow half-width, 1: full-width only)
NUMWindow width (optional)
NUMWindow height (optional)
NUMInput area width (optional)
NUMInput area height (optional)

Creates an input dialog that captures all input to the character variable.
The character string serves as the dialog message text.
The first number is the max input length, the second (0 or 1) determines whether the user is forced to enter 2-byte characters or not.
The last 4 arguments may be omitted; in order they are (window size x), (window size y), (text input window size x), (text input window size y).


input / inputnum / textfield /
page top / list / main

Ver.1.98[Definition Block Only]( NScr )
insertmenu

Window Menubar

insertmenu STR,NAME[,NUM]

STRCharacter string displayed for menu item
NAMEMenu function code
NUMSubmenu level (optional)

Adds a menubar item. It always adds at the head position.

Example:
Creates a full menu, arranged differently from the default.
insertmenu "終了",END
insertmenu "バージョン情報",VERSION
insertmenu "次の選択肢に進む",SKIP
insertmenu "オートモード",AUTO
insertmenu "環境設定",SUB
;SUB indicates the top of a submenu, which will contain following items of deeper level.
;This one contains everything that follows.
insertmenu "フォント",FONT,1
insertmenu "ウェーブ",SUB,1
insertmenu "ON",WAVEON,2
insertmenu "OFF",WAVEOFF,2
insertmenu "ボリューム",DWAVEVOLUME,2
insertmenu "テキスト",SUB,1
insertmenu "遅い",TEXTSLOW,2
insertmenu "普通",TEXTMIDDLE,2
insertmenu "速い",TEXTFAST,2
insertmenu "画面",SUB,1
insertmenu "フルスクリーン",FULL,2
insertmenu "ウィンドウ",WINDOW,2
insertmenu "CD-DA",SUB,1
insertmenu "ON",CDON,2
insertmenu "OFF",CDOFF,2
insertmenu "クリック設定",SUB,1
insertmenu "普通",CLICKDEF,2
insertmenu "ページごと",CLICKPAGE,2

killmenu / resetmenu / deletemenu /
page top / list / main

[Definition Block Only]( NScr, ONScr, ONScr-EN, PONS )
intlimit

Variable Manipulation/Calculations

intlimit NUM,NUM,NUM

NUMNumeric variable number
NUMMinimum allowed value
NUMMaximum allowed value

Restricts the value of an numerical variable. If it exceeds the set maximum, it becomes reset to the set maximum; if it goes below the set minimum, it resets to the set minimum.
In order, the numbers in the command are: numerical variable number, min value, max value.

Example:
This sets the allowed range for numeric variable 0 to be 10 to 20.
intlimit 0,10,20

page top / list / main

[Program Block Only]( NScr1.97, ONScr, ONScr-EN, PONS )
isdown

Button Extensions

isdown %VAR

VARresult numeric variable (1: pressed, 0: not pressed)

Sets the result variable based on whether the left mouse button is pressed down.
It returns 1 if pressed, 0 if not pressed.

Example:
This prints a line of "0"s while the left mouse button is pressed, moving to the next line when the button is released. It exits on right-click.
*waitloop
btnwait %0
if %0=0 goto *onlclick
end
*onlclick
isdown %1
if %1=1 puttext "0/":goto *onlclick
puttext ""
goto *waitloop

btndown /
page top / list / main

[Program Block Only]( NScr2.03, ONScr-EN )
isfull

Window Menubar

isfull %VAR

VARResult numeric variable (0: windowed, 1: full-screen)

Retrieves the current full-screen status (full or windowed).

Example:
This checks whether the program is in fullscreen mode - if not, it enters fullscreen mode, otherwise it goes to windowed mode.
isfull %0
if %0==0 menu_full
notif %0==0 menu_window

menu_full / menu_window /
page top / list / main

[Program Block Only]( NScr2.49, ONScr, ONScr-EN, PONS )
ispage

System Customization

ispage %VAR

VARReturn numeric variable

Within a textgosub routine, this will set the return variable to 1 if the current clickwait is for a new page, 0 if not.

Example:
Retrieves the clickwait type and assigns it to %0.
ispage %0

textgosub /
page top / list / main

[Program Block Only]( NScr2.20, ONScr, ONScr-EN, PONS )
isskip

System Customization

isskip %VAR

VARReturn numeric variable (0: no skip, 1: skip mode, 2: auto mode)

Retrieves the current skip mode setting. Returns 0 if no skip, 1 if skip to next choice mode, and 2 if auto mode.

*
If currently in kidoku (skip to unread) mode, this will return 0 at unread sentences. (by senzogawa)
*
ONScripter-EN will return 4 if page-at-once mode is set. (by Mion)

page top / list / main

[Definition/Program Block]( NScr, ONScr, ONScr-EN, PONS )
itoa

Variable Manipulation/Calculations

itoa $VAR,NUM

VARString result variable
NUMNumeric value to convert

Converts a number into a (half-width digit) character string. Similar to the itoa function in C.

Example:
Populates $0 with "120", and $1 with the string conversion of %2.
itoa $0,120
itoa $1,%2

page top / list / main

[Definition/Program Block]( NScr2.49, ONScr, ONScr-EN, PONS )
itoa2

Variable Manipulation/Calculations

itoa $VAR,NUM

VARString variable for the fullwidth result
NUMNumeric value to convert

This is the same as itoa, except that it converts a number into a full-width digit character string, for more convenient Japanese text display.

Example:
The numeric value of %4 is converted to a fullwidth string, which is then assigned to $0.
itoa2 $0,%4

itoa /
page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
jumpb

Jumps

jumpb

Return to the last ~ symbol.

*
Be careful about "~" chars in comments and such around this command. (by senzogawa)

page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
jumpf

Jumps

jumpf

Jumps to the next appearance of a ~ symbol. Use this when it's bothersome to use a proper label. However, as you can't really do deeply nested control with this kind of command, try not to overuse it.

*
Be careful about "~" chars in comments and such around this command. (by senzogawa)
Example:
jumpf
;I am a line that gets skipped.
~
;I am a line that isn't skipped.

page top / list / main

[Program Block Only]( NScr1.97, ONScr, ONScr-EN, PONS )
kidokumode

Skip Mode

kidokumode NUM

NUMMode setting (0: regular skip, 1: skip to unread)

Toggles between regular kidoku skip (stops at first unread text) and forced "skip to next choice" mode.


kidokuskip /
page top / list / main

[Definition Block Only]( NScr, ONScr, ONScr-EN, PONS )
kidokuskip

Skip Mode

kidokuskip

If you use this command, you can enter "skip to next choice" mode. The script will keep track of previously-read text, so that whenever you encounter unread text, Skip Mode will automatically terminate.
Kidoku (read text) data is stored in the file "kidoku.dat".


kidokumode /
page top / list / main

[Definition Block Only]( NScr )
killmenu

Window Menubar

killmenu NUM

NUMPosition of erased menu item

This deletes menu items, counted from left to right.
0 is the leftmost item number, with each item to the right incrementing in number.
Once you have deleted a menu item, the numbers for all menu items after it shift down one, so please be careful.

*
For some reason, menu item "CD-DA" always starts with number 7.
Similarly, menu items "Version Info" and "Exit" start as numbers 8 and 9, respectively.

page top / list / main

[Program Block Only]( NScr2.73, ONScr-EN )
kinsoku

Text Display

kinsoku {on,off}

ENUMon: use kinsoku rules; off: ignore kinsoku rules

kinsoku on causes "kinsoku" (forbidden start/end character) rules to be enforced, while kinsoku off causes those rules to be ignored.

*
This works with both regular text display and the strsp command. (by senzogawa)

strsp /
page top / list / main

Ver.(undoc)[Program Block Only]( NScr2.20 )
labelexist

Miscellaneous

labelexist %VAR,LABEL

VARResult for label check (1: exists, 0: not found)
LABELLabel to check for

Assigns 1 to the given variable if the label exists, 0 if not.

Example:
Checks if "*message" routine exists, and calls it if so.
labelexist %0,*message
if %0==1 gosub *message

goto / gosub /
page top / list / main

[Definition Block Only]( NScr, ONScr, ONScr-EN, PONS )
labellog

File Access Logs/Global Variables

labellog

This command behaves somewhat like filelog, except in this case it keeps a record of labels.
Whenever a goto, gosub or similar command is called, a record of which label was called will be stored if labellog was specified.


page top / list / main

[Definition/Program Block]( ONScr-EN20080823 )
language

Text Display

language {english/japanese}

NAMEenglish: prefer English, japanese: prefer Japanese

This sets the preferred text display language in ONScripter-EN, more-or-less replacing the FORCE_1BYTE_CHAR compilation option.
The right-click menu will use the preferred language for display messages, and text display will take preferred language, kinsoku settings, and whether a chunk of text contains single-byte and/or double-byte characters into account when performing linebreaks.
This command can be used within either the define or program block, and may be set by default from the command line or depending on the executable filename (i.e. "onscripter-en.exe" is assumed to prefer English).

Note that ENABLE_1BYTE_CHAR must be set at ONScripter compile time to be able to use language english.

ONScripter Example:
Sets preferred language to Japanese.
language japanese

page top / list / main

[Program Block Only]( NScr2.03, ONScr-EN20090411 )
layermessage

Plugins/Archives

setlayer NUM,STR

NUMLayer number (defined using setlayer)
STRMessage to send to the layer

An arbitrary character string is sent to the specified layer.
This command can be useful for achieving various effects within a layer.
To use this command, a layer plugin should export a function with this declaration:
BOOL Message(char *message, int *returnint, char *returnstr);


setlayer /
page top / list / main

[Definition/Program Block]( NScr, ONScr, ONScr-EN, PONS )
lchk

Conditionals/Loops

lchk LABEL

LABELLabel to confirm

Like fchk, this command is used in if statement conditionals. It checks to see whether the given label has been used/accessed.
Any of the following are allowed syntax:
lchk *test
lchk "*test"
lchk $0


page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
ld

Image Display

ld {l,c,r},STR,EFFECT

ENUMstanding pic position (l: left, c: center, r: right)
STRImage filename
EFFECTEffect for displaying standing picture

Loads a standing picture. Use l for left, r for right, c for center.
The character string is the image filename; the image tag is automatically generated as well.


cl / effect / humanz /
page top / list / main

[Definition/Program Block]( NScr1.99, ONScr, ONScr-EN, PONS )
len

Variable Manipulation/Calculations

len %VAR,STR

VARLength result variable
STRCharacter string to measure

Finds the length of the given character string.

Example:
Sets %0 to the length of $0
len %0,$0

mid /
page top / list / main

[Definition Block Only]( NScr1.99, ONScr, ONScr-EN, PONS )
linepage

Click Wait

linepage

Setting this causes new-page clickwaits to occur at the end of each line, even if you do not specify it using '\'.
This means that you never have to manually specify a line/page feed.
Please take care if you decide to use @, \, or clickstr along with this command.


@ / \ / clickstr / _ /
page top / list / main

[Definition/Program Block]( NScr2.65, ONScr-EN )
linkcolor

Text Buttons

linkcolor COLOR,COLOR

COLORTextbutton standard color
COLORTextbutton mouseover color

Sets the button colors for textbuttons.
The default colors are yellow and cyan.

Example:
Sets the standard textbutton color to #FFFF88 and the mouseover color to #88FF88.
linkcolor #FFFF88,#88FF88

<> /
page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
loadgame

Save/Load

loadgame NUM

NUMSavefile number

Loads the save data corresponding to the given save number. This does not prompt for confirmation, so be careful.
This command gives no error indication if savefile cannot be loaded, and simply proceeds to the next command without stopping.


page top / list / main

[Definition Block Only]( NScr2.40, ONScr, ONScr-EN, PONS )
loadgosub

Save/Load

loadgosub LABEL

LABELSubroutine to call upon game load

Specifies a routine to call immediately after a game is loaded and its save state has been restored.
Please take care when scripting to be sure that all saveable points will work properly when restored with this loadgosub routine.
This command was created especially to handle games that use plugins for music reproduction.

*
This command is necessary in NScr if a plugin is being used for music playback.
Example:
Specifies that the script should call *loadlb whenever a game is loaded.
loadgosub *loadlb

page top / list / main

[Definition/Program Block]( PONS20091013 )
localestring

PONScripter Commands

localestring {message_reset_confirm|message_end_confirm|message_yes|message_no|message_empty|message_space} STR

ENUMLocale string identifier
STRLocale string

localestring {days|months|am_pm|digits} STR,...

ENUMLocale string list identifier
STRLocale string list item(s)

localestring {message_save_label|message_save_exist|message_save_confirm|message_load_confirm} STR

ENUMSave/load related locale string identifier
STRSave/load related locale string

Changes a string or set of strings related to the default right-click menu.
There are three separate types of localestring commands: standard dialog items, localization lists, and processed dialog items.

1) Standard dialog items - localestrings meant to be displayed exactly as provided, except for parsing any ~ formatting tags.
message_reset_confirm (default: "Return to Title Menu?")
- confirmation message after requesting a game reset
message_end_confirm (default: "Quit?")
- confirmation message after requesting to exit the game
message_yes (default: "Yes")
- affirmative response to confirmation message
message_no (default: "No")
- negative response to confirmation message
message_space (default: " ")
- used for displaying spaces in processed items
message_empty (default: "-")
- used for filling in unused slots in the Save/Load menu

2) Localization lists - sequences of localestrings related to date, time, and numbers, that are used when filling in processed dialog items. Items of a sequence are not required to be the same length.
days (default: "Sun","Mon","Tue","Wed","Thu","Fri","Sat")
- days of the week, starting with Sunday; must be exactly 7 comma-separated strings
months (default: "Jan","Feb","Mar","Apr","May","Jun","Jul","Aug","Sep","Oct","Nov","Dec")
- months of the calendar year, starting with January; must be exactly 12 comma-separated strings
am_pm (default: "AM","PM")
- distinguish between before-noon and after-noon times in 12-hour time systems; must be exactly 2 comma-separated strings
digits (default: "0","1","2","3","4","5","6","7","8","9")
- decimal digits starting with 0; must be exactly 10 comma-separated strings

3) Processed dialog items - localestrings parsed for special character sequences related to saved games and the Save/Load menu save slots.
message_save_label (default: "%s%n")
- used to display the label and number of a slot in the Save/Load menu
message_save_exist (default: "%b %d%i %-H:%i%M")
- used to display the date and time information of a saved game
message_save_confirm (default: "Save in %s%n?")
- confirmation message for saving the current game in a particular slot of the Save/Load menu
message_load_confirm (default: "Load from %s%n?")
- confirmation message for loading a game from a particular slot of the Save/Load menu

Processed dialog character sequences
The syntax of character sequences parsed within save/load related items comes largely from the UNIX date format syntax.
%% - a literal '%'
%s - Save/Load menu savefile slot heading (set via savename)
%n - Savefile number
%a - day of the week, retrieved from days localization list
%b - month of the year, retrieved from months localization list
%d - date of the month ('01'-'31')
%H - hour, 24-hour system ('00'-'23')
%I - hour, 12-hour system ('01'-'12')
%M - minute ('00'-'59')
%p - AM/PM time indicator, retrieved from am_pm localization list
%S - second ('00'-'59')
%Y - year (full)
%y - year (last 2 digits)

The following optional flags may follow the % in the previous code sequences:
- (hyphen) - do not pad
_ (underscore) - pad with spaces
0 (zero) - pad with zeroes
After the flag, if any, may come a decimal number specifying field width, and then an optional O to indicate that the locale's digits should be used. For example, "%_4OH:%M" will display the hour with field width 4, padded with spaces, and using locale digits: " 8:45".

There are also two sequences used specifically within message_save_exist for formatting Save/Load menu slots:
%i - Indent point
%t - Tab area

An indent point is a location within the slot text where all non-empty slots must line up with each other. For example, with the slot text "%H:%i%M", the colons in the 'hour:minute' time will line up across the entire list of slots.

In order to make the indent points line up, whitespace is added to the beginning of the string (or just after the last indent point in the string). If one of those points shouldn't have whitespace, the whitespace tab area can be specified with %t. For example, in the text "%H:%i%M %t(%a)%i" ('hour:minute (weekday)'), setting the tab just before the '(weekday)' prevents whitespace after the colon in the ':minute' part.

Try the following examples of localestring settings.

PONScripter Example:
Use French abbreviated months and days of the week.
localestring months "janv.","févr.","mars","avr.","mai","juin","juill.","août","sept.","oct.","nov.","déc."
localestring days "Dim","Lun","Mar","Mer","Jeu","Ven","Sam"
PONScripter Example:
Use fullwidth Japanese digits and space.
localestring digits "0","1","2","3","4","5","6","7","8","9"
localestring message_space " "
PONScripter Example:
Use Russian confirmation messages and responses.
localestring message_save_confirm "Сохранить %s%n?"
localestring message_load_confirm "Загрузить %s%n?"
localestring message_reset_confirm "Выйти в главное меню?"
localestring message_yes "Да"
localestring message_no "Нет"
PONScripter Example:
Display savefile slot with the default format.
localestring message_save_exist "%b %d%i %_H:%i%M"
;e.g. "Feb 06  0:45"
PONScripter Example:
Other savefile slot formats.
localestring message_save_exist "%Y/%m/%d  %H:%M"
;e.g. "2008/02/06  00:45"
localestring message_save_exist "%m/%d/%Y %i%I:%M %i%p"
;e.g. "02/06/2008   12:45  AM"
localestring message_save_exist "%a, %b %d, %I:%M %p"
;e.g. "Wed, Feb 6, 12:45 AM"

savename /
page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
locate

Text Display

locate NUM,NUM

NUMHorizontal position (in full-width chars)
NUMVertical position (in chars)

Changes the (absolute) position of text insertion within the text window.
Note that the position values are in text metrics, not pixels.


page top / list / main

[Program Block Only]( NScr2.49, ONScr, ONScr-EN, PONS )
logsp

Log Mode Customization

logsp NUM,STR,NUM,NUM[,COLOR[,COLOR[,...]]]

NUMSprite number
NUMText string (provided by getlog)
NUMTop-left X-coordinate
NUMTop-left Y-coordinate
COLORLog Text color (default: #FFFFFF)
COLORLog Text sprite additional cell color (optional)

Creates a sprite from backlog text retrieved via getlog, positioned at the given coordinates.
If no color is specified, the sprite text will be white (#FFFFFF). If only one color is specified, then the sprite will have just one cell - provide additional colors if you need more cells, like for use as a button.

Example:
Creates Sprite 8 from backlog text in $0, displayed at (60,90)
logsp 8,$0,60,90
Example:
Creates Sprite 8 from backlog text in $0, displayed at (60,90), with color #FFFF88
logsp 8,$0,60,90,#FFFF88
Example:
Creates Sprite 8 from backlog text in $0, displayed at (60,90), with Cell 0 of color #888888 and Cell 1 of color #FFFF88
logsp 8,$0,60,90,#888888,#FFFF88

getlog / logsp2 /
page top / list / main

[Program Block Only]( NScr2.49, ONScr, ONScr-EN, PONS )
logsp2

Log Mode Customization

logsp2 NUM,STR,NUM,NUM,NUM,NUM,NUM,NUM[,COLOR[,COLOR[,...]]]

NUMSprite number
NUMText string (provided by getlog)
NUMTop-left X-coordinate
NUMTop-left Y-coordinate
NUMText font width
NUMText font height
NUMText spacing X
NUMText spacing Y
COLORLog Text color (default: #FFFFFF)
COLORLog Text sprite additional cell color (optional)

Same as logsp, but allows specifying the text character size.

Example:
Creates Sprite 2 from backlog text in $0 with fullwidth char size 17x17, no horizontal spacing, and 1 pixel vertical spacing, displayed at (150,20)
logsp2 2,$0,150,20,17,17,0,1

getlog / logsp /
page top / list / main

[Definition Block Only]( NScr, ONScr, ONScr-EN, PONS )
lookbackbutton

Log Mode

lookbackbutton STR,STR,STR,STR

STRPage-up active button image
STRPage-up inactive button image
STRPage-down active button image
STRPage-down inactive button image

Loads buttons for use in Log Mode.
By default, these are "uoncur.bmp","uoffcur.bmp","doncur.bmp","doffcur.bmp".
The images must be of the same size or else this command will fail.
Log mode buttons cannot be animated.
The button to enter log mode is located at the upper right of the text window. Its position cannot be changed once set, so please make sure you set it right the first time around.


page top / list / main

[Definition Block Only]( NScr, ONScr, ONScr-EN, PONS )
lookbackcolor

Log Mode

lookbackcolor COLOR

COLORLog Mode text color

Sets the text color for Log Mode.
The color is an #rrggbb hex value, like that used in HTML.


page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
lookbackflush

Log Mode

lookbackflush

Flushes the Log Mode buffer.


page top / list / main

[Program Block Only]( NScr )
lookbackoff

Log Mode

lookbackon

Stops collecting Log Mode data; data collection can be restarted with lookbackon.


lookbackon /
page top / list / main

[Program Block Only]( NScr )
lookbackon

Log Mode

lookbackon

Turns on accumulation of Log Mode data; use this to return regular log buffering after turning it off with lookbackoff.


lookbackoff /
page top / list / main

[Definition Block Only]( NScr1.99, ONScr, ONScr-EN, PONS )
lookbacksp

Log Mode

lookbacksp NUM,NUM

NUMPageUp button sprite number
NUMPageDown button sprite number

Uses the given sprites as lookback buttons instead of the defaults.

Example:
Uses Sprites 2 and 3 as the Log Mode Pageup and Pagedown buttons.
lookbacksp 2,3

lookbackbutton /
page top / list / main

[Definition Block Only]( NScr, ONScr, ONScr-EN, PONS )
lookbackvoice

Log Mode

lookbackvoice STR

STRPaging sound filename

Designates a WAV file to play back when the pageup/pagedown button is clicked in Log Mode.


page top / list / main

[Program Block Only]( NScr2.03, ONScr, ONScr-EN, PONS )
loopbgm

Music/SFX Playback

loopbgm STR,STR

STRIntro music filename
STRLooped music filename

Plays the first music file, then once it's finished, loops the second file until stopped.

Example:
First plays "bgm_s.wav" then loops "bgm_l.wav" ("bgm_s.wav" -> "bgm_l.wav" -> "bgm_l.wav" -> ...)
loopbgm "bgm_s.wav","bgm_l.wav"

loopbgmstop /
page top / list / main

[Program Block Only]( NScr2.03, ONScr, ONScr-EN, PONS )
loopbgmstop

Music/SFX Playback

loopbgmstop

Stops playback of loopbgm music.


page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
lr_trap

Click Traps

lr_trap LABEL

LABELDestination for jump upon click

lr_trap off

Traps left and right clicks (or turns said trap off), directing the interpreter to the given label name.


page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
lr_trap2

Click Traps

lr_trap2 LABEL

LABELDestination for jump upon click during skip mode

lr_trap2 off

Similar to lr_trap, except this one functions in "skip to next choice" mode.


lr_trap /
page top / list / main

[Program Block Only]( NScr2.49, ONScr, ONScr-EN )
lrclick

Click Wait

lrclick

Waits for either a left or right click.
The type of click of occurred can be retrieved using getret:
getret %0
This will return 0 for a right-click and 1 for a left-click.


click / getret /
page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
lsp

Image Display

lsp NUM,STR,NUM,NUM[,NUM]

NUMSprite number (0 - 999)
STRImage filename or processing tag
NUMTop-left X-coordinate
NUMTop-left Y-coordinate
NUMOpacity value (0 - 255)

Loads and displays a sprite. Sprite numbers may range from 0 to 999.
The other numbers are, from left to right: x coordinate of upper left pixel, y coordinate of upper left pixel, and optional opacity value (0 for transparent up to 255 for opaque).
The only difference between lsp and lsph is the beginning condition of the sprite - lsp displays the sprite, while lsph keeps the sprite hidden (which may later be displayed with vsp).

Image processing tag format:
"[:(trans-mode)[/(animation)];](filename)"
OR
":s[/(string-params);](color)[(color)...](text-string)" (added Ver.1.80)
OR
"[:(trans-mode)[/(animation)];]>(width),(height),(color)[(color)...]" (added Ver.2.93)

The first format is for processing image files - note that the (filename) by itself is fine for single-cell default transparency images. The possible arguments are:
(transmode):
l - for 'leftup'; the color of the top-left pixel will be used as the transparent color
r - for 'rightup'; the color of the top-right pixel will be used as the transparent color
c - for 'copy'; shows the image as-is, no transparency settings
a - for 'alphablend'; the right half of the image contains alpha-level data for the left half
m(filename) - for 'mask'; uses the given file as alpha-level data for the main image

Note that for alpha-levels, black (#000000) = opaque and white (#ffffff) = completely transparent.
If (transmode) is omitted, it assumes the default transparency setting provided via the transmode command.

(animation): (num-cells),(delay),(loop-type)
This optional parameter set tells how to animate a sprite with multiple cells.
The image gets 'cut' into (num-cells) pieces, going from left to right. If the image contains alpha-level data, then each cell contains its own alpha-data in its right-half.
The (delay) can either be a single value, telling the number of milliseconds to spend on each cell; or else it can have the format <(cell-1-delay),(cell-2-delay,...(cell-n-delay)>, giving varying delays per cell.
The (loop-type) is a number telling how to cycle between the cells:
0 - a repeated cycle (0,1,...n,0,1,...)
1 - single time through (0,1,...n)
2 - a 'bouncing' cycle (0,1,...n,n-1,...1,0,1,...)
3 - no cycle (0); cell number is changed via cell command or sprite control (see spstr)

The second tag format is for creating string sprites:
":s[/(string-params);](color)[(color)...](text-string)"
Note that at least one color setting (#rrggbb) must be provided with the text. Other arguments are:
(string-params): (char-width),(char-height),(X-spacing),(decor)
The character width, height, and spacing are the same kinds of numeric values used for setwindow, for example.
The (decor) value describes a style for the text:
0 - standard
1 - none
2 - open face
If (string-params) are omitted, the text uses the sizing, spacing and style set by setwindow or spfont.
If multiple (color) values are provided, it creates a string sprite with multiple cells - each cell with each different color. This can be useful for making text buttons.
For finer control and/or to make multiple-line string sprites, use the strsp command instead.

The NEW third format is for creating single-color rectangle sprites:
"[:(trans-mode)[/(animation)];]>(width),(height),(color)[(color)...]"
The (trans-mode) and (animation) have the same syntax as used in the first tag format. The (width) and (height) provide the width and height of the resulting rectangle.
Note that there must be at least one color value provided; if multiple (color) values are provided, it creates a rectangle sprite with multiple cells - one cell for each different color.

Example:
Loads image "thing1.bmp", using default transparency type.
lsp 2,"thing1.bmp",0,0
Example:
Loads image "thing1.bmp", using "mask1.bmp" for transparency data.
lsp 2,":mmask1.bmp;thing1.bmp",0,0
Example:
The default clickwait cursor: 'leftup' transmode, bouncing through 3 cells (0,1,2,1,0,...) with 160ms delay per cell.
lsp 0,":l/3,160,2;cursor0.bmp",0,0
Example:
The default clickwait cursor, but with 'jerky' animation.
lsp 0,":l/3,<160,1000,400>,2;cursor0.bmp",0,0
Example:
Creates a 100x50 rectangular sprite with 2 cells (white and gray).
lsp 0,":c;>100,50,#FFFFFF#888888",200,200

lsph / strsp / spfont /
page top / list / main

[Program Block Only]( NScr2.80, ONScr, ONScr-EN, PONS )
lsp2

Extended Sprites

lsp2 NUM,STR,NUM,NUM,NUM,NUM,NUM[,NUM]

NUMExtended-sprite number (0 - 255)
STRImage filename or sprite processing string
NUMCenter X-coordinate
NUMCenter Y-coordinate
NUMScaling factor X (%)
NUMScaling factor Y (%)
NUMRotation angle (degrees, counterclockwise)
NUMOpacity value (optional, default 255)

Loads an extended sprite. Extended sprites add rotation about center and horizontal/vertical scaling to the existing sprite elements of position and opacity; it's also possible to flip images with the use of negative scale factors.
Like lsp, lsp2 loads images using the set display transparency mode.
The scaling factors are percentages; also note that providing a negative scaling factor will reverse the direction of the image.

*
The lsp2 command does not correspond to current animation
Example:
Loads and displays the image "test.bmp" without transparency, centered at (320,240), expanded to 200% vertically, and rotated 36 degrees counterclockwise.
lsp2 0,":c;test.bmp",320,240,100,200,36

lsph2 / lsp2add / lsph2add / csp2 / vsp2 / msp2 / amsp2 /
page top / list / main

[Program Block Only]( NScr2.80, ONScr-EN )
lsp2add

Extended Sprites

lsp2add NUM,STR,NUM,NUM,NUM,NUM,NUM[,NUM]

NUMExtended-sprite number (0 - 255)
STRImage filename or sprite processing string
NUMCenter X-coordinate
NUMCenter Y-coordinate
NUMScaling factor X (%)
NUMScaling factor Y (%)
NUMRotation angle (degrees, counterclockwise)
NUMOpacity value (optional, default 255)

Loads an extended sprite using additive composition.
lsp2add uses additive blending for display, but otherwise it works the same as lsp2.

Example:
Loads the image "test.bmp" and displays without transparency using additive blending, centered at (320,240), expanded to 200% vertically, and rotated 36 degrees counterclockwise.
lsp2add 0,":c;test.bmp",320,240,100,200,36

lsp2 / lsph2 / lsph2add / csp2 / vsp2 / msp2 / amsp2 /
page top / list / main

[Program Block Only]( NScr2.93, ONScr-EN )
lsp2sub

Extended Sprites

lsp2add NUM,STR,NUM,NUM,NUM,NUM,NUM[,NUM]

NUMExtended-sprite number (0 - 255)
STRImage filename or sprite processing string
NUMCenter X-coordinate
NUMCenter Y-coordinate
NUMScaling factor X (%)
NUMScaling factor Y (%)
NUMRotation angle (degrees, counterclockwise)
NUMOpacity value (optional, default 255)

Loads an extended sprite using subtractive composition.
lsp2sub uses subtractive blending for display, but otherwise it works the same as lsp2.

Example:
Loads the image "test.bmp" and displays without transparency using subtractive blending, centered at (320,240), expanded to 200% vertically, and rotated 36 degrees counterclockwise.
lsp2sub 0,":c;test.bmp",320,240,100,200,36

lsp2 / lsph2 / lsp2add / lsph2add / lsph2sub / csp2 / vsp2 / msp2 / amsp2 /
page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
lsph

Image Display

lsph NUM,STR,NUM,NUM[,NUM]

NUMSprite number (0 - 999)
STRImage filename or sprite processing string
NUMTop-left X-coordinate
NUMTop-left Y-coordinate
NUMOpacity value (0 - 255)

Loads a sprite in a hidden state.
The only difference between lsp and lsph is the beginning condition of the sprite - lsp displays the sprite, while lsph keeps the sprite hidden (which may later be displayed with vsp).


lsp /
page top / list / main

[Program Block Only]( NScr2.80, ONScr, ONScr-EN, PONS )
lsph2

Extended Sprites

lsph2 NUM,STR,NUM,NUM,NUM,NUM,NUM[,NUM]

NUMExtended-sprite number (0 - 255)
STRImage filename or sprite processing string
NUMCenter X-coordinate
NUMCenter Y-coordinate
NUMScaling factor X (%)
NUMScaling factor Y (%)
NUMRotation angle (degrees, counterclockwise)
NUMOpacity value (optional, default 255)

Loads an extended sprite in a hidden state.
The only difference between lsp2 and lsph2 is the beginning condition of the extended sprite - lsp2 displays the sprite, while lsph2 keeps the sprite hidden (which may later be displayed with vsp2).


lsp2 / lsp2add / lsph2add / csp2 / vsp2 / msp2 / amsp2 /
page top / list / main

[Program Block Only]( NScr2.80, ONScr-EN )
lsph2add

Extended Sprites

lsph2add NUM,STR,NUM,NUM,NUM,NUM,NUM[,NUM]

NUMExtended-sprite number (0 - 255)
STRImage filename or sprite processing string
NUMCenter X-coordinate
NUMCenter Y-coordinate
NUMScaling factor X (%)
NUMScaling factor Y (%)
NUMRotation angle (degrees, counterclockwise)
NUMOpacity value (optional, default 255)

Loads an extended sprite using additive composition, in a hidden starting state.
The only difference between lsp2add and lsph2add is the beginning condition of the extended sprite - lsp2add displays the sprite, while lsph2add keeps the sprite hidden (which may later be displayed with vsp2).


lsp2 / lsph2 / lsp2add / csp2 / vsp2 / msp2 / amsp2 /
page top / list / main

Ver.(undoc)[Program Block Only]( NScr2.93, ONScr-EN )
lsph2sub

Extended Sprites

lsph2add NUM,STR,NUM,NUM,NUM,NUM,NUM[,NUM]

NUMExtended-sprite number (0 - 255)
STRImage filename or sprite processing string
NUMCenter X-coordinate
NUMCenter Y-coordinate
NUMScaling factor X (%)
NUMScaling factor Y (%)
NUMRotation angle (degrees, counterclockwise)
NUMOpacity value (optional, default 255)

Loads an extended sprite using subtractive composition, in a hidden starting state.
The only difference between lsp2sub and lsph2sub is the beginning condition of the extended sprite - lsp2sub displays the sprite, while lsph2sub keeps the sprite hidden (which may later be displayed with vsp2).


lsp2 / lsph2 / lsp2add / lsph2add / lsp2sub / csp2 / vsp2 / msp2 / amsp2 /
page top / list / main

Ver.2.93[Definition Block Only]( NScr )
luacall

System Customization

luacall NAME

NAMESystem function name (tag, text0, text, animation, close, end, savepoint, save, load)

Many default NScripter system functions can now be replaced with Lua callbacks.
A Lua function could be created to handle text display using sprites, for example, as well as other sorts of system customization.
The specified character string need not be enclosed by double-quotes, and is case-insensitive.
The applicable Lua-side function must be named NSCALL_(sysfunc-name) and use the defined function argument structure for that particular call.

*
luacall animation callback stub added in (Japanese) onscripter 20090510-exp. (by Mion)
Example:
Specifies that Lua function NSCALL_text will be called for text display handling.
luacall text

luasub /
page top / list / main

Ver.2.93[Definition Block Only]( NScr )
luasub

System Customization

luasub NAME

NAMEInstruction name

Defines a new command with the given name and ties it to a Lua function NSCOM_(cmd-name).
Any time the command is executed within the script, that Lua function will be called.
A Lua function registered with luasub must be void - no arguments or return values.

*
Existing NScr commands may be replaced using luasub!
For example, luasub bg will cause Lua function NSCOM_bg() to be called instead of the standard bg command.
As with defsub, you can use _bg to call the original bg instruction.
*
luasub stub added in (Japanese) onscripter 20090510-exp. (by Mion)
Example:
Specifies that Lua function NSCOM_func will be called when the "func" command is executed.
luasub func

luacall / defsub /
page top / list / main

[Definition Block Only]( NScr2.01, ONScr, ONScr-EN, PONS )
maxkaisoupage

Log Mode

maxkaisoupage NUM

NUMMaximum number of pages to store in backlog buffer

Sets the maximum number of pages that may be stored for Log Mode.

Example:
Allows access to only the previous 10 pages in Log Mode.
maxkaisoupage 10

page top / list / main

[Program Block Only]( NScr, ONScr-EN )
menu_click_def

Window Menubar

menu_click_def

Enters default text display (not single-page) mode; see menu_click_page.


menu_click_page /
page top / list / main

[Program Block Only]( NScr, ONScr-EN )
menu_click_page

Window Menubar

menu_click_page

Enters single-page text display mode, as provided via the 表示形式(Display Format) menubar item.

*
This and menu_click_def affect what *ONScripter provides as "page-at-once" mode, using 'o' keystroke toggle. (by Mion)

menu_click_def /
page top / list / main

Ver.1.97[Program Block Only]( NScr )
menu_dwavvol

Window Menubar

menu_dwavvol

Displays the volume change dialog box.


mp3vol / voicevol / sevol / bgmvol /
page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
menu_full

Window Menubar

menu_full

Enters fullscreen mode.


menu_window / isfull /
page top / list / main

[Program Block Only]( ONScr-EN20091230 )
menu_waveoff

Window Menubar

menu_waveoff

Disables (or mutes) main volume.


menu_waveon /
page top / list / main

[Program Block Only]( ONScr-EN20091230 )
menu_waveon

Window Menubar

menu_waveon

Enables main volume (turning off volume mute, if set).


menu_waveoff /
page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
menu_window

Window Menubar

menu_window

Enters windowed mode.


menu_full / isfull /
page top / list / main

[Definition Block Only]( NScr, ONScr, ONScr-EN, PONS )
menuselectcolor

Right-Click Functionality

menuselectcolor COLOR,COLOR,COLOR

COLORMouseover color
COLORMouseoff color
COLOREmpty savefile slot color

This command sets the colors of the right-click menu when the right-click menu functionality is enabled. In order, the colors are the mouseover color, the mouseout color, and the "no savefile exists" color.


page top / list / main

[Definition Block Only]( NScr, ONScr, ONScr-EN, PONS )
menuselectvoice

Right-Click Functionality

menuselectvoice STR,STR,STR,STR,STR,STR,STR

STRSound file that plays when a menu opens
STRSound file that plays at menu cancel
STRSound file that plays upon mouseover of a menu item
STRSound file that plays when a menu item is clicked
STRSound file that plays at an error
STRSound file that plays when 'Yes' option chosen
STRSound file that plays when 'No' option chosen

Designates the WAV files that are played for menu choices, and other system sounds.

From left to right, the strings are: menu open, menu cancel, menu item mouseover, on click, forbidden operation, "yes" confirmation, "no" confirmation.

If any of these are set to "", no sound plays.
By default, all of these sounds are set to "".


page top / list / main

[Definition Block Only]( NScr, ONScr, ONScr-EN, PONS )
menusetwindow

Right-Click Functionality

menusetwindow NUM,NUM,NUM,NUM,NUM,NUM,COLOR

NUM(Full-width) text font width
NUMText font height
NUMText spacing X
NUMText spacing Y
NUMBoldface toggle (0=off/1=on)
NUMDrop shadow toggle (0=off/1=on)
COLORWindow color

Creates a menu dialog window.
This window displays above all other items in the screen when active.
From left to right, the arguments are: character font size x, character font size y, kerning x, kerning y, boldface (1 - yes; 0 - no), drop shadow (1 - yes; 0 - no); the final #rrggbb parameter is the window color.


page top / list / main

[Definition/Program Block]( NScr )
mesbox

Miscellaneous

mesbox STR,STR

STRMessage to display
STRMessagebox title

Shows a message box.
The first string is the contents of the box, the second string is the title of said box.


page top / list / main

[Definition/Program Block]( NScr1.99, ONScr, ONScr-EN, PONS )
mid

Variable Manipulation/Calculations

mid $VAR,STR,NUM,NUM

VARString variable to receive the substring
STRCharacter string to extract from
NUMStarting index of the substring
NUMNumber of (half-width) characters to extract

Extracts a substring from the given character string.

*
Use starting index 0 for the first character. Also, to get exactly 1 full-width character, specify 2 as the number of chars to extract.
Example:
Extracts a substring of length %1 starting at index %0 from string $1, and assigns the result to $0.
mid $0,$1,%0,%1
Example:
Grabs the first 5 characters of $1 and assigns the substring to $0.
mid $0,$1,0,5

len /
page top / list / main

[Program Block Only]( NScr2.00, ONScr-EN )
minimizewindow

Miscellaneous

minimizewindow

Minimizes the game window.


page top / list / main

[Definition/Program Block]( NScr, ONScr, ONScr-EN, PONS )
mod

Variable Manipulation/Calculations

mod %VAR,NUM

VARNumeric variable
NUMNumeric value to divide by and get remainder

Finds the remainder after the variable is divided by the number (same as the x % y command in C).

*
You can also use mod as an expression operator, as follows:
mov %0,%1 mod 2

page top / list / main

[Definition Block Only]( NScr, ONScr, ONScr-EN, PONS )
mode_ext

Special Mode Settings

mode_ext

This is a command developed especially for the commercial software "Gin'iro". When you use this command, you can enter Auto Mode from the menu. It is similar in concept to the "skip to next choice" option, but displays characters much more slowly (with a delay defined by automode_time). This makes it almost like a mode in which the computer reads the text to you.

You can adjust sound playback volume from the NScr menus while Auto Mode is progressing (MP3(BGM), voice(DWAVE 0), and SE(DWAVE 1+) are all active and adjustable).

There are future plans to add more functionality to this command, and to make things conform to predefined syntaxes.


page top / list / main

[Definition Block Only]( NScr, ONScr, ONScr-EN, PONS )
mode_saya

Special Mode Settings

mode_saya

A command mode written especially for the doujin game, "Saya ~Labyrinth of Immorality~". Once you specify this command, you enter: the legendary Saya Mode!
In Saya mode, when the text window disappears:

* Sprites 0-9 also disappear, regardless of whether they're flagged to be visible or not.
* Bars and numbers indicating status underneath the text window also disappear.

You would use this, for instance, when you had a parameter status window that you wanted to hide when the text window disappeared.


page top / list / main

[Definition Block Only]( NScr, ONScr-EN, PONS )
mode_wave_demo

Skip Mode

mode_wave_demo

Usually WAV files are not played during "skip to next choice" mode, but specifying this command will have them be played.

*
ONScripter doesn't recognize this command, but plays WAV files during skip mode anyway. ONScripter-EN supports this command since ver.20090816 (as does PONScripter since ver.20100205) by playing WAV files during skips only if mode_wave_demo is used. (by Mion)

page top / list / main

[Definition Block Only]( NScr2.01, ONScr, ONScr-EN, PONS )
mode320

Special Mode Settings

;mode320

Enables 320x240 screen mode. This command must be the first line in the script - even above *define.

*
Even when this command is used, the text window is still sized as for 640x480. Therefore, you will need to adjust it with setwindow.
Example:
Sets the game screen size to 320x240.
;mode320
*define

mode800 / mode400 / value /
page top / list / main

[Definition Block Only]( NScr2.01, ONScr, ONScr-EN, PONS )
mode400

Special Mode Settings

;mode400

Enables 400x300 screen mode. This command must be the first line in the script - even above *define.

*
Even when this command is used, the text window is still sized as for 640x480. Therefore, you will need to adjust it with setwindow.
Example:
Sets the game screen size to 400x300.
;mode400
*define

mode800 / mode320 / value /
page top / list / main

[Definition Block Only]( NScr, ONScr, ONScr-EN, PONS )
mode800

Special Mode Settings

;mode800

Enables 800x600 screen mode (yes, the ';' in the beginning is necessary!). This command must be the first line in the script - even above *define.

*
Even when this command is used, the text window is still sized as for 640x480. Therefore, you will need to adjust it with setwindow.
Example:
Sets the game screen size to 800x600.
;mode800
*define

mode400 / mode320 / value /
page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
monocro

Visual Effects

monocro COLOR

COLORBase color

monocro off

Fades the screen to monochrome, using the given color as a base.
The text window and cursor will not follow suit.
Use "off" as the parameter to make the colors return to normal.


page top / list / main

[Definition/Program Block]( NScr )
mousecursor

Cursor

mousecursor STR

STRMouse cursor file

Loads a Windows mouse cursor definition file (.cur) and utilizes it.

*
Non-recommendation of this command is removed as of ver2.93.

page top / list / main

[Program Block Only]( NScr2.93, ONScr-EN20091122 )
mousemode

Cursor

mousemode NUM

NUMMouse cursor display flag (0: hidden, 1: displayed)

Setting mousemode 0 hides the mouse cursor, while mousemode 1 displays it.


page top / list / main

[Definition/Program Block]( NScr, ONScr, ONScr-EN, PONS )
mov

Variable Manipulation/Calculations

mov %VAR,NUM

VARNumeric variable
NUMNumeric value

mov $VAR,STR

VARString variable
STRCharacter string value

Assigns a variable with a new value.

Example:
Sets numeric variable %3 to 24.
mov %3,24
Example:
Sets string variable $0 to a filename.
mov $0,"myfile.jpg"

page top / list / main

[Definition/Program Block]( NScr, ONScr, ONScr-EN, PONS )
mov10

Variable Manipulation/Calculations

mov10 %VAR,NUM,NUM,NUM,NUM,NUM,NUM,NUM,NUM,NUM,NUM

VARNumeric variable
NUMNumeric value #1
NUMNumeric value #2
NUMNumeric value #3
NUMNumeric value #4
NUMNumeric value #5
NUMNumeric value #6
NUMNumeric value #7
NUMNumeric value #8
NUMNumeric value #9
NUMNumeric value #10

This command fills 10 numeric variables - starting from the one specified and incrementing upward - with the specified numbers.

*
This can't be used with string variables. (by senzogawa)
Example:
Sets %3 to 2, %4 to 4, %5 to 6, and so forth.
mov3 %3,2,4,6,8,10,12,14,16,18,20
;is equivalent to
;mov %3,2
;mov %4,4
;mov %5,6
;mov %6,8
;mov %7,10
;mov %8,12
;mov %9,14
;mov %10,16
;mov %11,18
;mov %12,20

mov / mov3 / mov4 / mov5 / mov6 / mov7 / mov8 / mov9 /
page top / list / main

[Definition/Program Block]( NScr, ONScr, ONScr-EN, PONS )
mov3

Variable Manipulation/Calculations

mov3 %VAR,NUM,NUM,NUM

VARNumeric variable
NUMNumeric value #1
NUMNumeric value #2
NUMNumeric value #3

This command fills 3 numeric variables - starting from the one specified and incrementing upward - with the specified numbers.

mov4, mov5, mov6, mov7, mov8, mov9, and mov10 all follow suit from this.

*
This can't be used with string variables. (by senzogawa)
Example:
Sets %3 to 2, %4 to 4, and %5 to 6.
mov3 %3,2,4,6
;is equivalent to
;mov %3,2
;mov %4,4
;mov %5,6

mov / mov4 / mov5 / mov6 / mov7 / mov8 / mov9 / mov10 /
page top / list / main

[Definition/Program Block]( NScr, ONScr, ONScr-EN, PONS )
mov4

Variable Manipulation/Calculations

mov4 %VAR,NUM,NUM,NUM,NUM

VARNumeric variable
NUMNumeric value #1
NUMNumeric value #2
NUMNumeric value #3
NUMNumeric value #4

This command fills 4 numeric variables - starting from the one specified and incrementing upward - with the specified numbers.

*
This can't be used with string variables. (by senzogawa)
Example:
Sets %3 to 2, %4 to 4, %5 to 6, and so forth.
mov3 %3,2,4,6,8
;is equivalent to
;mov %3,2
;mov %4,4
;mov %5,6
;mov %6,8

mov / mov3 / mov5 / mov6 / mov7 / mov8 / mov9 / mov10 /
page top / list / main

[Definition/Program Block]( NScr, ONScr, ONScr-EN, PONS )
mov5

Variable Manipulation/Calculations

mov5 %VAR,NUM,NUM,NUM,NUM,NUM

VARNumeric variable
NUMNumeric value #1
NUMNumeric value #2
NUMNumeric value #3
NUMNumeric value #4
NUMNumeric value #5

This command fills 5 numeric variables - starting from the one specified and incrementing upward - with the specified numbers.

*
This can't be used with string variables. (by senzogawa)
Example:
Sets %3 to 2, %4 to 4, %5 to 6, and so forth.
mov3 %3,2,4,6,8,10
;is equivalent to
;mov %3,2
;mov %4,4
;mov %5,6
;mov %6,8
;mov %7,10

mov / mov3 / mov4 / mov6 / mov7 / mov8 / mov9 / mov10 /
page top / list / main

[Definition/Program Block]( NScr, ONScr, ONScr-EN, PONS )
mov6

Variable Manipulation/Calculations

mov6 %VAR,NUM,NUM,NUM,NUM,NUM,NUM

VARNumeric variable
NUMNumeric value #1
NUMNumeric value #2
NUMNumeric value #3
NUMNumeric value #4
NUMNumeric value #5
NUMNumeric value #6

This command fills 6 numeric variables - starting from the one specified and incrementing upward - with the specified numbers.

*
This can't be used with string variables. (by senzogawa)
Example:
Sets %3 to 2, %4 to 4, %5 to 6, and so forth.
mov3 %3,2,4,6,8,10,12
;is equivalent to
;mov %3,2
;mov %4,4
;mov %5,6
;mov %6,8
;mov %7,10
;mov %8,12

mov / mov3 / mov4 / mov5 / mov7 / mov8 / mov9 / mov10 /
page top / list / main

[Definition/Program Block]( NScr, ONScr, ONScr-EN, PONS )
mov7

Variable Manipulation/Calculations

mov7 %VAR,NUM,NUM,NUM,NUM,NUM,NUM,NUM

VARNumeric variable
NUMNumeric value #1
NUMNumeric value #2
NUMNumeric value #3
NUMNumeric value #4
NUMNumeric value #5
NUMNumeric value #6
NUMNumeric value #7

This command fills 7 numeric variables - starting from the one specified and incrementing upward - with the specified numbers.

*
This can't be used with string variables. (by senzogawa)
Example:
Sets %3 to 2, %4 to 4, %5 to 6, and so forth.
mov3 %3,2,4,6,8,10,12,14
;is equivalent to
;mov %3,2
;mov %4,4
;mov %5,6
;mov %6,8
;mov %7,10
;mov %8,12
;mov %9,14

mov / mov3 / mov4 / mov5 / mov6 / mov8 / mov9 / mov10 /
page top / list / main

[Definition/Program Block]( NScr, ONScr, ONScr-EN, PONS )
mov8

Variable Manipulation/Calculations

mov8 %VAR,NUM,NUM,NUM,NUM,NUM,NUM,NUM,NUM

VARNumeric variable
NUMNumeric value #1
NUMNumeric value #2
NUMNumeric value #3
NUMNumeric value #4
NUMNumeric value #5
NUMNumeric value #6
NUMNumeric value #7
NUMNumeric value #8

This command fills 8 numeric variables - starting from the one specified and incrementing upward - with the specified numbers.

*
This can't be used with string variables. (by senzogawa)
Example:
Sets %3 to 2, %4 to 4, %5 to 6, and so forth.
mov3 %3,2,4,6,8,10,12,14,16
;is equivalent to
;mov %3,2
;mov %4,4
;mov %5,6
;mov %6,8
;mov %7,10
;mov %8,12
;mov %9,14
;mov %10,16

mov / mov3 / mov4 / mov5 / mov6 / mov7 / mov9 / mov10 /
page top / list / main

[Definition/Program Block]( NScr, ONScr, ONScr-EN, PONS )
mov9

Variable Manipulation/Calculations

mov9 %VAR,NUM,NUM,NUM,NUM,NUM,NUM,NUM,NUM,NUM

VARNumeric variable
NUMNumeric value #1
NUMNumeric value #2
NUMNumeric value #3
NUMNumeric value #4
NUMNumeric value #5
NUMNumeric value #6
NUMNumeric value #7
NUMNumeric value #8
NUMNumeric value #9

This command fills 9 numeric variables - starting from the one specified and incrementing upward - with the specified numbers.

*
This can't be used with string variables. (by senzogawa)
Example:
Sets %3 to 2, %4 to 4, %5 to 6, and so forth.
mov3 %3,2,4,6,8,10,12,14,16,18
;is equivalent to
;mov %3,2
;mov %4,4
;mov %5,6
;mov %6,8
;mov %7,10
;mov %8,12
;mov %9,14
;mov %10,16
;mov %11,18

mov / mov3 / mov4 / mov5 / mov6 / mov7 / mov8 / mov10 /
page top / list / main

[Program Block Only]( NScr2.00, ONScr, ONScr-EN, PONS )
movemousecursor

Cursor

movemousecursor NUM,NUM

NUMX-coordinate for mouse cursor destination
NUMY-coordinate for mouse cursor destination

Moves the mouse cursor to an arbitrary position on the screen.

Example:
This moves the mouse to (100,10).
movemousecursor 100,10

page top / list / main

[Program Block Only]( NScr2.49, ONScr20090116, ONScr-EN20090419 )
movie

Movie Playback

movie STR[,'pos',NUM,NUM,NUM,NUM][,'click'][,'loop'][,'async']

STRMovie filename
NUMMovie window top-left X coordinate
NUMMovie window top-left Y coordinate
NUMMovie window width
NUMMovie window height

movie stop

This movie playback command is intended to replace mpegplay.

The following options may be combined:
movie "filename" ;Plays until completion, can't be interrupted
movie "filename",pos,10,20,320,240 ;Positions the movie within a 320x240 window with top-left at (10,20)
movie "filename",click ;Movie playback is click-interruptible (not valid in async mode)
movie "filename",loop ;Plays the movie repeatedly (must be combined with either click or async, otherwise it can't be stopped!)
movie "filename",async ;Asynchronous playback. The script returns to command interpretation while playback continues. The movie will always be the top layer on-screen, even atop text.
movie stop ;Use this to stop async movie playback

*
The movie image remains on-screen after playback finishes.
Since the movie is considered invalid data, it's possible to revert to the screen as it was beforehand by using print.
Example:
This plays "test.mpg" looped, within a 320x240 window at coordinate (10,20), and asynchronously; it then stops playback after a 30 second wait.
movie "test.mpg",pos,10,20,320,240,async,loop
wait 30*1000
movie stop
Example:
This plays "test.mpg", click-interruptible, then crossfades to the previous screen after playback is complete.
movie "test.mpg",click
print 10,1000

mpegplay /
page top / list / main

[Definition/Program Block]( NScr1.97, ONScr, ONScr-EN, PONS )
movl

Variable Manipulation/Calculations

movl ARRAY,NUM[,NUM[,...]]

ARRAYArray variable
NUMNumeric value

Enters numbers into an array all at once.

Example:
Define an array ?10 of length 5 and populate it.
dim ?10[4]
movl ?10,0,1,2,3,4
Example:
Define a two-dimensional array ?20 of size 3x4 and populate it, line by line.
dim ?20[2][3]
movl ?20[0],0,1,2,3
movl ?20[1],0,2,4,6
movl ?20[2],0,3,6,9

page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
mp3

Music/SFX Playback

mp3 STR

STRMP3 filename

If mp3dec.dll is used (this functionality is built into ONScripter), you can use this to play an mp3 file. mp3 plays the file only once, while mp3loop loops the file. You may issue wave commands while mp3's are playing with no ill effects.


page top / list / main

[Definition/Program Block]( NScr2.24, ONScr-EN )
mp3fadein

Music/SFX Playback

mp3fadein NUM

NUMBGM playback fade-in time (msec)

The same as bgmfadein.


bgmfadeout /
page top / list / main

[Definition/Program Block]( NScr, ONScr-EN20060621 )
mp3fadeout

Music/SFX Playback

mp3fadeout NUM

NUMMP3 playback fade-out time (msec)

Sets MP3 (BGM) fadeout time in milliseconds. Same as bgmfadeout (added in Ver2.21).

*
In versions of ONScripter-EN before 20090417, mp3fadeout did an immediate fadeout instead of setting the behavior for mp3stop. (by Mion)

bgmfadein /
page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
mp3loop

Music/SFX Playback

mp3loop STR

STRMP3 filename

If mp3dec.dll is used (this functionality is built into ONScripter), you can use this to play an mp3 file. mp3 plays the file only once, while mp3loop loops the file. You may issue wave commands while mp3's are playing with no ill effects.


page top / list / main

[Program Block Only]( NScr1.97, ONScr, ONScr-EN, PONS )
mp3save

Music/SFX Playback

mp3save

Just like the mp3 command, this plays back an mp3 only once; however, if the player saves during playback, the mp3 will start playing upon reload.


page top / list / main

[Program Block Only]( NScr2.01, ONScr, ONScr-EN, PONS )
mp3stop

Music/SFX Playback

mp3stop

Stops playback of compressed music.


page top / list / main

[Program Block Only]( NScr1.98, ONScr, ONScr-EN, PONS )
mp3vol

Music/SFX Playback

mp3vol NUM

NUMSound volume (0-100)

Changes the volume of the BGM. This applies to both bgm and mp3 commands.

*
Volume changes are not saved, so manage them manually or with variables.
This does not affect the play instruction. (by senzogawa)
Example:
Sets BGM volume to maximum (100)
mp3vol 100

chvol / voicevol / sevol / bgmvol /
page top / list / main

[Program Block Only]( NScr1.97, ONScr, ONScr-EN, PONS )
mpegplay

Movie Playback

mpegplay STR,NUM

STRMovie filename
NUMInterrupt flag (0: play whole thing, 1: click-interruptible)

Plays an MPEG video file. The second parameter can be 0 or 1, and determines whether the player must watch the whole movie (0) or can skip the movie by clicking (1).

Example:
This plays "test.mpeg", click-interruptible.
mpegplay "test.mpeg",1

page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
msp

Image Display

msp NUM,NUM,NUM[,NUM]

NUMSprite number (0 - 999)
NUMX-coordinate offset
NUMY-coordinate offset
NUMOpacity offset

Moves the sprite of the designated number, adjusting the position and opacity relative to their current values.

Like the tal command, and other sprite system commands, The results of msp will not show up immediately on screen (this is for ease and speed of batch processing).
So before you call any text or image display commands after an msp, please call a print command to update the screen before continuing.


amsp /
page top / list / main

[Program Block Only]( NScr2.80, ONScr, ONScr-EN, PONS )
msp2

Extended Sprites

msp2 NUM,NUM,NUM,NUM,NUM,NUM[,NUM]

NUMExtended-sprite number
NUMX-coordinate offset
NUMY-coordinate offset
NUMX scaling factor offset
NUMY scaling factor offset
NUMRotation angle offset
NUMOpacity offset

Moves the extended sprite of the designated number, adjusting its position, scale, rotation and opacity relative to their current values.

Example:
Takes Extended-Sprite 0 and moves it 10 pixels right and 20 pixels down, while decreasing its X-scale factor by 10, increasing its Y-scale factor by 10, and adding 5 degrees to its rotation.
msp2 0,10,20,-10,10,5

lsp2 / lsph2 / lsp2add / lsph2add / csp2 / vsp2 / amsp2 /
page top / list / main

[Definition/Program Block]( NScr, ONScr, ONScr-EN, PONS )
mul

Variable Manipulation/Calculations

mul %VAR,NUM

VARNumeric variable
NUMNumeric value to multiply

Multiplies the variable by the number and stores the result in the variable.


page top / list / main

[Program Block Only]( NScr2.20, ONScr-EN20091122 )
mv

Music/SFX Playback

'mv'NUM':'

NUMVoice file number

This is a shorthand command for playing mp3 voice files.
It is equivalent to mp3 "voice\(num).mp3".

Example:
This plays "voice\0001.mp3" via the mp3 command before outputting text.
mv0001:「これが0001番のせりふだよー」

page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
nega

Visual Effects

nega NUM

NUMDisplay flag (0: off, 1: monochrome-priority, 2: negative-priority)

If flag is 1 or 2, it causes a negative of the current image.
Use 1 to apply (any) monocro on top of the nega, 2 to apply nega atop the monocro (i.e. 1 applies nega first, 2 applies monocro first).
If 0, the image flips back to positive.
Neither monocro nor nega update the screen themselves, so please call print afterwards.


monocro /
page top / list / main

[Definition/Program Block]( NScr, ONScr, ONScr-EN, PONS )
next

Conditionals/Loops

next

This ends a for block. Please refer to the documentation of for for more details.


for /
page top / list / main

Ver.2.80[Program Block Only]( NScr )
nextcsel

System Customization

nextcsel %VAR

VARNumeric result variable (1: next cmd is csel, 0: not csel

Returns 1 if the next command is csel, 0 otherwise. This may be useful in displaying choices without erasing text.


csel / *customsel /
page top / list / main

Ver.(undoc)[Definition Block Only]( NScr )
noloaderror

Miscellaneous

noloaderror

The program won't fail with an error if a sound or image load command, such as ld or bgm, fails to load a file.


bg / ld / bgm /
page top / list / main

Ver.1.99[Definition Block Only]( NScr )
noteraseman

Text Window

noteraseman

Standing images will not be erased when the text window is removed.

*
Does this actually do anything? (by Mion)

textoff /
page top / list / main

[Definition/Program Block]( NScr, ONScr, ONScr-EN, PONS )
notif

Conditionals/Loops

notif CONDITION[{&&,&} CONDITION[...]] SENTENCE

CONDITIONRelative operation, check instruction, or some other truth-value returning expression
SENTENCECommand(s) to execute if the condition was False

The commands following the if statement are executed if the conditional statement(s) evaluate false; if you want branch control in which a command executes if a conditional statement is true, use if.
The conditions compare numerical values, else you can employ fchk.
& and && are logical 'ands', and are equivalent to each another.

Conditions:
(numerical variable) {>,<,=,>=,<=,==,!=,<>} (numeric variable)
- or -
fchk (character string)

Example:
If %0 is not equal to 1, do a 1/2 second horizontal screen shake.
notif %0=1 quakex 2,500

if /
page top / list / main

[Definition Block Only]( NScr, ONScr, ONScr-EN, PONS )
nsa

Plugins/Archives

nsa

Allows for NSA archive mode. In this mode, resources such as BMPs may be read from nsa*.arc, located in the same directory as the executable itself. The nsa*.arc files themselves are generated by nsaarc.exe, which can be found in the NScr SDK.

Please note that you may consecutively name files as arc.nsa, arc1.nsa, arc2.nsa ... arc9.nsa, and for the purposes of the interpreter, they will all be considered as part of the same namespace - like one big archive. You may use this to quickly unpackage and repackage archives for testing.


page top / list / main

[Definition Block Only]( NScr1.97, ONScr, ONScr-EN, PONS )
nsadir

Plugins/Archives

nsadir STR

STRDirectory to be read for NSA archives

Sets the folder search path for nsa archives. By default, this is the same directory where the executable resides.


page top / list / main

[Definition Block Only]( NScr, ONScr, ONScr-EN, PONS )
numalias

Variable Manipulation/Calculations

numalias NAME,NUM

NAMEAlias name
NUMNumeric value given by alias

Creates a name that serves as an alias for a numeric value.

Example:
Use an alias "ef_lshutter" for the number 2.
numalias ef_lshutter,2
;Now the following 2 lines are equivalent.
bg "test.bmp",ef_lshutter
bg "test.bmp",2
Example:
(Advanced) Use a numeric alias for a variable number.
numalias akari_love,0
;Now the following 2 lines are equivalent.
add %akari_love,10
add %0,10

page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
ofscpy

Image Display

ofscpy

Copies things drawn using a blt command to the offscreen buffer.
Explanation:
Once you have blitted an image onto the screen, and want to use an effect on it, you would use this command to copy it to the offscreen buffer.
The offscreen buffer saved by this command may be used in effects, just like any other screen buffer.
The image and the effect will display, but they will not be remembered via load/save.

By using blt and ofscpy together, you can create engine cutscenes and such (like those found in AIR).

Example:
btndef "~"
;read animation images

bg ~
ld c,~
;all commands up until this point have been standard image commands, so they will show fine.

resettimer
blt ~
waittimer 100
blt ~
waittimer 100
;in this fashion we display images one after the other for an engine cutscene.

;now that we've blitted a bunch of stuff, to use effects on the image, we need to copy it to the offscreen buffer.
ofscpy
bg ~

;and now you can do anything you want to either the onscreen or the offscreen buffer.
bg ~
ld c,~

blt /
page top / list / main

Ver.2.47[Definition/Program Block]( NScr )
okcancelbox

Miscellaneous

okcancelbox %VAR,STR,STR

VARResult: 1 for OK, 0 for Cancel
STRMessage to display
STRDialog box title

Shows a Windows OK/Cancel dialog box and retrieves user input.

Example:
Creates an OK/Cancel dialog titled "セーブ確認" (Confirm Save) with the message "セーブします。" (About to Save).
okcancelbox %0,"セーブします。","セーブ確認"

yesnobox /
page top / list / main

Ver.(undoc)[Definition Block Only]( NScr2.82, ONScr20080121, ONScr-EN20080310 )
pagetag

Pretext Tags

pagetag

A pretextgosub-enabled script will only check for [] pretext tags at the start of a page, not at the start of every line (or text command).


pretextgosub / [] /
page top / list / main

[Definition/Program Block]( PONS20090926 )
pbreakstr

PONScripter Commands

pbreakstr STR

STRBreak characters

pbreakstr basic

ENUMKeyword for the standard linebreaking characters

Specifies a set of characters that allow linebreaks; if necessary for word-wrapping, ponscripter will make a new line right after one of these characters.
Giving an empty string will clear all linebreak characters (including space!)

Using the basic keyword will set the following characters as breaking:
' ' U+0020 (space - default)
- U+202d (hyphen-minus)
U+2013 (en dash)
- U+2014 (em dash)

*
Since ponscripter-20091015, scripts start out with only the space character defined for linebreaking, so please use this command if you want other break characters. pbreakstr basicwill restore the default break characters from earlier ponscripter versions. (by Mion)
PONScripter Example:
Sets space, comma and hyphen as break characters.
pbreakstr ^ ,-^

~ /
page top / list / main

[Definition/Program Block]( PONS20090926 )
pfontstyle

PONScripter Commands

pfontstyle STR

STRFont style tag

Sets the default text styling. This command is equivalent to inserting a ~d STR~
formatting tag at the start of every subsequent text command (though it has no effect on sprites).

Only font style tags are may be used; size and position tags are not supported.

PONScripter Example:
Displays text in italic display font (slot 5).
pfontstyle "si"
^Here is a page of italic text.\
^And it's still italic!\
pfontstyle ^d^ ;back to regular style

~ / pmapfont /
page top / list / main

[Definition/Program Block]( PONS20090926 )
pindentstr

PONScripter Commands

pindentstr STR

STRIndent characters

pindentstr basic

ENUMKeyword for the standard indenting characters

Specifies a set of characters where, if one appears as the first character of a page, it will set an indent; this is equivalent to following the character with a ~n~ formatting tag.
Giving an empty string will clear all indent characters.

Using the basic keyword will cause indenting on the following characters:
( U+0028 (left paren)
- U+2014 (em dash)
U+2018 (left single curly quote)
U+201c (left double curly quote)
U+300c (left corner bracket)
U+300e (left white corner bracket)
U+ff08 (fullwidth left paren)
U+ff5e (fullwidth tilde)
U+ff62 (halfwidth left corner bracket)

*
Since ponscripter-20091015, scripts start out with nodefined indent characters, so please use this command if you want indenting characters.
pindentstr basicwill restore the default indent characters from earlier ponscripter versions. (by Mion)
PONScripter Example:
Sets quote marks (undirected and left) as indenting characters.
pindentstr ^"'‘“^

~ /
page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
play

Music/SFX Playback

play STR

STRMIDI filename or CD track number label

Plays a MIDI file or CD audio track.

If you specify a file name, then the corresponding MIDI file will be played, but if you specify "*(number)", then the appropriate CD track will play.

play will loop the MIDI file/CD audio; if you want a file/track to play once, use the playonce command.


playstop /
page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
playonce

Music/SFX Playback

playonce STR

STRMIDI filename or CD track number label

Plays a MIDI file or CD audio track.

If you specify a file name, then the corresponding MIDI file will be played, but if you specify "*(number)", then the appropriate CD track will play.

Use play to loop the MIDI file/CD audio instead of playing just once.


playstop /
page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
playstop

Music/SFX Playback

playstop

Stops MIDI/CD audio playback.


page top / list / main

[Definition/Program Block]( PONS20090926 )
pligate

PONScripter Commands

pligate STR,NUM|STR

STRShortcut matching text
NUMUnicode codepoint for shortcut result (if numeric)
STR(Unicode) char for shortcut result (if string)

pligate STR,remove

STRShortcut matching text
ENUMKeyword to remove the defined matching shortcut

pligate {none|default|basic|punctuation|f_ligatures|specials|all}

ENUMKeyword for a preset shortcut set

Adds or removes shortcut sequences. This commands lets you define a sequence of ASCII (or Unicode) characters to be replaced with a single Unicode character within text, for use as shortcuts or mappings to ligatures.

The Unicode result for a particular shortcut may be given either as the numeric value of a Unicode codepoint, or as a string whose first (Unicode) character will be used as the result. Use the bareword remove to remove the shortcut with the defined sequence.

In its single-argument form, this command enables the specified preset shortcuts. Valid arguments are:

none - will remove all defined shortcuts, even defaults
all - adds all of the following preset shortcuts
default - enables basic and specials presets (default)
f_ligatures - adds ligatures for "ff", "fi", "fl", "ffi", and "ffl"
specials - adds the hash escape sequences for the special characters @, /, \, _, ^, `, !, #
basic - adds the following sequences for quotes:
"`" (left single quotation mark)
"``" (left double quotation mark)
"'" (right single quotation mark)
"''" (right double quotation mark)
punctuation - adds shortcuts for these punctuation symbols:
"%-" (non-breaking hyphen)
"%_" U+00A0 (non-breaking space)
"%." U+2009 (thin space)
"..." (horizontal ellipsis)
"--" (en dash)
"---" (em dash)
"(c)" © (copyright sign)
"(r)" ® (registered sign)
"(tm)" (trademark sign)
"++" (dagger)
"+++" (double dagger)
"**" (bullet)

To display a shortcut sequence as-is within text, insert a Unicode zero-width non-joiner (ZWNJ) or its builtin shortcut | within the sequence to prevent it from matching the shortcut. (The ZWNJ will not be displayed).
If the Unicode character for a shortcut/ligature is not present in the current font, that shortcut sequence will not be replaced in text.

Please note that this command, and ligature/shortcut processing in general, are not available in onscripter compatibility mode.

PONScripter Example:
Defines shortcuts and displays text using them.
pligate basic ;presets for curly quotes
pligate "-->",0x2192 ;rightwards arrow
pligate "'",remove ;don't replace single apostrophe with curly quote

^``Check it out --> it's my funky-cool shortcut example.''\
;assuming a font that contains all those glyphs, the previous text should display as:
;“Check it out → it's my funky-cool shortcut example.”

page top / list / main

[Definition/Program Block]( PONS20090926 )
pmapfont

PONScripter Commands

pmapfont NUM,STR[,STR]

NUMFont slot (0-7)
STRFont filename
STRFont metrics file (Type 1 fonts only)

Maps a font file to the given font slot.
For TrueType and OpenType fonts, the font file should be of type ".ttf" or ".otf"; for Type 1 fonts, the font file should be of type ".pfa" or ".pfb", with the metrics option providing the corresponding ".afm" file.

Filenames are relative to the game's data path. If a file is not found there, it is then sought within a "fonts" subdirectory of the data path, then in the game's archive, and then in the game binary itself (in case the font has been embedded).
As a last resort, and for compatibility, Ponscripter checks for a file named "default.ttf" in the game's data path.

The eight font slots are intended to represent two typefaces (a text face and a display face), each with regular, italic, bold, and bold-italic styles, as follows:
slot 0 - text face, regular font
slot 1 - text face, italics font
slot 2 - text face, bold font
slot 3 - text face, bold-italic font
slot 4 - display face, regular font
slot 5 - display face, italics font
slot 6 - display face, bold font
slot 7 - display face, bold-italic font
You can, of course, assign fonts however you like, but following this convention permits straightforward use of mnemonic formatting tags.

Note that mapping fonts in this way is optional - a slot that has not had a font assigned to it via pmapfont will use the default filename "faceN.ttf", where N is the slot number.

PONScripter Example:
Maps font slot 0 to "myprettyfont.ttf".
pmapfont 0,"myprettyfont.ttf"

page top / list / main

[Definition/Program Block]( PONS20090926 )
prendering

PONScripter Commands

prendering {none|full|light},{integer|float}[,{light|normal}]

ENUMHinting (either none, full, or light)
ENUMPositioning (either integer or float)
ENUMOptional Freetype rendering mode (light or normal)

Configures the Freetype text rendering mode.

Hinting can be one of the following:
none - no hinting (default)
full - Freetype hinting
light - Light hinting
The optimum settings depend on the fonts in use. In general, Freetype hinting makes TrueType fonts look hideous, but it does sometimes help with Type 1 fonts.

Use the bareword integer for positioning - although float is available and uses subpixel positioning, which would in theory give better spacing, it has never worked properly and tends to look awful.

The optional parameter can be used to override the Freetype rendering mode. It should be one of the barewords light or normal. By default, light rendering is used with light hinting, and normal rendering otherwise.


page top / list / main

[Definition Block Only]( NScr2.46, ONScr, ONScr-EN, PONS )
pretextgosub

Pretext Tags

pretextgosub LABEL

LABELLabel to jump to before a text command

Sets a subroutine to jump to immediately before a display text command.
If this command is used, a script can use a "tag", or data enclosed within square brackets [], immediately before any line of text.
For example, in the following code, the [太郎/0001.wav] is a tag:
[太郎/0001.wav]テスト用の文章です。

Example:
Specifies that execution will jump to the *pretext_lb subroutine before each line of text
pretextgosub *pretext_lb
Example:
Example pretextgosub routine
pretextgosub *pretext_lb

*pretext_lb
dwavestop 0
gettag $0,$1
;assuming first item is person name, second is voice dialog file
if $0="" indent 0:goto *next_tag
mov $2,$0
add $2,"/"
puttext $2
;this displays "(Name)" right before the actual text
;the "/" is to keep puttext from adding a newline
indent 3
;indents text for character dialog
*next_tag
if $1="" return
dwave 0,$1
;play the voice file
return

[] / gettag / indent /
page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
print

Image Display

print EFFECT

EFFECTDisplay effect

Draws to the screen utilizing the designated effect.

You may set the effect to use in one of two ways:
1) By effect tag
0: draws only to memory, not to screen
1: instantaneous display
>1: the tag of an effect defined by the effect command

2) Direct designation
2-18: Use the same parameters as used for the effect command
99: Use for plugin-based effects. You must provide a plugin specification string of format: "plugin-name/plugin-parameters".


The following display commands, like print, take effect specs:
bg ld cl

All other display-related commands must be followed by print or one of the above commands in order to update the screen display.

*
Plugin-based effect support was added in ver.2.03, and the effect plugin api was extended in ver.2.37. Only NScripter supports plugins.
At present, ONScripter-EN supports the following "plugin-based" wipe effects (originally created by Takashi Toyama), via emulation: "breakup.dll", "cascade.dll", "trvswave.dll", "whirl.dll". (by Mion)
Example:
Display the background "test.jpg" and the standing picture "testman.jpg" simultaneously, then remove the standing picture using set effect 3.
bg "test.jpg",0
ld c,"testman.jpg",1
cl c,3
Example:
Display the background "test.jpg" via a one-second crossfade, then display the standing picture "testman.jpg" on the left side via a two-second masked fade using "mask.bmp".
bg "test.jpg",10,1000
ld "testman.jpg",15,2000,"mask.bmp"
Example:
Display the background "test.jpg" via the plugin-effect "clockwip.dll".
bg "test.jpg",99,1000,"clockwip.dll/l"

effect /
page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
prnum

Character/Number/Bar Display

prnum NUM,NUM,NUM,NUM,NUM,NUM,COLOR

NUMNumeric label number
NUMCurrent value
NUMTop-left X-coordinate
NUMTop-left Y-coordinate
NUMCharacter width
NUMCharacter height
COLORLabel color

Creates a numeric value label, and then blits its current value in the given position at the given size and color.
A label can take 3 columns, so they can range from 0 to 999 in value.
You need to call a print command or something like it to actually display this onscreen.

bar and prnum were specifically created for mode_saya, which was in-turn specifically created for the doujin game "Saya ~Labyrinth of Immorality~".
There are plans to replace these commands with something a little bit more generalized and powerful.

*
Deprecated since ver2.93; the behavior of this command is environment-dependent.

page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
prnumclear

Character/Number/Bar Display

prnumclear

Clears the numeric value labels.


prnum /
page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
puttext

Text Display

puttext STR

STRCharacter string to display

Displays the given character string onscreen. This command is most often used within if statements to display some short indicator; otherwise its efficacy is limited.
When using puttext, you may not use any of the variable designation/value functions (e.g. % or $) with it.


page top / list / main

[Program Block Only]( NScr1.80, ONScr, ONScr-EN, PONS )
quake

Visual Effects

quake NUM,NUM

NUMAmplitude (pixels)
NUMDuration (msec)

Causes an onscreen random quake effect of the given amplitude and duration. Can be slow on older graphics cards.

Example:
This shakes the screen for 1 second with an 8-pixel amplitude.
quake 8,1000

quakex / quakey /
page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
quakex

Visual Effects

quakex NUM,NUM

NUMAmplitude (pixels)
NUMDuration (msec)

Works just like quake, except it only shakes the screen from side-to-side (horizontally).


quake /
page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
quakey

Visual Effects

quakey NUM,NUM

NUMAmplitude (pixels)
NUMDuration (msec)

Works just like quake, except it only shakes the screen up-and-down (vertically).


quake /
page top / list / main

[Program Block Only]( NScr2.55, ONScr-EN20091122 )
r_trap

Click Traps

r_trap LABEL

LABELDestination for jump upon right-click

r_trap off

After this command, a right-click will cause a jump to the specified label.
This trap mode deactivates itself immediately thereafter, or you can deactivate it manually (before the jump happens) by using r_trap off.
It behaves the same as trap and lr_trap, except that it only activates on right-clicks.

*
This command also reacts to left-clicks since ver2.75. (by senzogawa) -WHY? isn't that what lr_trap is for? (by Mion)

trap / lr_trap /
page top / list / main

Ver.2.40[Definition/Program Block]( NScr )
readfile

Data Acquisition

readfile $VAR,STR

VARString variable for the file read result
STRA text filename

Reads the contents of the given file into the given string variable.

*
Note that this also reads CRLF (\x0d\x0a) line endings; when writing multiple lines to a file that will be processed with readfile, these ending bytes must be skipped since relative operators cannot process CR or LF.
Also, since calling readfile does not affect the file log, fchk cannot be used to determine if the file was read.
Example:
Reads the contents of "file.txt" into $0.
readfile $0,"file.txt"

split /
page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
repaint

Image Display

repaint

Repaints the screen. Call this command if you start getting strange artifacting and such onscreen.


page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
reset

Game Start/End/Quit

reset

Resets the game and returns to the start of the program block.


*start /
page top / list / main

Ver.1.98[Definition Block Only]( NScr )
resetmenu

Window Menubar

resetmenu

Declares creation of a custom menubar. Add menu items after this command using insertmenu.


killmenu / insertmenu / deletemenu /
page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
resettimer

Wait/Timer

resettimer

Sets the internal timer back to 0. This timer runs on a millisecond scale.


page top / list / main

[Definition/Program Block]( NScr, ONScr, ONScr-EN, PONS )
return

Jumps

return [LABEL]

LABELOptional return destination

Used at the end of a routine called by gosub to return to the next command after the gosub call itself.

*
The optional return destination label was added in Ver.2.67. (by senzogawa)

gosub /
page top / list / main

Ver.(undoc)[Definition Block Only]( NScr, ONScr-EN20091122 )
rgosub

Right-Click Functionality

rgosub LABEL

LABELDestination to jump to upon right-click

This sets a routine to call at right-clicks.
The given label will be called using a gosub, so that a return will go back to the waiting point where the right-click was detected.

*
The systemcall command doesn't work if rgosub is defined (by BBS)

rmenu /
page top / list / main

[Definition Block Only]( NScr, ONScr, ONScr-EN, PONS )
rlookback

Right-Click Functionality

rlookback

Activate Log Mode by using a right click.


page top / list / main

[Definition Block Only]( NScr, ONScr, ONScr-EN, PONS )
rmenu

Right-Click Functionality

rmenu STR,{skip,reset,save,load,lookback,windowerase}[,...]

STRRight-click menu display string
STRRight-click menu function name

Defines a system menu to show upon right-click.
The character string is menu item text, and the function is picked from the list defined below.

SYSTEM MENU FUNCTION NAMES:
skip - same as "skip to next choice"
reset - reset program
resetdlg - same as reset? save - go to save menu
load - go to load menu
lookback - go to log mode
windowerase - remove text window
end - exit the program

Example:
Display 3 elements in the right-click menu: "セーブ" for the Save menu function, "ロード" for the Load menu function, and "回想" for Log Mode.
rmenu "セーブ",save,"ロード",load,"回想",lookback

page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
rmode

Right-Click Functionality

rmode NUM

NUMRight-click active toggle (0:off, 1:on)

Toggles right-click functionality on (1) or off (0).


page top / list / main

[Definition/Program Block]( NScr, ONScr, ONScr-EN, PONS )
rnd

Variable Manipulation/Calculations

rnd %VAR,NUM

VARNumeric variable
NUMUpper range for the random number (0 to n-1)

Generates a random number and sticks it in the numerical variable, ranging from 0 to (number - 1).

*
The command has no effect if 0 is given as the second number. (by senzogawa)
Example:
Get a random value from 0 to 99 and assign it to %5.
rnd %5,100

page top / list / main

[Definition/Program Block]( NScr, ONScr, ONScr-EN, PONS )
rnd2

Variable Manipulation/Calculations

rnd %VAR,NUM,NUM

VARNumeric variable
NUMLower range for the random number
NUMUpper range for the random number

Generates a random number ranging from number 1 to number 2.

Example:
Get a random value from 10 to 20 and assign it to %3.
rnd2 %3,10,20

page top / list / main

[Definition Block Only]( NScr, ONScr, ONScr-EN, PONS )
roff

Right-Click Functionality

roff

Set default behavior of right-click as null/do nothing.


page top / list / main

[Definition/Program Block]( NScr2.30, ONScr, ONScr-EN, PONS )
rubyoff

Ruby Text

rubyoff

Turns off ruby mode, thereby disallowing ruby text.


() / rubyon /
page top / list / main

[Definition/Program Block]( NScr2.30, ONScr, ONScr-EN, PONS )
rubyon

Ruby Text

rubyon [NUM,NUM[,STR]]

NUMRuby char width (default: half of main text width)
NUMRuby char height (default: half of main text height)
STRRuby text font name

Turns on ruby mode.

Example:
Enters ruby mode, using the set text font and half the set text sizes for displaying ruby text.
rubyon
Example:
Enters ruby mode, using the set text font, width 10, and height 8 for displaying ruby text. (It is probably best not to use ruby text bigger than 13x13, for anti-aliasing purposes.)
rubyon 10,8
Example:
Enters ruby mode, using width 14, height 12, and Japanese font "MS Gothic" for displaying ruby text.
rubyon 14,12,"MS ゴシック"

() / rubyoff /
page top / list / main

[Program Block Only]( NScr2.80, ONScr-EN20100105 )
rubyon2

Ruby Text

rubyon2 NUM,NUM

NUMRuby char width
NUMRuby char height

This changes to ruby mode, but only when ruby appears in the current line. (Assumed to be used for quick-display modes; will also allow ruby text in strsp commands.)

*
Please note that text may be shifted to make room for ruby text.
*
Still not clear to me what this command's documentation means; for now, ONScr-EN recognizes this command but does no special handling. (by Mion)

rubyoff / rubyon / strsp /
page top / list / main

[Definition Block Only]( NScr2.49, ONScr-EN )
savedir

Save/Load

savedir STR

STRName of directory where save data will be stored

This specifies a folder to use for storing save data.

*
When this command is used (in NScripter), only the file "envdata" will be stored in the same location as "nscr.exe".
Be sure the savedir exists beforehand.
*
ONScripter-EN and PONScripter already store game & save data in a separate folder from the game; this location can be adjusted via the "-s" command line option.
This behavior is separate from the savedir command, which is used to specify a directory relative to the game/save folder (holding all but "envdata". (by Mion)
Example:
Sets so that save data files will be stored in the folder "savedata".
savedir "savedata"

savegame /
page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
savefileexist

Save/Load

savefileexist %VAR,NUM

VARResult numeric variable (0: doesn't exist, 1: exists)
NUMSavefile number

Returns 1 if the savefile exists, 0 if it does not.


page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
savegame

Save/Load

savegame NUM

NUMSavefile number

Saves the game under the given save number. This does not ask for confirmation, so be careful.


page top / list / main

[Program Block Only]( NScr2.60, ONScr, ONScr-EN, PONS )
savegame2

Save/Load

savegame2 NUM,STR

NUMSavefile number
STRString to store with the save

Stores a particular character string with each save file; otherwise, it works the same as savegame.

Example:
Along with Save Game 12, this stores the string "8月5日 ヒロインAルート"
savegame2 12,"8月5日 ヒロインAルート"
ONScripter Example:
Along with Save Game 12, this stores the string "Aug. 5 -Heroine A route-"
savegame2 12,`Aug. 5 -Heroine A route-`

savegame / getsavestr /
page top / list / main

[Definition Block Only]( NScr, ONScr, ONScr-EN, PONS )
savename

Right-Click Functionality

savename STR,STR,STR

STRSave menu title
STRLoad menu title
STRSavefile line heading

Designates the display strings for savefiles.
From left to right, the strings are: title for the save menu, title for the load menu, and then the name of the save itself.
By default, these are "<セーブ>","<ロード>","しおり" -- note that these are all double-byte character strings.

*
ONScripter-EN and PONScripter have the following for defaults: "Save", "Load", "Slot".

page top / list / main

[Definition Block Only]( NScr, ONScr, ONScr-EN, PONS )
savenumber

Save/Load

savenumber NUM

NUMSavefile capacity

Change the limit on the number of save files. At most, this can be 20, and the default is 9.
If you are not careful to make sure that the save menu does not overflow the bottom of the screen (using menusetwindow), this command could cause the interpreter to hard crash.


menusetwindow /
page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
saveoff

Save/Load

saveoff

Turns Save Mode off.
This does not mean that you cannot save; it means that when you load, the position at which the player starts will be at the last place where saveon was set.
Why would you ever want to turn save mode off? When save mode is on, it records every sprite ever loaded into a log -- causing moderate to massive amounts of slowdown when you are attempting to do a fast animation. In these cases, you should definitely call saveoff before you start the animation, then call saveon once you've finished.


page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
saveon

Save/Load

saveon

Turns Save Mode back on (also see saveoff for more details).


saveoff /
page top / list / main

Ver.2.93[Program Block Only]( NScr )
savepoint

Save/Load

savepoint

Updates the save point.
Use this when the autosaveoff command is used in the define block.
Timing issues may slow down returns from data updates, for example when updating a save point after drawing over the entire screen, so please use common sense.


autosaveoff /
page top / list / main

[Program Block Only]( NScr2.25, ONScr, ONScr-EN, PONS )
savescreenshot

Screenshot

savescreenshot STR

STRScreenshot filename

Saves a screenshot collected via getscreenshot.
This also deletes the screenshot image from memory; use savescreenshot2 instead if you need to reuse the screenshot image.

Example:
Saves the last collected screenshot as "thumb01.bmp".
savescreenshot "thumb01.bmp"

getscreenshot / savescreenshot2 / deletescreenshot /
page top / list / main

[Program Block Only]( NScr2.30, ONScr, ONScr-EN, PONS )
savescreenshot2

Screenshot

savescreenshot2 STR

STRScreenshot filename

Saves a screenshot collected via getscreenshot as the given filename.
This does not delete the screenshot image from memory, so please use deletescreenshot to remove it from memory when finished.


getscreenshot / savescreenshot / deletescreenshot /
page top / list / main

[Program Block Only]( NScr1.97, ONScr, ONScr-EN, PONS )
savetime

Data Acquisition

savetime NUM,%VAR,%VAR,%VAR,%VAR

NUMSavefile number
VARNumeric variable for the save month
VARNumeric variable for the save date
VARNumeric variable for the save hour
VARNumeric variable for the save minute

Gets the month, day, hour of the day, and minutes of the hour in which a particular save was recorded.
If the save file does not exist, then the %month parameter is set to 0.

Example:
Retrieves the save time and date of savefile 3, or else explains that the savefile was not found.
savetime 3,%0,%1,%2,%3
if %0=0 goto *non
;save found
セーブ3番は%0月%1日%2時%3分@
end
*non
;save not found
セーブ3番は存在しない。@
end

page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
select

Choices

select STR,LABEL[,STR,LABEL[,...]]

STRDisplayed choice
LABELChoice select destination

Displays a selection of choices, and then jumps to the label associated with the selected choice.
If the character string is set to "", then that choice will not be displayed.
(This works the same way as selnum and selgosub.)
But be careful, as this command will cause the interpreter to hang if you do not specify even a single choice as a parameter.


page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
selectbtnwait

System Customization

selectbtnwait %VAR

VARNumeric variable for button number

Waits for a click during a *customsel routine.

Example:
Waits for a click and assigns the clicked button number to %0.
selectbtnwait %0

csel / *customsel / getcselnum / cselgoto / getcselnum / getcselstr /
page top / list / main

[Definition Block Only]( NScr, ONScr, ONScr-EN, PONS )
selectcolor

Choices

selectcolor COLOR,COLOR

COLORMouseover color
COLORMouseoff color

Specifies, in order, the mouseover and the mouseoff colors for choice text.


page top / list / main

[Definition Block Only]( NScr, ONScr, ONScr-EN, PONS )
selectvoice

Choices

selectvoice STR,STR,STR

STRWAV file that plays at choice dialog entry
STRWAV file that plays upon mouseover of a choice
STRWAV file that plays when a choice is clicked

Designate WAV files to play in the choice dialog. From left to right: upon entry into choice dialog, upon mouseover of choice text, and finally upon clicking on a choice text.


page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
selgosub

Choices

selgosub STR,LABEL[,STR,LABEL[,...]]

STRDisplayed choice
LABELChoice select destination

Works the same as select, except this command jumps to a subroutine, not a generalized label.


select /
page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
selnum

Choices

selnum %VAR,STR[,STR[,...]]

VARNumeric result variable
STRDisplayed choice

Works somewhat like select and selgosub, except that there are no jumps - instead, depending on which character string is clicked, a number (starting at 0, then incrementing by 1 for each string) is loaded into the given numeric variable.

*
Unlike with select and selgosub, a null character string ("") can't be provided as a choice. (by senzogawa)

select /
page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
setcursor

Cursor

setcursor NUM,STR,NUM,NUM

NUMCursor number (0: click-wait cursor, 1: page-wait cursor)
STRCursor image filename
NUMCursor horizontal displacement (right)
NUMCursor vertical displacement (down)

Loads and displays a cursor definition file for use during click wait states.
The numbers comprise an (x,y) coordinate positioned relative to the upper left pixel of the next text display character.

The default settings are:
setcursor 0,":l/3,160,2;cursor0.bmp",0,0
setcursor 1,":l/3,160,2;cursor1.bmp",0,0


abssetcursor /
page top / list / main

[Definition Block Only]( NScr2.70, ONScr-EN )
setkinsoku

Text Display

addkinsoku STR,STR

STRString of characters forbidden at line start
STRString of characters forbidden at line end

Much as English has linebreak rules, Japanese defines certain characters as "kinsoku" - forbidden from either starting or ending a line of text (e.g. end/start quotes, parentheses, and other punctuation).

This command specifies which (fullwidth) text characters will be treated as "kinsoku" for the purposes of text display: the first string contains characters forbidden at the start of a line, while the second string contains characters to be forbidden at the end of a line.

The default kinsoku characters for NScripter are "」』)]}、。,.・?!ヽヾゝゞ々ー" (start) and "「『([{" (end).


addkinsoku /
page top / list / main

[Definition Block Only]( NScr2.03, ONScr-EN20090411 )
setlayer

Plugins/Archives

setlayer NUM,NUM,STR

NUMLayer number
NUMLayer update interval (msec)
STRDLL filename

This registers a layer number for a particular plugin DLL.
Messages may be sent to the plugin via layermessage.

*
At present, ONScripter-EN supports the following "plugin-based" layer effects (originally created by Takashi Toyama), via emulation: "hana.dll", "oldmovie.dll", and "snow.dll". (by Mion)

layermessage /
page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
setwindow

Text Window

setwindow NUM,NUM,NUM,NUM,NUM,NUM,NUM,NUM,NUM,NUM,NUM,COLOR,NUM,NUM,NUM,NUM

NUMX-coordinate of top left for text
NUMY-coordinate of top left for text
NUMNumber of (full-width) text columns
NUMNumber of text lines
NUM(Full-width) text font size X
NUMText font size Y
NUMText spacing X
NUMText spacing Y
NUMDefault text speed
NUMBoldface toggle (0=off/1=on)
NUMDrop shadow toggle (0=off/1=on)
COLORWindow color
NUMWindow top left X-coordinate
NUMWindow top left Y-coordinate
NUMWindow bottom right X-coordinate
NUMWindow bottom right Y-coordinate

setwindow NUM,NUM,NUM,NUM,NUM,NUM,NUM,NUM,NUM,NUM,NUM,STR,NUM,NUM

NUMX-coordinate of top left for text
NUMY-coordinate of top left for text
NUMNumber of (full-width) text columns
NUMNumber of text lines
NUM(Full-width) text font size X
NUMText font size Y
NUMText spacing X
NUMText spacing Y
NUMDefault text speed
NUMBoldface toggle (0=off/1=on)
NUMDrop shadow toggle (0=off/1=on)
STRImage file name
NUMWindow top left X-coordinate
NUMWindow top left Y-coordinate

Sets up the text window.
The first form is used when the backdrop for the text window is an alpha-layered solid color.
The second form is used when the backdrop for the text window is a graphic file.

By default, the text window takes up the full screen and is somewhat translucent, the font is 26x26 pixels, the spacing is 0,2, the top left coordinate is 8,16, there are 23 2-byte columns and 16 lines, boldface and drop shadow enabled, 20 speed, and a translucent color of #999999.

Example:
Text window with default settings
setwindow 8,16,20,23,26,26,0,2,20,1,1,#999999,0,0,639,479
Example:
Text window with default settings, but using image file "bgi.bmp" as backdrop
setwindow 8,16,20,23,26,26,0,2,20,1,1,"bg1.bmp",0,0

setwindow2 / setwindow3 /
page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
setwindow2

Text Window

setwindow2 COLOR

COLORWindow color

setwindow2 STR

STRImage file name

This modifies the appearance of the text window without deleting either it or the text backlog.
This command can only modify the color or image file that was first specified in setwindow, and none of the other parameters.

Example:
This modifies the text window to use image file "twindow2.bmp" as backdrop.
setwindow2 ":c;twindow2.bmp"

setwindow / setwindow3 /
page top / list / main

[Program Block Only]( NScr2.30, ONScr, ONScr-EN, PONS )
setwindow3

Text Window

setwindow3 NUM,NUM,NUM,NUM,NUM,NUM,NUM,NUM,NUM,NUM,NUM,COLOR,NUM,NUM,NUM,NUM

NUMX-coordinate of top left for text
NUMY-coordinate of top left for text
NUMNumber of (full-width) text columns
NUMNumber of text lines
NUM(Full-width) text font size X
NUMText font size Y
NUMText spacing X
NUMText spacing Y
NUMDefault text speed
NUMBoldface toggle (0=off/1=on)
NUMDrop shadow toggle (0=off/1=on)
COLORWindow color
NUMWindow top left X-coordinate
NUMWindow top left Y-coordinate
NUMWindow bottom right X-coordinate
NUMWindow bottom right Y-coordinate

setwindow3 NUM,NUM,NUM,NUM,NUM,NUM,NUM,NUM,NUM,NUM,NUM,STR,NUM,NUM

NUMX-coordinate of top left for text
NUMY-coordinate of top left for text
NUMNumber of (full-width) text columns
NUMNumber of text lines
NUM(Full-width) text font size X
NUMText font size Y
NUMText spacing X
NUMText spacing Y
NUMDefault text speed
NUMBoldface toggle (0=off/1=on)
NUMDrop shadow toggle (0=off/1=on)
STRImage file name
NUMWindow top left X-coordinate
NUMWindow top left Y-coordinate

This behaves the same as setwindow but without clearing the Log mode buffer.

*
Entering Log Mode may be buggy if the text window isn't set to the same width and height.
Example:
Sets text window with default settings without clearing log
setwindow3 8,16,20,23,26,26,0,2,20,1,1,#999999,0,0,639,479
Example:
Sets text window with default settings, but using image file "bgi.bmp" as backdrop, without clearing log
setwindow3 8,16,20,23,26,26,0,2,20,1,1,"bg1.bmp",0,0

setwindow / setwindow2 /
page top / list / main

[Program Block Only]( NScr1.98, ONScr, ONScr-EN, PONS )
sevol

Music/SFX Playback

sevol NUM

NUMSound volume (0-100)

Changes the sound volume.

*
Volume changes are not saved, so manage them manually or with variables.
Example:
Sets sound effect volume to maximum (100)
sevol 100

chvol / mp3vol / voicevol / bgmvol /
page top / list / main

[Definition/Program Block]( NScr2.25, ONScr, ONScr-EN, PONS )
shadedistance

Text Display

shadedistance NUM,NUM

NUMShadow offset width (pixels)
NUMShadow offset height (pixels)

Sets the text shadow position.

*
NScr Ver.2.62 added this command to the program block as well.
The shadow position will not return to the default setting even at reset. (by senzogawa)
Example:
Sets the text shadow offset to 2 pixels right and 3 pixels down
shadedistance 2,3

page top / list / main

[Program Block Only]( NScr, ONScr-EN20080310, PONS20100324 )
shell

External Command Execution

shell STR

STRName of external file (or URL)

Executes the given file via Explorer, using the ShellExecute API.
Note that shell execution is asynchronous with the game engine.

ONScripter-EN supports the shell command in Windows builds, and has basic support in Mac and Linux for using it to open a URL in the default web browser.


page top / list / main

[Definition/Program Block]( NScr2.25, ONScr, ONScr-EN, PONS )
sin

Variable Manipulation/Calculations

sin %VAR,NUM

VARNumeric result variable
NUMAngle (in degrees)

Acquires the trigonometric sine of the given angle, and returns the value multiplied by 1000.

Example:
Assigns the sine of 90 degrees to %0.
sin %0,90
;%0=1000, since sin(90)=1

cos / tan /
page top / list / main

[Definition/Program Block]( NScr, ONScr, ONScr-EN, PONS )
skip

Jumps

skip NUM

NUMNumber of script lines to skip

Skips the designated number of lines. Can skip forward (-) or backward (+).


page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
skipoff

Skip Mode

skipoff

Exits both "skip to next choice" mode and "auto mode".

*
Skip Mode can be enabled with "systemcall skip".
So, using defsub, you can create a "skipon" command with the follow code. (by senzogawa)
*skipon
systemcall skip
return
Example:
Exits any Skip Mode that may have been active.
skipoff

page top / list / main

[Definition Block Only]( NScr )
soundpressplgin

Plugins/Archives

soundpressplgin STR

STRPlugin specification

Using this, you can designate a dll file with which to decode other kinds of compressed sound files that are not mp3s. The character string format is "plugin-name|3-char-file-extension".

Example:
This specifies using "nbzplgin.dll" to open *.nbz sound files.
soundpressplgin "nbzplgin.dll|nbz"

page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
spbtn

Image Buttons

spbtn NUM,NUM

NUMSprite number
NUMButton number

Just like the btn command, except it sets up an image button using a sprite. It uses cell 0 as the graphic for the nonclicked state and cell 1 for the clicked state.
When the button is pressed during a btnwait, it returns the given button number as a value.


page top / list / main

[Program Block Only]( NScr1.99, ONScr, ONScr-EN, PONS )
spclclk

Button Extensions

spclclk

Use this between btndef and btnwait commands.
This will cause a wait command to give the same return value on a pressed Spacebar as for a left-click in the same situation.


btndef / btnwait /
page top / list / main

Ver.1.99[Definition/Program Block]( NScr )
spfont

Image Display

spfont STR,NUM,NUM,NUM,NUM,NUM,NUM

STRFont name
NUM(Full-width) text font width
NUMText font height
NUMText spacing X
NUMText spacing Y
NUMBoldface toggle (0=off/1=on)
NUMDrop shadow toggle (0=off/1=on)

spfont clear

ENUMclear: use font settings from setwindow

spfont STR

STRFont name

This sets the font to use for string sprites, e.g. ":s;名".
spfont clear reverts to using the font settings from setwindow.

It's also possible to omit all but the first argument: spfont (font-name)
Doing so will have string sprites use the given font face but all other settings will come from setwindow.

*
This command was allowed in the program block since ver2.62.
Ver2.66 corrected bugs with using spfont and setwindow settings.
The "clear" option was added in ver2.67.
Example:
Change the string sprite font to (JP) MS Gothic, 16x16, no spacing, bold & drop-shadowed.
spfont "MS ゴシック",16,16,0,0,1,1
Example:
Revert to the font settings of setwindow for string sprites.
spfont clear

lsp /
page top / list / main

[Definition Block Only]( NScr )
spi

Plugins/Archives

spi STR

STRPlugin specification

Allows for utilization of image compression plugin dll's - image filetypes that are not supported in standard NScripter. The character string format is "plugin-dll-name|file-extension".

Example:
This specifies using "jpgplgin.dll" to open *.jpg files, and "iflf2.spi" to open *.lf2 files.
spi "jpgplgin.dll|jpg"
spi "iflf2.spi|lf2"

page top / list / main

[Definition/Program Block]( NScr2.40, ONScr, ONScr-EN, PONS )
split

Variable Manipulation/Calculations

split STR,STR,$VAR|%VAR,$VAR|%VAR[,...]

STRCharacter string to split
STRDelimiter (must be just one character)
VARResult variable

Splits the given string at each occurrence of the given delimiter, and assigns the resulting portions to the given variables.
Use this command to process the results returned by readfile.

*
If a variable is repeated, its final result will be the last value portion assigned to it. (by eijipou)
If the string cannot be split (i.e. the delimiter never occurs), then numeric variables will be assigned the value 0 and string variables will receive the entire "split" string. (by senzogawa)
Example:
Splits $0 at every occurrence of "/", assigning the results to $1, $2, %0, %1, and $3.
mov $0,"あいうえお/かきくけこ/15/25/さしすせそ"
split $0,"/",$1,$2,%0,%1,$3

$1=$1 ; あいうえお
$2=$2 ; かきくけこ
%0=%0 ; 15
%1=%1 ; 25
$3=$3 ; さしすせそ
\

readfile /
page top / list / main

[Program Block Only]( NScr1.97, ONScr, ONScr-EN, PONS )
spstr

Image Display

spstr STR

STRsprite control string

You can use this command to manually control sprites using the control string format of the exbtn command.

Just like with csp, lsp and vsp, you need to call print afterwards to have anything show up on screen.

Example:
Clears Sprite 11, displays cell 2 of Sprite 10, and displays Sprite 9.
spstr "C11P10,2P9"

page top / list / main

Ver.1.97[Program Block Only]( NScr )
spwait

Wait/Timer

spwait NUM

NUMSprite number

Waits for the animation of the given sprite number to be either finished or cut short by the user.

Example:
Waits for the animation of Sprite 0 to finish.
spwait 0

page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
stop

Music/SFX Playback

stop

Stop playback of all sound.

*
Here, "all sound" means bgm and wave playback, but not loopbgm or dwave playback. (by Mion)

page top / list / main

[Definition Block Only]( NScr, ONScr, ONScr-EN, PONS )
stralias

Variable Manipulation/Calculations

stralias NAME,STR

NAMEAlias name
STRString value given by alias

Makes an alias for the given character string as then given name - in other words, after this declaration, you can refer to that character string using that NAME in all cases.

Example:
Use an alias "man_a0" for the file ":a/10,20,2;man_alpha.bmp".
stralias man_a0,":a/10,20,2;man_alpha.bmp"
;Now the following 2 lines are equivalent.
ld c,man_a0,1
ld c,":a/10,20,2;man_alpha.bmp",1

page top / list / main

[Program Block Only]( NScr2.62, ONScr, ONScr-EN, PONS )
strsp

Image Display

strsp NUM,STR,NUM,NUM,NUM,NUM,NUM,NUM,NUM,NUM,NUM,NUM[,COLOR[,...]]

NUMSprite number
NUMString of text to render as a sprite
NUMX-coordinate of top left
NUMY-coordinate of top left
NUMNumber of (full-width) text columns
NUMNumber of text lines
NUM(Full-width) text font width
NUMText font height
NUMText spacing X
NUMText spacing Y
NUMBoldface toggle (0=off/1=on)
NUMDrop shadow toggle (0=off/1=on)
COLOROptional color(s)

This creates a multi-line string sprite, using the font face specified by spfont.
Use "\" to move to the next line. Note that text will run to the end of the available columns and continue onto the next line, without using linebreak or kinsoku conventions, so the "\" are necessary for proper string display.
If optional colors are provided, then the sprite will have a cell for each given color, with the text in that color.

*
This command was originally an alias of logsp2, but was given its own specification in ver2.65.

spfont / strsph /
page top / list / main

[Program Block Only]( NScr2.81, ONScr-EN )
strsph

Image Display

strsph NUM,STR,NUM,NUM,NUM,NUM,NUM,NUM,NUM,NUM,NUM,NUM[,COLOR[,...]]

NUMSprite number
NUMString of text to render as a sprite
NUMX-coordinate of top left
NUMY-coordinate of top left
NUMNumber of (full-width) text columns
NUMNumber of text lines
NUM(Full-width) text font width
NUMText font height
NUMText spacing X
NUMText spacing Y
NUMBoldface toggle (0=off/1=on)
NUMDrop shadow toggle (0=off/1=on)
COLOROptional color(s)

Works the same as strsp, except that the sprite starts out hidden.


spfont / strsp /
page top / list / main

[Definition/Program Block]( NScr, ONScr, ONScr-EN, PONS )
sub

Variable Manipulation/Calculations

sub %VAR,NUM

VARNumeric variable
NUMNumeric value to subtract

Subtract a number from a numeric variable.

Example:
Subtract 6 from %0, then subtract the value of %2.
sub %0,6
sub %0,%2

add /
page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
systemcall

Miscellaneous

systemcall NAME

NAMEMenu function name

Works identically to the system menu functions.
The available function names are similar to the ones used by rmenu:
SYSTEMCALL MENU FUNCTION NAMES:
skip - same as "skip to next choice"
reset - reset program
resetdlg - same as reset?
save - go to save menu
load - go to load menu
lookback - go to log mode
windowerase - remove text window
automode - automatically advance text at each clickwait (delay time set by automode_time)
rmenu - opens the right-click menu

If you use systemcall in routines like select/selgosub, then you'll end up with something not very different from the title menu.
(In that case, it would probably be better to temporarily toggle off right-click menu functionality through rmode.)

Calling systemcall rmenu has the same effect as calling the right-click menu itself.
You'd use this when you wanted right-click menu functionality during a button wait state. Once you exit this right-click menu, the interpreter continues its execution at the command after systemcall.
(This can leave the screen and the interpreter stack in an inconsistent state, so be careful when using this command.)


rmenu / automode / automode_time /
page top / list / main

[Definition/Program Block]( NScr1.99, ONScr, ONScr-EN, PONS )
tablegoto

Jumps

tablegoto %VAR,LABEL[,LABEL[,...]]

VARNumeric variable with an index into the jumptable
LABELA jump destination label within the table

Creates a jump table.
If the variable is set to 0, it jumps to the first label; if 1, the second label; and so forth.

Example:
Jumps to one of *label0 - *label3, depending on the value of %0
tablegoto %0,*label0,*label1,*label2,*label3

goto /
page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
tal

Image Display

tal {l,c,r},NUM,EFFECT

ENUMstanding pic position (l: left, c: center, r: right)
NUMOpacity value (0 - 255)
EFFECTEffect for changing standing picture opacity

Changes the opacity of the specified standing picture to the given value: 0 is fully transparent, 255 is fully opaque.

*
The official manual omits the effect specification, which causes an error. (by senzogawa via "hau")

ld /
page top / list / main

[Definition/Program Block]( NScr2.25, ONScr, ONScr-EN, PONS )
tan

Variable Manipulation/Calculations

tan %VAR,NUM

VARNumeric result variable
NUMAngle (in degrees)

Acquires the trigonometric tangent of the given angle, and returns the value multiplied by 1000.

*
Please note that tan will return infinity if given values 90 and 270.
Example:
Assigns the tangent of 45 degrees to %2.
tan %2,45
;%2=1000, since tan(45)=1

sin / cos /
page top / list / main

[Program Block Only]( NScr2.03, ONScr, ONScr-EN )
tateyoko

Text Window

tateyoko NUM

NUMFlag (1: vertical text mode, 0: horizontal text mode)

Toggles vertical text display mode. See sample for details.

Example:
Sets vertical text display mode
tateyoko 1

page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
texec

System Customization

texec

Does text removal for a page-wait (within a textgosub routine). Also does line-feeds after regular clickwaits as applicable.


textgosub / textbtnwait / getcursorpos /
page top / list / main

Ver.2.82[Program Block Only]( NScr )
texec2

System Customization

texec2

Similar to texec, except that it does not remove text immediately - only once the following line is displayed.
(This is used to prevent erasing text at choices.)

*
Available since 2008/08/10 release

textgosub / textbtnwait / texec / getcursorpos /
page top / list / main

[Program Block Only]( NScr2.74, ONScr-EN )
textbtnoff

Text Buttons

textbtnoff

Textbuttons are usually active during a btnwait.
Using textbtnoff between btndef and btnwait commands will turn off text buttons during the wait.
This can be useful if, for example, textbuttons need to be off while other buttons are processed.

Example:
Inactivates buttons and textbuttons before waiting for user input.
btndef clear
textbtnoff
textbtnwait %0

btnwait / btnwait2 / textbtnwait /
page top / list / main

[Program Block Only]( NScr2.65, ONScr-EN )
textbtnstart

Text Buttons

textbtnstart NUM

NUMStarting number for unnumbered textbuttons (default: 1)

Specifies the starting number for unnumbered textbuttons; 1 is the default value.

Example:
Sets the starting number for unnumbered textbuttons to 3.
textbtnstart 3

<> /
page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
textbtnwait

System Customization

textbtnwait %VAR

VARNumeric variable for button number

Waits for a click during a custom wait routine, as defined by textgosub.

Example:
Waits for a click and assigns the clicked button number to %0.
textbtnwait %0

textgosub / texec / getcursorpos /
page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
textclear

Text Display

textclear

Remove the contents of the text window, but not the window itself.


page top / list / main

Ver.(undoc)[Program Block Only]( NScr2.82 )
textcolor

Text Display

textcolor COLOR

COLORColor to use for text

Changes the color of the text, using HTML hexadecimal color codes (e.g. #000000 for black, #ffffff for white, and #ffffaa for pale yellow).
Please note that it only changes the color of text displayed after this command, and not any of the text that came before.

*
This seems to have been added in the 2007/11/04 release. You must use this command to change text color if english mode is enabled. (by senzogawa)
Example:
Displays the text "blue font" in blue.
*define
english
game
*start
textcolor #0000ff
>blue font@
end

english /
page top / list / main

[Program Block Only]( NScr2.65, ONScr-EN )
textexbtn

Text Buttons

textexbtn NUM,STR

NUMTextbutton number
STRSprite control string

Adds complex behavior to a textbutton, in much the same manner as exbtn.


exbtn /
page top / list / main

Ver.2.49[Program Block Only]( NScr )
textfield

Miscellaneous

textfield $VAR,NUM,NUM,NUM,NUM,NUM,NUM,NUM

VARString variable that stores both the default and input result strings
NUMWindow top left X-coordinate
NUMWindow top left Y-coordinate
NUMWindow bottom right X-coordinate
NUMWindow bottom right Y-coordinate
NUMCharacter width (single-byte)
NUMCharacter height
NUMDouble-byte text (0: allow half-width, 1: full-width only)

This creates a text input window on the screen (not a dialog box) and waits for input.
The prior contents of the given string variable will be used as the default text.
Input is returned by hitting the Escape, Tab or Enter keys, or by left-clicking on-screen outside the textfield area.
To see if the Tab key was pressed, use getret %0
If %0 is 0, then Tab was not pressed, but if %0 is 1 then the Tab key was pressed to return input.

Example:
Produces a text input area within (100,50) to (320,70) that takes 10x20 (half-width) characters, with forced full-width input.
textfield $0,100,50,320,70,10,20,1

input / inputstr / inputnum /
page top / list / main

[Definition Block Only]( NScr, ONScr, ONScr-EN, PONS )
textgosub

System Customization

textgosub LABEL

LABELLabel called at clickwaits

Defines a label to jump to at click waits for system customization. The routine named by this label must handle all system menus, cursors, buttons, and user input during these wait states.

Example:
Sets to jump to "*text_1b" at clickwaits.
textgosub *text_lb

textbtnwait / texec / getcursorpos /
page top / list / main

[Program Block Only]( NScr2.49, ONScr, ONScr-EN, PONS )
texthide

Log Mode Customization

texthide

Hides the textwindow text, while leaving the window itself in place.
This is important for customized Log Mode display.


textshow /
page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
textoff

Text Window

textoff

Hide the text window.


texton /
page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
texton

Text Window

texton

Unhide/show the text window.


textoff /
page top / list / main

[Program Block Only]( NScr2.49, ONScr, ONScr-EN, PONS )
textshow

Log Mode Customization

textshow

Redisplays text that had been hidden with texthide.


texthide /
page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
textspeed

Text Display

textspeed NUM

NUMCharacter display speed (msec)

Changes the text display speed.
This has the same functionality as !s, except that you can specify a variable here.


!s /
page top / list / main

[Program Block Only]( NScr2.47, ONScr-EN )
textspeeddefault

Text Window

textspeeddefault

Sets text display speed to the default.
Same as !sd, this command is especially meant for use in english mode.


!sd / english /
page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
time

Data Acquisition

time %VAR,%VAR,%VAR

VARNumeric variable for the retrieved hour
VARNumeric variable for the retrieved minute
VARNumeric variable for the retrieved second

Retrieves the current time.


page top / list / main

[Program Block Only]( NScr1.99, ONScr-EN20091122 )
transbtn

Image Buttons

transbtn

This will prevent transparent areas of a button image from activating the button.
Please use this command after a btndef but before the btnwait command.


btndef / btnwait /
page top / list / main

[Definition Block Only]( NScr, ONScr, ONScr-EN, PONS )
transmode

Image Display

transmode {leftup,copy,alpha}

ENUMleftup: top-left pixel color, copy: no transparency, alpha: alpha-blend

Change the default transparency mode. leftup is the default setting.
This essentially makes any image-definition string without a transparency setting use "l" for leftup, "c" for copy, or "a" for alpha; see lsp for more details.


page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
trap

Click Traps

trap LABEL

LABELDestination for jump upon left-click

trap off

After this command, a left-click will cause a jump to the specified label.
This trap mode deactivates itself immediately thereafter, or you can deactivate it manually (before the jump happens) by using trap off.


page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
trap2

Click Traps

trap2 LABEL

LABELDestination for jump upon left-click during skip mode

trap2 off

This is the same as trap, except it is the one that should be used when "skip to next choice" mode is active.


trap /
page top / list / main

[Definition/Program Block]( NScr, ONScr, ONScr-EN, PONS )
underline

Image Display

underline NUM

NUMY-coordinate of ground line

Specifies the ground line for standing pictures. The default value is 479.

*
This command was allowed in the program block since ver2.92.

ld /
page top / list / main

[Definition Block Only]( NScr1.99, ONScr, ONScr-EN, PONS )
useescspc

Button Extensions

useescspc

Sets btnwait commands to detect when the Esc key or Spacebar is pressed.
The wait command will return -10 on Esc, -11 on Space.


btndef / btntime / btntime2 / btnwait / btnwait2 / spclclk / usewheel / getcursor / getenter / gettab / getfunction / getpage / getinsert /
page top / list / main

[Definition Block Only]( NScr1.97, ONScr, ONScr-EN, PONS )
usewheel

Button Extensions

usewheel

Sets btnwait commands to detect mouse wheel movement.
The wait command will return -2 on wheel up, -3 on wheel down.
Please note that, when usewheel is in effect, a button wait timeout (set by btntime) will return -5 instead of the usual -2.


btndef / btntime / btntime2 / btnwait / btnwait2 / spclclk / useescspc / getcursor / getenter / gettab / getfunction / getpage / getinsert /
page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
v

Music/SFX Playback

'v'NUM':'

NUMVoice file number

This is a shorthand command for playing voice files.
It is equivalent to wave "voice\(num).wav".

*
(p)onscr seem to map this command to wave "wav\(num).wav" instead. (by Mion)
Example:
This plays "voice\0001.wav" via the wave command before outputting text.
v0001:「これが0001番のせりふだよー」

wave / dv /
page top / list / main

[Reserved Syntax]( NScr2.25, ONScr, ONScr-EN, PONS )
value

Special Mode Settings

';value'NUM

NUMGlobal variable start boundary (0 - 4000)

If a script file has ";value500" as the first line, then this will set the starting number for global variables to 500.
To also change the window size mode, say to 800x600, use ";mode800,value500" as the first line of the script.

*
If you use ";mode640,value500" as the first line of a script, then since ";mode640" is not a valid directive, the "value" setting will also be ignored. (by BBS)
Example:
Sets the starting global variable number to 500.
;value500
*define

mode800 / mode400 / mode320 /
page top / list / main

[Definition Block Only]( NScr, ONScr, ONScr-EN, PONS )
versionstr

Console

versionstr STR,STR

STRFirst line of version string
STRSecond line of version string

Designates version strings to display in the "about" dialog. The first string is the first line, the second string is the second line.


page top / list / main

[Program Block Only]( NScr1.98, ONScr, ONScr-EN, PONS )
voicevol

Music/SFX Playback

voicevol NUM

NUMSound volume (0-100)

Changes the sound volume for voices.

*
Volume changes are not saved, so manage them manually or with variables.
Example:
Sets voice volume to maximum (100)
voicevol 100

chvol / mp3vol / sevol / bgmvol /
page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
vsp

Image Display

vsp NUM,NUM

NUMSprite number (0 - 999)
NUMvisibility flag (0: not visible, 1: visible)

Toggles display of specified sprite. 0 is off, 1 is on.


page top / list / main

[Program Block Only]( NScr2.80, ONScr, ONScr-EN, PONS )
vsp2

Extended Sprites

vsp2 NUM,NUM

NUMExtended-sprite number
NUMvisibility flag (0: not visible, 1: visible)

Toggles display of specified extended sprite. 0 is off, 1 is on.


lsp2 / lsph2 / lsp2add / lsph2add / csp2 / msp2 / amsp2 /
page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
wait

Wait/Timer

wait NUM

NUMAmount of time to wait (msec)

Causes a delay of specified time (in milliseconds) that may not be escaped out of by clicking.
This works the same as the special text command '!w', but here you can supply a variable as the argument.


!w /
page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
waittimer

Wait/Timer

waittimer NUM

NUMTime-value to wait for on the internal timer (msec)

Waits until the internal timer has passed the specified time before proceeding.
This command is the single most accurate timing measure in all of NScripter.
The timing intervals of things like image effect runtimes are not nearly this accurate, so be careful when you mix and match timing methods.

*
It may be necessary to do wait 0 in cases where sprite animation stalls due a mismatch with the internal timer. (by BBS)

page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
wave

Music/SFX Playback

wave STR

STRWAV filename

Plays the specified WAV file.
wave plays it once, while waveloop loops it.


wavestop /
page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
waveloop

Music/SFX Playback

waveloop STR

STRWAV filename

Plays the specified WAV file.
wave plays it once, while waveloop loops it.


wavestop /
page top / list / main

[Program Block Only]( NScr, ONScr, ONScr-EN, PONS )
wavestop

Music/SFX Playback

wavestop

Stops WAV file playback.


page top / list / main

[Definition Block Only]( NScr, ONScr, ONScr-EN, PONS )
windowback

Image Display

windowback

Inserts the text window at the same level as standing pictures. Can be used for a 'positional subtitle' effect.

*
The text window is drawn on top of the standing image layer, which is drawn on top of the sprite at humanz level. Meanwhile, sprites with number less than the humanz value will appear on top of the text window. (by senzogawa)
*
In reality, NScr draws the sprite at humanz level above the text window, which is above the standing image layer.
ONScripter-EN draws the sprite with humanz number between the text window and standing image layers when windowback is in effect; this allows placement of a graphic covering the images but under the text. (by Mion)

humanz /
page top / list / main

[Definition Block Only]( NScr2.25, ONScr20080121, ONScr-EN20080310 )
windowchip

Text Window

windowchip NUM

NUMSprite number to show with the text window

Attaches the given sprite to the text window, so it displays and disappears when the window does.

Example:
Sets Sprite 2 to display with the text window.
windowchip 2

page top / list / main

[Definition/Program Block]( NScr, ONScr, ONScr-EN, PONS )
windoweffect

Text Window

windoweffect EFFECT

EFFECTEffect specification

Sets an effect to use when the text window is hidden or unhidden. The parameters are identical to effect, except that there's no effect number parameter here.

Example:
This sets the window effect to do cross-fade for 1 second.
windoweffect 10,1000

effect /
page top / list / main

[Program Block Only]( NScr )
winexec

External Command Execution

winexec STR,NUM

STRExecution file name
STRSynchronization flag (0: asynchronous, !=0: synchronous)

Executes the given external program using the WinExec API.
If NScr is in full-screen mode, the call to WinExec will use display option SW_MAXIMIZE, while in windowed mode, it will use SW_SHOWNORMAL.
For any sync-flag value other than 0, the external program will run synchronously with NScr.
The executed program will send WM_USER+10 to the NScripter window if it restarted, and WM_USER+20 if the program ended.
This command is used to launch a demo program in "Dolls Antique".


page top / list / main

Ver.2.47[Definition/Program Block]( NScr )
yesnobox

Miscellaneous

yesnobox %VAR,STR,STR

VARResult: 1 for Yes, 0 for No
STRMessage to display
STRDialog box title

Shows a Windows Yes/No dialog box and retrieves user input.

Example:
Creates Yes/No dialog titled "ロード確認" (Confirm Load) with the message "ロードしますか?" (Perform Load?).
yesnobox %0,"ロードしますか?","ロード確認"

okcancelbox /
page top / list / main

Ver.(undoc)[Definition Block Only]( NScr2.49, ONScr20050504, ONScr-EN, PONS )
zenkakko

Pretext Tags

zenkakko

Enables use of 【】 (fullwidth black lenticular brackets) for pretext tag specifications, in addition to the standard [] brackets.

*
This feature appears to be unsupported in the latest release (ver2.95), as NScr crashes when it reaches the 【】. Seems to work fine up through ver2.82. (by senzogawa)
Note that, although the brackets may be fullwidth, tag elements are still separated by standard / slashes.
Example:
Uses fullwidth brackets for pretext tag specification.
*define
pretextgosub *pretextproc
zenkakko
game
*start
【名前/音声】「せりふ」
click
end

*pretextproc
gettag $0,$1
mesbox $0,$1 ; 題名が"音声"、本文が"名前"のダイアログを表示
return

gettag / pretextgosub / [] /
page top / list / main