NOTE: This is a MIRROR of UncleMion's Nscripter Reference (as the website is no longer working). Please see this page for more information, and for a reformatted version of this page.

Game Start/End/Quit
*define label denoting the start of the definition block
*start label denoting the start of the program block
game end definition block and execute game
reset reset game
definereset force total script reset
end end 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
0x provide a numeric literal in hexadecimal format
^ enter ponscripter text mode
Text Window
setwindow set up text window and character display attributes
setwindow2 modify text window appearance
textoff hide text window
texton show text window
windoweffect specify an effect for the text window
erasetextwindow toggle text display during effect runtime
btnnowindowerase text window won't be removed while buttons are in effect
noteraseman people won't be erased when the text window is removed
gettext retrieve the contents of the text window
tateyoko toggle text display during effect runtime
windowchip show the specified sprite whenever the text window is displayed
setwindow3 same as setwindow , but doesn't clear Log buffer
textspeeddefault change to default text display speed
font change the text display font
Text Display
defaultfont specify default font
!s set the character display speed
# change character color
textclear clear displayed text
locate change the position of character output within the text window
puttext output a short bit of text (like after an if statement)
br insert a carriage return into the displayed text
textspeed change text display speed
shadedistance specify the text shadow offset
setkinsoku set forbidden start/end characters for Japanese
addkinsoku add forbidden start/end characters for Japanese
kinsoku toggle enforcement of forbidden Japanese start/end chars
english use NScripter English mode
textcolor change the color for text output
language set preferred text language
Click Wait
@ enter click wait state
\ enter new-page wait state
clickstr enter click wait state upon hitting any of the specified chars
linepage wait for click at the end of a line
_ ignore the following click
clickvoice play a specified sound when a click occurs
autoclick wait for click at the end of a line
click enter click wait state without displaying the click wait cursor
lrclick wait for either a left or right click
clickskippage skip to the new page clickwait upon click
Cursor
setcursor set graphic file and relative position for click wait cursor
abssetcursor set absolute position and graphic file for click wait cursor
mousecursor specify file for general mouse cursor
mousemode toggle mouse cursor display
movemousecursor move the mouse to a particular position on the screen
getnextline get the text window coordinates of the start of the following line
Image Display
transmode change alpha blend transparency mode
underline set ground line for standing images
bgalia set parameters for a nonstandard background
humanz designate overlap priority for sprites and standing images
windowback insert text window at the same overlap level as standing image(s)
bg set background image
ld set standing image
cl erase specified standing image
tal modify standing image opacity
print display images while removing those that should be hidden
lsp load sprite into memory
lsph load sprite into memory (hidden)
csp delete sprite from memory
vsp toggle display of a loaded sprite
spstr execute the given control string for complex-button sprite display
msp change sprite position (relative)
amsp change sprite position (absolute)
cell manually designate the cell of a sprite
blt blit image onto screen instantaneously
ofscpy transfer an image drawn by blt to the offscreen buffer
repaint redraw screen
allsphide hide all sprites at the same time
allspresume redisplay sprites hidden with allsphide
humanorder set priority levels for standing image positions
humanpos set coordinates for standing image positions
bgcopy copy current screen to the background
getspsize return the sprite's size
getspmode return whether the given sprite is displayed
spfont set the font used for string sprites
strsp create and display a sprite of a multi-line character string
strsph create a sprite of a multi-line character string, hidden
Visual Effects
effect designate an effect
effectblank designate wait duration after an effect is over
effectcut toggle effect runtime during "skip to next choice" mode
effectskip specify whether effects can be skipped
quake cause a shaking screen effect
quakex cause a horizontal shaking effect
quakey cause a vertical shaking effect
monocro make screen monochrome/color-toned
nega set negative screen display
flushout execute flushout effect
Character/Number/Bar Display
% display contents of numeric variable
$ display contents of string variable
? display contents of array variable
bar create and display a (graph) bar
barclear clear bar display
prnum initialize a numeric label
prnumclear clear numeric labels
Music/SFX Playback
cdfadeout specify duration of CD-DA fade-out
chkcdfile determine if CD drive contains a file called "filename"
chkcdfile_ex determine if CD drive contains a file called "filename"
mp3fadeout specify duration of BGM fade-out
play play specified CD-DA track or MIDI file in a loop
playonce play specified CD-DA track or MIDI file only once
playstop stop playback of CD track or MIDI file
wave play a WAV file only once
waveloop loop WAV file playback
wavestop stop WAV file playback
mp3 play compressed music file only once
mp3loop play compressed music file in a loop
mp3save if game saved during playback, resume playing upon reload
dsound declare that you are using DirectSound (unnecessary in latest versions)
dwave play WAV file using DirectSound only once
dwaveloop loop-play a WAV file using DirectSound
dwavestop stop DirectSound WAV file playback
dwaveload load WAV file into memory
dwaveplay play a preloaded WAV file only once
dwaveplayloop loop-play a preloaded WAV file
stop stop all music playback
mp3stop stop playback of compressed music
mp3fadein specify duration of BGM fade-in
bgm play compressed music file in a loop
bgmonce play compressed music file only once
bgmstop stop playback of compressed music
bgmfadeout specify duration of BGM fade-out
bgmfadein specify duration of BGM fade-in
loopbgm play intro, then loop repeatedly
loopbgmstop stop playback of loopbgm
mp3vol change BGM sound volume
chvol change sound volume of the given dwave channel
voicevol change voice sound volume
sevol change SFX sound volume
bgmvol change BGM sound volume
v voice playback, shorthand cmd ( wave )
dv voice playback, shorthand cmd ( dwave )
mv playback an mp3 voice file
bgmdownmode toggle turning down BGM volume when voices are played
Movie Playback
avi playback an AVI file
mpegplay playback an MPEG movie
movie play a movie
Choices
selectcolor designate the text colors for choices
selectvoice designate sound(s) to play during choice selection
select create a choice
selgosub create a choice that jumps to a subroutine
selnum create a choice that returns a number based on selection
Jumps
goto jump to designated label
skip skip the next n lines of script
gosub call a subroutine
return return from a subroutine
jumpf jump forward to the next ~ symbol
jumpb jump back to the previous ~ symbol
tablegoto jump to a label in the table based on the numeric value
Click Traps
trap jump to specified label on left click
r_trap jump to specified label on right click
lr_trap jump to specified label on left or right click
trap2 jump to label on left click when "skip to next choice" mode is set
lr_trap2 jump to label on left or right click when "skip to next choice" mode is set
Image Buttons
btndef load image file into button memory buffer
btn initialize image as button (method 1)
btnwait display image button and enter a click-wait state (method 1)
btnwait2 display image button and enter a click-wait state (method 2)
spbtn designate a sprite as an image button
cellcheckspbtn designate a sprite as a button only if the sprite has at least 2 cells
getbtntimer acquire how much time passed during btnwait
btntime set a time limit for image button functionality
btntime2 same as btntime , but waits for voice to finish
exbtn create a complex button
cellcheckexbtn create a complex button only if the sprite has at least 2 cells
exbtn_d specify default behavior for when complex buttons are used
transbtn ignore transparent areas when creating a button from an image
Wait/Timer
!d wait for the specified time
!w wait for the specified time, ignoring clicks
delay cause a time delay (method 1)
wait cause a time delay (method 2)
resettimer reset the internal timer
waittimer wait until the internal timer reaches the specified time value
gettimer get the value of the internal timer
spwait wait until the designated sprite's animation has ended
Variable Manipulation/Calculations
stralias create an alias for a filename or character string
numalias create an alias for a numeric value
intlimit set the allowed range for a numeric variable
dim declare an array variable
mov load a numeric/string variable with a value
mov3 load numeric values into 3 consecutive variables
mov4 load numeric values into 4 consecutive variables
mov5 load numeric values into 5 consecutive variables
mov6 load numeric values into 6 consecutive variables
mov7 load numeric values into 7 consecutive variables
mov8 load numeric values into 8 consecutive variables
mov9 load numeric values into 9 consecutive variables
mov10 load numeric values into 10 consecutive variables
movl load a line of numbers into an array
add add/concatenate to variable
+ do addition/concatenation
sub subtract a number from a variable
- do subtraction
inc increment a variable
dec decrement a variable
mul multiply variable by a number
* do multiplication
div divide variable by a number
/ do division
mod get the remainder (modulo)
rnd generate a random number (method 1)
rnd2 generate a random number (method 2)
itoa convert a numeric value into a string
itoa2 convert a numeric value into a fullwidth character string
atoi convert a string into a numeric
len find the length of a character string
mid get a substring of the given character string
split split a character string using the given delimiter
sin find the sine of the given angle
cos find the cosine of the given angle
tan find the tangent of the given angle
Conditionals/Loops
if evaluate if a condition is true
notif evaluate if a condition is false
cmp compare character strings
fchk check whether or not a image file has been loaded (and tagged)
lchk check whether or not a label has been accessed
for loop instruction
next end a loop
break break out of a for loop
Right-Click Functionality
rmenu initialize menu to display upon right-click
menusetwindow initialize window for right-click menu
savename specify names to use for savefiles in right-click menu
menuselectcolor designate the text colors for choices
menuselectvoice specify right-click menu system sounds
rlookback jump to Log Mode upon right-click
rgosub set a routine to call upon right-click
roff ignore right-clicks
rmode toggle availability of right-click menu
Log Mode
lookbackbutton specify button images for Log Mode
lookbackcolor designate text color for Log Mode
lookbackvoice play a sound when paging through Log Mode
lookbacksp use sprites instead of the default Log Mode buttons
maxkaisoupage set maximum number of pages to store for Log Mode
lookbackflush clear Log Mode buffer
lookbackoff stop accumulating Log Mode data
lookbackon begin accumulating Log Mode data
Skip Mode
kidokuskip enable 'stop at unread' in Skip Mode
mode_wave_demo play WAV files even during Skip Mode
skipoff turn off Skip Mode
kidokumode toggle Skip Mode's 'stop at unread' setting
File Access Logs/Global Variables
filelog enable file access logging
globalon enable use of global variables
labellog enable label access logging
Save/Load
savenumber set the maximum number of saves allowed
savedir store save data in the designated folder
loadgame load game from the designated savefile
savegame save game in the designated savefile
savegame2 store a particular character string along with the savefile
getsavestr retrieve the string stored with a savefile using savegame2
savefileexist check whether or not a savefile exists
saveon turn on Save Mode
saveoff turn off Save Mode
loadgosub set a routine to call immediately after loading a game
errorsave automatically save game status in savefile 999 when an error occurs
autosaveoff disable (most) automatic save points
savepoint update the save point
Miscellaneous
mesbox create a message box
okcancelbox create an OK/Cancel dialog box
yesnobox create a Yes/No dialog box
inputstr wait for player to give character input (method 1)
inputnum wait for player to give numeric input
input wait for player to give character input (method 2)
textfield create a text input window
clickpos retrieve the cursor coordinates at the last click
systemcall perform a function as though called from the right-click menu
fileexist check whether or not a file exists
fileremove delete a file
labelexist check whether or not a label exists
noloaderror don't generate an error when an image or sound can't be loaded
minimizewindow minimize the game window
Special Mode Settings
automode allow use of Auto Mode
automode_time specify delay time in Auto Mode when sounds aren't being played
defvoicevol set default volume for voices (dwave channel 0)
defsevol set default volume for SFX
defmp3vol set default volume for mp3 files (BGM channel)
defbgmvol set default volume for BGM channel
mode_saya use special mode created for "Saya ~Labyrinth of Immorality~"
mode_ext allow use of Auto Mode created for "Gin'iro"
mode800 set screen size to 800x600
mode400 set screen size to 400x300
mode320 set screen size to 320x240
value change the starting number for global variables
gameid give a name to use for an ONScr game save folder
Plugins/Archives
soundpressplgin load compressed audio functionality via plugin/dll (can just use DirectSound instead)
spi load compressed image functionality via plugin/dll
arc use specified archive
nsa enable NSA archive access
nsadir designate folder where NSA archives are located
addnsadir add a directory to check for NSA archives
exec_dll call a DLL
getret retrieve value returned from a DLL
setlayer create a layer
layermessage send a message to a layer
Console
versionstr change the version information
caption change the game window title
Data Acquisition
date retrieve the current year, month and date
time retrieve the current hour, minute and second
savetime retrieve the date and time of the given savefile
getversion get the version number of the current NScripter build
getwindowsize get the area of the window client
getreg read from the registry
getini read from an ini file
readfile read file contents into a string variable
Window Menubar
killmenu erase a menubar item
resetmenu clear menubar for definition of a custom menu
insertmenu add a menubar menu option
deletemenu remove the Windows menubar from NScripter
defaultspeed designate text display speeds selectable via the menubar
!sd use a text display speed provided via defaultspeed
menu_full enter fullscreen mode
menu_window enter windowed mode
isfull retrieve whether or not fullscreen mode is active
menu_click_page enter single-page text display mode
menu_click_def enter default text display mode
menu_dwavvol display the volume setting dialog window
menu_waveon enable main volume
menu_waveoff disable (mute) main volume
System Customization
*customsel a label that interacts with the csel command
csel give choices to present via system customization
cselbtn create custom buttons for choice text
cselgoto jump to a label created by csel
getcselnum get the total number of csel choices
getcselstr get the character string of a csel choice
nextcsel returns whether or not the next command is csel
selectbtnwait enter click wait state within a *customsel
textgosub define a label for handling system customization during click wait states
textbtnwait enter click wait state within a custom wait routine
getskipoff retrieve skipoff keystrokes at textbtnwait
getmouseover return on mouseover of buttons at a button wait
checkkey check for a specified keypress
texec remove text for a page-wait condition
texec2 remove text for a page-wait condition (method 2)
getcursorpos get current position of text cursor
getcursorpos2 get top-left pixel coordinates of the last text character
isskip get current progress mode
ispage retrieve whether or not in a new page clickwait
defsub create a user-defined command name
getparam retrieve the parameters given to a user-defined command
luacall replace default NScripter functionality with a Lua callback
luasub create a user-defined instruction that calls a Lua function
Screenshot
getscreenshot grab a screenshot
savescreenshot save a screenshot image
savescreenshot2 save a screenshot image
deletescreenshot remove a screenshot image from memory
Button Extensions
btnarea set an area for detecting mouse cursor entry
btndown set to return from button command while mouse button is pressed
isdown return whether or not the mouse button is pressed
getmousepos retrieve mouse cursor position
spclclk set the Spacebar to work the same as a left-click
usewheel have button commands detect mouse wheel movement
useescspc have button commands detect Esc and Spacebar keypresses
getcursor have button commands detect left/right/up/down arrow keys
getenter have button commands detect Enter key
gettab have button commands detect Tab key
getfunction have button commands detect Function keys
getpage have button commands detect PageUp/PageDown keys
getinsert have button commands detect Insert key
getzxc have button commands detect Z/X/C keys
getmclick detect middle-button mouse clicks
Ruby Text
() produce ruby text
rubyoff turn off ruby mode
rubyon enter ruby mode
rubyon2 enter this ruby mode only when ruby text appears
Demo Draw Commands
draw send images created via demo draw commands to the screen
drawclear paint the screen black
drawfill paint over the screen with a specific color
drawbg draw the background to the screen
drawbg2 draw the background to the screen in a special manner
drawtext draw the text window
drawsp draw a sprite
drawsp2 draw a sprite (scaled and rotated)
drawsp3 draw a sprite with linear transformation
Log Mode Customization
checkpage check whether a backlog page is available
getlog get the character string for a backlog page
logsp create a sprite from backlog text
logsp2 create a sprite from backlog text with custom text size
getlogtext get the character string for a backlog page (for use with strsp )
gettaglog get the last pretext tag of a backlog page
texthide hide text while leaving the text window visible
textshow reshow text hidden with texthide
Pretext Tags
pretextgosub set a routine to jump to just before text display
[] specify tag data available to a pretextgosub routine
gettag use within a pretextgosub routine to get tag data
indent when linebreaking, indent the next line by the given amount
pagetag only process pretext tags at the start of a page
zenkakko allow use of 【】 as pretext tag brackets
Development Support
bmpcut split a BMP file into multiple pieces while preserving the original
bw2a generate an NScripter alpha image
bw2a3 generate an NScripter alpha image
chainbmp glue image files together
createdummy create a dummy image file
debuglog log debug messages
External Command Execution
shell opens an external program, file, or URL via Explorer
winexec execute an external program
CSV File Manipulation
csvopen open a CSV file
csvread read data from an open CSV file
csvwrite write data to an open CSV file
csveof detect whether or not at the end of an open CSV file
csvclose close an open CSV file
Text Buttons
<> set a text button
linkcolor set textbutton colors
textbtnstart specify starting number for unnumbered textbuttons
gettextbtnstr retrieve the text of a particular textbutton
erasetextbtn clear a pressed textbutton
textexbtn create a complex textbutton (similar to exbtn )
textbtnoff inactivate textbuttons
Extended Sprites
lsp2 load an extended sprite into memory
lsph2 load an extended sprite into memory (hidden)
lsp2add load an extended sprite using additive composition
lsph2add load an extended sprite using additive composition (hidden)
lsp2sub load an extended sprite using subtractive composition
lsph2sub load an extended sprite using subtractive composition (hidden)
csp2 delete extended sprite from memory
vsp2 toggle display of a loaded extended sprite
msp2 change extended sprite position (relative)
amsp2 change extended sprite position (absolute)
allsp2hide hide all extended sprites at the same time
allsp2resume redisplay extended sprites hidden with allsp2hide
New Button Processing
bclear clear button definitions
bsp create a button from a sprite
bdef specify behavior for when no sprite button is moused over
btime specify button processing timeout duration
bexec execute button processing
bcursor return cursor key input during button processing
bdown return from button processing while button is pressed
btrans ignore transparent areas during button processing
PONScripter Commands
~ set a ponscripter formatting tag region
pmapfont map a font file to a ponscripter font slot
prendering configure ponscripter text rendering
pfontstyle set the default font style
pligate add or remove a ligature or shortcut sequence
pindentstr specify characters that cause indents
pbreakstr specify characters that allow linebreaks
localestring localize a right-click menu message string
h_mapfont map a font file to a ponscripter font slot
h_rendering configure ponscripter text rendering
h_fontstyle set the default font style
h_ligate add or remove a ligature or shortcut sequence
h_indentstr specify characters that cause indents
h_breakstr specify characters that allow linebreaks

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

Variable Manipulation/Calculations

NUM'-'NUM

NUM Numeric value to be subtracted from
NUM Numeric 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

NUM Amount 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

NUM Character 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

NUM Amount 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

NUM Variable 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

NUM String 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

NUM Variable 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

NUM Numeric variable number

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


$ /
page top / list / main

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

Ruby Text

'('STR'/'STR')'

STR Main text to show ruby text above
STR Ruby 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

NAME Label 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] ( NScr 2.10 , ONScr , ONScr-EN , PONS )
*

Variable Manipulation/Calculations

NUM'*'NUM

NUM Numeric value to multiply
NUM Numeric 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] ( NScr 2.10 , ONScr , ONScr-EN , PONS )
/

Variable Manipulation/Calculations

NUM'/'NUM

NUM Numeric value to divide
NUM Numeric 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

NUM Array 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] ( NScr 1.97 , ONScr , ONScr-EN , PONS )
?

Character/Number/Bar Display

?NUM

NUM Array 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']'

STR Tag 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] ( NScr 1.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] ( ONScr 20040909 , 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] ( NScr 2.65 , ONScr-EN )
{}

Syntax Markers

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

VAR A string or numeric variable
STR Provide a string value if VAR was a string variable
NUM Provide 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[...]'~'

FTAG A 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.)
c NUM select the font in slot NUM (0-7)
d select the default font style (same as c0 )
r disable italics (default)
i toggle italics
t disable bold (default)
b toggle bold
f select the 'text' face (default)
s select 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.)
= NUM set the current size to exactly NUM pixels (0 will reset to the base size)
% NUM set the current size to NUM-percent of the base size
+ NUM increase the current size by NUM pixels
- NUM decrease the current size by NUM pixels

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

Indentation:
n set the indent to the current horizontal position; new text lines will start from this offset until the end of the current page
u reset 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] ( NScr 2.10 , ONScr , ONScr-EN , PONS )
+

Variable Manipulation/Calculations

NUM'+'NUM

NUM Numeric value to add
NUM Numeric value to add

STR'+'STR

STR Character string to be augmented
STR Character 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'>'

NUM Textbutton number, must be nonnegative (optional)
STR Textbutton 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

HNUM Hexidecimal 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

NUM Cursor number (0: click-wait cursor, 1: page-wait cursor)
STR Cursor image filename
NUM Cursor position X-coordinate
NUM Cursor 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

VAR Numeric variable
NUM Numeric value to add

add $VAR,STR

VAR String variable
STR Character 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] ( NScr 2.70 , ONScr-EN )
addkinsoku

Text Display

addkinsoku STR,STR

STR String of characters forbidden at line start
STR String 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] ( NScr 2.20 , ONScr-EN )
addnsadir

Plugins/Archives

addnsadir STR

STR Directory to check for NSA archives

Adds a directory to check for NSA archives.


nsadir /
page top / list / main

[Program Block Only] ( NScr 2.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] ( NScr 2.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]

NUM Sprite number (0 - 999)
NUM X-coordinate
NUM Y-coordinate
NUM Opacity (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] ( NScr 2.80 , ONScr , ONScr-EN , PONS )
amsp2

Extended Sprites

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

NUM Extended-sprite number (0 - 255)
NUM Center X-coordinate
NUM Center Y-coordinate
NUM Scaling factor X (%)
NUM Scaling factor Y (%)
NUM Rotation angle (degrees, counterclockwise)
NUM Opacity 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

STR Plugin 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

VAR Numeric result variable
STR Character 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

NUM Click-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

NUM Wait 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

STR Movie filename
NUM Interrupt 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

NUM Bar number
NUM Bar current value
NUM Top-left X-coordinate
NUM Top-left Y-coordinate
NUM Bar width
NUM Bar height
NUM Bar maximum value
COLOR Bar 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

STR Default 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]

VAR Input result var
VAR Numeric 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

STR Image filename
EFFECT Effect for displaying background

bg COLOR,EFFECT

COLOR #rrggbb color for background
EFFECT Effect for displaying background

bg {black|white},EFFECT

ENUM Use basic black/white for background
EFFECT Effect 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

NUM Top-left X-coordinate
NUM Top-left Y-coordinate
NUM Background width
NUM Background 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] ( NScr 2.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] ( NScr 1.99 , ONScr , ONScr-EN , PONS )
bgm

Music/SFX Playback

bgm STR

STR Music 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] ( NScr 2.30 , ONScr-EN 20091230 )
bgmdownmode

Music/SFX Playback

bgmdownmode NUM

NUM 0: 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] ( NScr 2.24 , ONScr-EN )
bgmfadein

Music/SFX Playback

bgmfadein NUM

NUM BGM playback fade-in time (msec)

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


bgmfadeout /
page top / list / main

[Definition/Program Block] ( NScr 2.21 , ONScr-EN )
bgmfadeout

Music/SFX Playback

bgmfadeout NUM

NUM BGM playback fade-out time (msec)

Sets BGM fadeout time in milliseconds.


bgmfadein /
page top / list / main

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

Music/SFX Playback

bgmonce STR

STR Music 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] ( NScr 2.01 , ONScr , ONScr-EN , PONS )
bgmstop

Music/SFX Playback

bgmstop

Stops playback of compressed music.


page top / list / main

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

Music/SFX Playback

bgmvol NUM

NUM Sound 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

NUM Onscreen top-left X-coordinate
NUM Onscreen top-left Y-coordinate
NUM Onscreen width
NUM Onscreen height
NUM In-buffer top-left X-coordinate
NUM In-buffer top-left Y-coordinate
NUM In-buffer width
NUM In-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

STR Image filename
NUM Number of horizontal pieces (num. of horiz. cuts + 1)
NUM Number 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]

NUM Sprite number
STR Sprite control string for mouseoff
STR Sprite control string for mouseover
STR Sprite 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]

NUM Timeout duration (ms)
NUM Voice-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

NUM Button number
NUM Top-left X-coordinate
NUM Top-left Y-coordinate
NUM Button width
NUM Button height
NUM X-shift
NUM Y-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] ( NScr 1.97 , ONScr-EN 20091122 )
btnarea

Button Extensions

btnarea NUM

NUM Y-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

STR button 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] ( NScr 1.97 , ONScr , ONScr-EN , PONS )
btndown

Button Extensions

btndown NUM

NUM down-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

NUM Time 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] ( NScr 2.00 , ONScr , ONScr-EN , PONS )
btntime2

Image Buttons

btntime2 NUM

NUM Time 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

STR Numeric 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

VAR Numeric 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 bexec will 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

STR Resulting 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

STR Resulting 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

STR String to use for the window title

Sets the window title.


page top / list / main

[Definition Block Only] ( NScr )
cdfadeout

Music/SFX Playback

cdfadeout NUM

NUM CD 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

NUM Sprite number (0 - 999)
NUM Cell 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] ( NScr 2.49 , ONScr , ONScr-EN , PONS )
cellcheckexbtn

Image Buttons

exbtn NUM,NUM,STR

NUM Sprite number
NUM Button number
STR Sprite 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] ( NScr 1.99 , ONScr , ONScr-EN , PONS )
cellcheckspbtn

Image Buttons

cellcheckspbtn NUM,NUM

NUM Sprite number
NUM Button 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

STR Image 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] ( NScr 2.92 , ONScr-EN 20091230 )
checkkey

System Customization

checkkey %VAR,STR

VAR Numeric variable (1: got specified keypress, 0: didn't)
STR Key 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] ( NScr 2.49 , ONScr , ONScr-EN , PONS )
checkpage

Log Mode Customization

checkpage %VAR,NUM

VAR Result numeric variable
NUM Previous 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

STR File name to check for
STR Error 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

VAR Result numeric variable
STR File 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] ( NScr 2.00 , ONScr , ONScr-EN , PONS )
chvol

Music/SFX Playback

chvol NUM,NUM

NUM DWAVE channel number (0 - 49)
NUM Sound 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

ENUM standing pic position (l: left, c: center, r: right, a: all)
EFFECT Effect 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

VAR X-coordinate at last click
VAR Y-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] ( NScr 2.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

STR Clickwait characters
NUM Lines 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

STR Sound for click-wait
STR Sound 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

VAR Numeric variable for result of comparison
STR Character string #1
STR Character 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] ( NScr 2.25 , ONScr , ONScr-EN , PONS )
cos

Variable Manipulation/Calculations

cos %VAR,NUM

VAR Numeric result variable
NUM Angle (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

STR Dummy 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[,...]]

LABEL Choice string to display
LABEL Choice 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

NUM Choice index number (starting at 0)
LABEL Top-left X-coordinate
LABEL Top-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

NUM Choice 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

NUM Sprite 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] ( NScr 2.80 , ONScr , ONScr-EN , PONS )
csp2

Extended Sprites

csp2 NUM

NUM Extended-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

VAR numeric 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

STR CSV file name
STR file 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[,...]

VAR numeric 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[,...]

VAL numeric 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

VAR Numeric variable for the retrieved year
VAR Numeric variable for the retrieved month
VAR Numeric 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

NUM Debug 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

VAR Numeric variable to decrement

Decrements said variable by 1.


page top / list / main

[Definition Block Only] ( NScr )
defaultfont

Text Display

defaultfont STR

STR Font 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

NUM Slow default text display speed
NUM Medium default text display speed
NUM Fast 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] ( NScr 2.37 , ONScr-EN )
defbgmvol

Special Mode Settings

defbgmvol NUM

NUM Default 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] ( NScr 1.97 , ONScr , ONScr-EN , PONS )
defmp3vol

Special Mode Settings

defmp3vol NUM

NUM Default 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] ( NScr 1.97 , ONScr , ONScr-EN , PONS )
defsevol

Special Mode Settings

defsevol NUM

NUM Default 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] ( NScr 2.40 , ONScr , ONScr-EN , PONS )
defsub

System Customization

defsub NAME

NAME Subroutine 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] ( NScr 1.97 , ONScr , ONScr-EN , PONS )
defvoicevol

Special Mode Settings

defvoicevol NUM

NUM Default 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

NUM Amount 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] ( NScr 2.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] ( NScr 1.97 , ONScr , ONScr-EN , PONS )
dim

Variable Manipulation/Calculations

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

NUM Array number (0 - 199)
NUM Dimension 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

VAR Numeric variable
NUM Numeric value to divide by

Divides the variable by the number, truncating the remainder.


page top / list / main

[Program Block Only] ( NScr 2.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] ( NScr 2.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] ( NScr 2.31 , ONScr , ONScr-EN , PONS )
drawbg2

Demo Draw Commands

drawbg2 NUM,NUM,NUM,NUM,NUM

NUM Center X-coordinate
NUM Center Y-coordinate
NUM Width scaling factor (%)
NUM Height scaling factor (%)
NUM Rotation 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] ( NScr 2.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] ( NScr 2.31 , ONScr , ONScr-EN , PONS )
drawfill

Demo Draw Commands

drawfill NUM,NUM,NUM

NUM Red component of RGB color (0-255)
NUM Green component of RGB color (0-255)
NUM Blue 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] ( NScr 2.31 , ONScr , ONScr-EN , PONS )
drawsp

Demo Draw Commands

drawsp NUM,NUM,NUM,NUM,NUM

NUM Sprite number
NUM Cell number (of sprite)
NUM Opacity (0-255)
NUM Top-left X-coordinate
NUM Top-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] ( NScr 2.31 , ONScr , ONScr-EN , PONS )
drawsp2

Demo Draw Commands

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

NUM Sprite number
NUM Cell number (of sprite)
NUM Opacity (0-255)
NUM Center X-coordinate
NUM Center Y-coordinate
NUM Width scaling factor (%)
NUM Height scaling factor (%)
NUM Rotation 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] ( NScr 2.60 , ONScr , ONScr-EN , PONS )
drawsp3

Demo Draw Commands

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

NUM Sprite number
NUM Cell number (of sprite)
NUM Opacity (0-255)
NUM Top-left X-coordinate
NUM Top-left Y-coordinate
NUM Matrix top-left coefficient
NUM Matrix top-right coefficient
NUM Matrix bottom-left coefficient
NUM Matrix 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] ( NScr 2.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] ( NScr 1.97 , ONScr , ONScr-EN , PONS )
dv

Music/SFX Playback

'dv'NUM':'

NUM Voice 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

NUM Channel number (0 - 49)
STR WAV 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] ( NScr 1.97 , ONScr , ONScr-EN , PONS )
dwaveload

Music/SFX Playback

dwaveload NUM,STR

NUM Channel number (0 - 49)
STR WAV 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

NUM Channel number (0 - 49)
STR WAV 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] ( NScr 1.97 , ONScr , ONScr-EN , PONS )
dwaveplay

Music/SFX Playback

dwaveplay NUM

NUM Channel 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] ( NScr 1.97 , ONScr , ONScr-EN , PONS )
dwaveplayloop

Music/SFX Playback

dwaveplayloop NUM

NUM Channel 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

NUM Channel 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]]

NUM Effect number (2 - 255)
NUM Built-in effect number (1 - 18,)
NUM Duration (msec)
STR Mask 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

NUM Wait 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] ( NScr 1.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] ( NScr 2.92 , ONScr-EN )
effectskip

Visual Effects

effectskip NUM

NUM Effect 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] ( NScr 2.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] ( NScr 2.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

NUM Flag (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] ( NScr 1.97 , ONScr , ONScr-EN , PONS )
exbtn

Image Buttons

exbtn NUM,NUM,STR

NUM Sprite number
NUM Button number
STR Sprite 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] ( NScr 1.97 , ONScr , ONScr-EN , PONS )
exbtn_d

Image Buttons

exbtn_d STR

STR Sprite 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] ( NScr 2.03 , ONScr , ONScr-EN , PONS )
exec_dll

Plugins/Archives

exec_dll STR

STR DLL 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

STR Filename 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] ( NScr 2.01 , ONScr , ONScr-EN , PONS )
fileexist

Miscellaneous

fileexist %VAR,STR

VAR Result for file check (1: exists, 0: not found)
STR Filename

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

STR Filename

Deletes the given file.


fileexist /
page top / list / main

[Program Block Only] ( NScr 2.48 , ONScr-EN 20100102 )
flushout

Visual Effects

flushout NUM

NUM Duration (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

STR Font 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]

VAR Numeric variable used as counter
NUM Initial value for counter
NUM Ending value for counter
NUM Increment 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

STR Name 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

VAR Numeric 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

VAR Numeric 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] ( NScr 2.34 , ONScr , ONScr-EN , PONS )
getcselstr

System Customization

getcselstr $VAR,NUM

VAR String variable for choice
NUM Index 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] ( NScr 2.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

VAR Variable for the text-window X-coordinate of the text cursor
VAR Variable 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] ( NScr 2.92 , ONScr-EN 20100105 )
getcursorpos2

System Customization

getcursorpos2 %VAR,%VAR

VAR Variable for the top-left pixel X-coordinate of the text character
VAR Variable 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] ( NScr 2.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] ( NScr 2.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

VAR String variable for the registry key/value result
STR An INI filename
STR INI section name
STR INI key name

Opens an ini file and reads a variable.


page top / list / main

[Program Block Only] ( NScr 2.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] ( NScr 2.49 , ONScr , ONScr-EN , PONS )
getlog

Log Mode Customization

getlog $VAR,NUM

VAR Result variable for backlog string
NUM Number 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

VAR Result variable for backlog string
NUM Number 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] ( NScr 2.94 , ONScr-EN 20091122 )
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] ( NScr 2.49 , ONScr-EN 20091122 )
getmouseover

System Customization

getmouseover

NUM Minimum button number to return mouseovers
NUM Maximum 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] ( NScr 1.97 , ONScr , ONScr-EN , PONS )
getmousepos

Button Extensions

getmousepos %VAR,%VAR

VAR result numeric variable for mouse cursor X-coordinate
VAR result 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-EN 20100105 )
getnextline

Cursor

getnextline %VAR,%VAR

VAR Numeric variable for the text window X-coordinate of the following line
VAR Numeric 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] ( NScr 2.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] ( NScr 2.40 , ONScr , ONScr-EN , PONS )
getparam

System Customization

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

VAR Argument 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

VAR String variable for the registry key/value result
STR A registry key
STR A 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] ( NScr 2.03 , ONScr , ONScr-EN , PONS )
getret

Plugins/Archives

getret %VAR|$VAR

VAR Variable 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] ( NScr 2.60 , ONScr , ONScr-EN )
getsavestr

Save/Load

getsavestr $VAR,NUM

VAR Result string variable
NUM Savefile 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] ( NScr 2.25 , ONScr , ONScr-EN , PONS )
getscreenshot

Screenshot

getscreenshot NUM,NUM

NUM Screenshot image width
NUM Screenshot 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] ( NScr 2.49 , ONScr-EN 20091230 )
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] ( NScr 2.61 , ONScr , ONScr-EN , PONS )
getspmode

Image Display

getspmode %VAR,NUM

VAR Result numeric variable
NUM Sprite 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] ( NScr 2.53 , ONScr , ONScr-EN , PONS )
getspsize

Image Display

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

NUM Sprite number
VAR Result numeric variable for sprite width
VAR Result numeric variable for sprite height
VAR Optional 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] ( NScr 2.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] ( NScr 2.46 , ONScr , ONScr-EN , PONS )
gettag

Pretext Tags

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

VAR Numeric 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] ( NScr 2.72 , ONScr , ONScr-EN , PONS )
gettaglog

Log Mode Customization

gettaglog $VAR,NUM

VAR Result variable for backlog string
NUM Number 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] ( NScr 2.00 , ONScr , ONScr-EN , PONS )
gettext

Text Window

gettext VAR

VAR String 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] ( NScr 2.65 , ONScr-EN )
gettextbtnstr

Text Buttons

gettextbtnstr $VAR,NUM

VAR Result string variable
NUM Textbutton 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

VAR Current 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] ( NScr 1.97 , ONScr , ONScr-EN , PONS )
getversion

Data Acquisition

getversion %VAR

VAR Numeric 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

VAR Numeric variable for window width
VAR Numeric 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] ( NScr 2.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

LABEL Jump 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

LABEL Jump 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

STR Break characters

h_breakstr basic

ENUM Keyword 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

STR font 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

STR Indent characters

h_indentstr basic

ENUM Keyword 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

STR Shortcut matching text
NUM Unicode codepoint for shortcut result (if numeric)
STR (Unicode) char for shortcut result (if string)

h_ligate STR,remove

STR Shortcut matching text
ENUM Keyword to remove the defined matching shortcut

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

ENUM Keyword for a preset shortcut set

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


pligate /
page top / list / main

[Definition/Program Block] ( PONS 20061124 )
h_mapfont

PONScripter Commands

h_mapfont NUM,STR[,STR]

NUM Font slot (0-7)
STR Font filename
STR Font 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] ( PONS 20061124 )
h_rendering

PONScripter Commands

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

ENUM Hinting (either none, full, or light)
ENUM Positioning (either integer or float)
ENUM Optional 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] ( NScr 2.25 , ONScr , ONScr-EN , PONS )
humanorder

Image Display

humanorder STR,EFFECT

STR Standing image positions in priority order, e.g. "lcr"
EFFECT Transition 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] ( NScr 2.03 , ONScr-EN 20091010 )
humanpos

Image Display

humanpos NUM,NUM,NUM

NUM Standard X-coordinate for "l" standing image position
NUM Standard X-coordinate for "c" standing image position
NUM Standard 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

NUM Sprite 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

CONDITION Relative operation, check instruction, or some other truth-value returning expression
SENTENCE Command(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

VAR Numeric variable to increment

Increments the value of the numerical variable by one.


page top / list / main

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

Pretext Tags

indent NUM

NUM The 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

VAR Input result string variable
STR Message to display
STR Default input string
NUM Maximum input length
NUM Force 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]

VAR Input result numeric variable
STR Message to display
NUM Window width (optional)
NUM Window height (optional)
NUM Input area width (optional)
NUM Input 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]

VAR Input result string variable
STR Message to display
NUM Maximum input length
NUM Force double-byte input (0: allow half-width, 1: full-width only)
NUM Window width (optional)
NUM Window height (optional)
NUM Input area width (optional)
NUM Input 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]

STR Character string displayed for menu item
NAME Menu function code
NUM Submenu 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

NUM Numeric variable number
NUM Minimum allowed value
NUM Maximum 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] ( NScr 1.97 , ONScr , ONScr-EN , PONS )
isdown

Button Extensions

isdown %VAR

VAR result 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] ( NScr 2.03 , ONScr-EN )
isfull

Window Menubar

isfull %VAR

VAR Result 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] ( NScr 2.49 , ONScr , ONScr-EN , PONS )
ispage

System Customization

ispage %VAR

VAR Return 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] ( NScr 2.20 , ONScr , ONScr-EN , PONS )
isskip

System Customization

isskip %VAR

VAR Return 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

VAR String result variable
NUM Numeric 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] ( NScr 2.49 , ONScr , ONScr-EN , PONS )
itoa2

Variable Manipulation/Calculations

itoa $VAR,NUM

VAR String variable for the fullwidth result
NUM Numeric 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] ( NScr 1.97 , ONScr , ONScr-EN , PONS )
kidokumode

Skip Mode

kidokumode NUM

NUM Mode 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

NUM Position 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.