| Reserved Syntax | Keywords or labels with predefined functions |
| F Commands | Commands that may only be used in the definition block |
| E Commands | Commands that may only be used in the program block |
| F/E Commands | Commands that may be used in the program or the definition block |
| Special Text Commands | Special characters that may be used as command substitutes within displayed text blocks |
| NAME | Case-insensitive string of alphanumerics and/or '_'; must begin with an alphabet letter or '_' |
| LABEL | Character string consisting of '*' followed by a NAME |
| NUM | Numeric expression: string(s) of numeric digits possibly connected by any of the operators '+', '-', '*', '/' |
| STR | Character string enclosed by '"'s; (originally) intended for full-width Japanese chars |
| %VAR | Variable that may store numeric values |
| $VAR | Variable that may store character strings |
| COLOR | RGB value: '#' followed by 6 hexadecimal chars |
| EFFECT | Built-in effect number w/duration, or number defined by an earlier "effect" command |
| ENUM | Argument must be one of the comma-separated values within the {}s |
| CONDITION | Expression that returns a true/false value |
| SENTENCE | A single command, or multiple commands separated by ':' |
| '' | Surrounds a string literal |
| [] | Surrounds optional argument(s) |
| ... | Follows an argument pattern that may be repeated |
| Variable Number | 0 - 4095 | If 4096 is used, the initial value is undefined. |
| Array Number | 0 - | Unbounded? This could cause memory issues. |
| Sprite Number | 0 - 999 | Use of 1000 will cause an error. |
| Enhanced Sprite Number | 0 - 255 | Use of 512 will cause an error. |
| Effect Number | 2 - 255 | Use of 256 will cause an error. |
| Button Number | 1 - | Unbounded? This could cause memory issues. |
| Channel Number | 0 - 49 | NScr ver2.82+ allows (0-199) |
| NScripter (WayBack Machine Link) | A game scripting engine |
| ONScripter (WayBack Machine Link) | An open-source NScripter emulator |
| ONScripter-EN (WayBack Machine Link) | English branch of ONScripter |
| PONScripter (WayBack Machine Link) | Proportional ONScripter: supports Unicode and proportional fonts |
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.
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.
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.
Sets text display to the current default speed. You may set the three possible default speeds with the defaultspeed command.
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.
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.
Works much as for numeric
variables -- like the general vs. global designation -- except for
character strings.
The default value for character variables is "".
Tag for character string variables. Use this to access their contents within text.
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.
Tag for numeric variables. Use this to access their contents within text.
This text command produces ruby text, often used for furigana (Japanese phonetic characters that show the pronunciation of a kanji phrase).
*define rubyon game *start setwindow 10,10,20,20,24,24,0,12,0,1,1,#ffffff,0,0,639,479 ルビ機能の(暫定仕様/ざんていしよう)です。@ ｒｕｂｙｏｎ時、(文字/もじ)は(下詰/したづめ)で表示されます。@ (縦/たて)の(字間/じかん)を、ルビが入る分とって下さい。@ 「(承/うけたまわ)」る、とか、「(論理的/ロジカル)」みたいに、文字幅をあわせようとする機能がついてます。 ルビは折り返し改行されませんのでご注意ください。\ end
*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
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)
*asterisk
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.
Jumps to this label whenever
a
csel
command is executed.
Code for handling a custom select display follows this label.
*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
A special label that denotes the start of the definition block.
*define game
This label denotes the start of the program block proper.
*start end
If you write a newline directly after this slash, then the newline will be ignored.
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.
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 ...
btnwait %0 if %0=-1 allsphide:systemcall lookback
A command that starts with ';' is a comment - Nscr will skip these.
defsub abs ; This is just a comment.
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.
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 .
*define dim ?0[10][20] start ;populate ?0[2][5] with value 20. mov ?0[2][5],20 ;used in text ＶＡＬ＝?0[2][3]@
`Array value = `?0[2][5]`.@
Specifies tag data accessible to gettag within a pretextgosub routine, called immediately before the following text is displayed.
[太郎/0001.wav]「太郎の台詞」
[`Taro Mendo`/0001.wav]`Taro speaking.`
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.
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").
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.
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")
*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
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.
mov %2,4 : mov $3,"いない"
;the following text sets values
ここでは %2 $3 、@このように{%2,15,$3,テキスト}。@
ここでは %2 $3。\
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.\
Tags
that are targets for jumpf and jumpb.
Please do not place any display text between a jumpf/jumpb command and a
~.
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
.
puttext ^~c1~Hello there^
^Bruce: ~n~What's that you say?@ ^You don't understand indenting?~u~@ br ^Rick shuffled his feet.\
^~i %120 x-20 y-40~Heading~i =0~
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.
mov ?0[0],?0[0]+1
mov $1,"●" mov $2,"あいうえお"+$1+"さしすせそ" ;Now $2 contains "あいうえお●さしすせそ".
mov $0,`Text` mov $0,$0+` String` ;Now $0 contains "Text String".
A character string enclosed by '<' and '>' is converted into a text button.
`This is a `<3`textbutton`>`.@
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.
numalias ascii_slash,0x2F
This works the same as setcursor , but uses absolute onscreen coordinates, not text-relative coordinates.
Add a number to a numeric variable. If used with strings, performs string concatenation instead.
add %0,6
add $5,"ああああ"
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.
Hides all extended sprites at the same time. (Works essentially the same as allsphide .)
Redisplays the extended sprites that were hidden by allsp2hide . (Works essentially the same as allspresume .)
Similar to msp , but moves the sprite to an absolute instead of relative position.
amsp 2,5,2,100
Similar to msp2 , but this command changes the given extended sprite's position, scale, rotation, and opacity to absolute values instead of relatively.
amsp2 0,10,20,10,10,5
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.
arc "arc.sar|scrunarc.dll"
getreg $0,"software\leaf\toheart","datadir" add $0,"\lvns3dat.pak|axlfpak.spi" arc $0
Converts a character string into a numeric variable. This works the same way as the corresponding command in C.
atoi %0,"123" atoi %3,$0
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.
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.
When in Auto Mode (as defined by mode_ext), and when text display is not instantaneous, this sets the delay at clickwaits in milliseconds.
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.
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.
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.
Clears
out bars.
You can think of the bars as being like life bars in fighting games,
kind of.
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
.
Specifies behavior for when no sprite buttons are being moused over. Uses the same control string format as exbtn and spstr .
bdef "C0"
If bdown is executed after bclear and before bexec , bexec will return on a left-click even before the mouse button press is released.
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.
bexec $0,%0
Loads the background image, using the given effect and final image/color.
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).
The
same as
bgcpy
; the current screen gets copied to the background
screen.
The text window, etc. can be displayed on top of this.
Plays the given compressed music file in a loop. Equivalent to the mp3loop command.
bgm "bgm01.mp3"
Sets whether the BGM volume should be lowered while a voice sound is playing.
bgmdownmode 1
Plays the given compressed music file one time through. Equivalent to the mp3 command.
bgm "bgm01.mid"
Changes the volume of the BGM. This applies to both bgm and mp3 commands.
bgmvol 100
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).
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.
bmpcut "test.bmp",3,2
Inserts
a linefeed into the text window.
Use this when you want a blank line or something similar.
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.
*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
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.
bsp 1
bsp 2,"P3,0","P3,1","P4,1"
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.
btime 2000
btime 1000,1
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.
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.
btndef clear btnarea -400
Sets up an image button. The previously-defined
button is cleared.
For an example, see the "btndemo" folder in the NScr SDK.
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).
btndown 1
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.
This is the same as btntime , except that the timeout will wait for voices to finish.
btntime2 1000
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.
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
)
Executing btrans after bclear and before bexec will cause button processing to treat transparent areas of sprite buttons as outside the respective buttons.
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.
bw2a "test"
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.
bw2a3 "test.bmp"
Designate the fade-out time of CD-DA audio, in milliseconds.
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.
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.
cellcheckexbtn 1,100,"P1,1P2"
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.)
for %0=0 to 9
cellcheckspbtn %0,%0+1
next
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.
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
btnwait %0 checkkey %1," " checkkey %2,"ENTER"
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.
checkpage %5,1
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".
chkcdfile "file.dat","CDがありません"
This checks for the given file on the CD drive.
It sets the result to 1 if it finds the file, 0 otherwise.
chkcdfile_ex %0,"file.dat"
Changes the volume of the given DWAVE channel.
chvol 3,100
Clear a standing image from the current picture.
If you specify 'a', then that will clear all of them.
Returns the position of the last click - the first variable is x, the second variable is y.
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).
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.
clickstr "」。！？",2
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.
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.
Acquires the trigonometric cosine of the given angle, and returns the value multiplied by 1000.
cos %1,60 ;%1=500, since cos(60)=0.5
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.
createdummy "test.bmp"
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 .
csel "Choice１",*s1,"Choice２",*s2,"Choice３",*s3
Creates a button from the text of the given choice number - no need to specify the string or sprite number.
cselbtn 0,500,%1,%2
Jumps to the label of the given choice index set by csel .
cselgoto %0
Erases the given extended sprite.
If the given value is -1, it erases all extended sprites.
Closes an open CSV file. Please use this command when finished with the file; otherwise it will remain open.
(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.
csveof %1
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.
csvopen "test.csv","r"
csvopen "angou.csv","wc"
(For use in read mode only)
Reads data items from a CSV file, in the specified order.
csvread $0,$1,%0,%2
(For use in write mode only)
Writes data items to a CSV file, in the specified order.
csvwrite 12,"test",%1,$2
If enabled, saves the message displayed in the debug window to "debuglog.txt".
Defines a default font.
NScripter defaults to MS Gothic if this command is not used.
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.
defaultspeed 50,20,0
This is a special reset command that forces reinterpretation of the script starting at *define .
Sets the default volume for mp3s (BGM), from a range of 0-100. Is 100 by default.
Sets default volume for sound effects (DWAVE 1+). Ranges from 0 to 100. Is 100 by default.
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 "_".
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
*define defsub *texton game *start texton ; does "gosub *texton" _texton ; calls the original "texton" command
Sets default volume for voices (DWAVE 0). Ranges from 0 to 100. Default value is 100.
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.
Completely removes the Windows menubar from NScripter.
Removes
a screenshot image from memory.
This command is meant to be used with
savescreenshot2
.
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.
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]. ＶＡＬ＝?0[2][3]@ ;used in text
numalias enemyparam,10 dim ?enemyparam[10]
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.
*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
Draws
the background image to the screen.
Must be followed by the
draw
command.
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.
drawbg2 320,240,200,300,15
Paints
over the entire screen with the color black.
Must be followed by the
draw
command.
Paints over the entire screen with the given color,
as provided with separate R,G,B levels.
Must be followed by the
draw
command.
drawfill 255,0,128
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.
drawsp 2,1,128,20,40
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.
drawsp2 2,1,128,20,40,150,60,-10
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.
drawsp3 2,1,128,20,40,1500,300,800,1200
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.
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.
This is a shorthand command
for playing voice files.
It is equivalent to
dwave 0,"voice\(num).wav"
.
dv0001:「これが０００１番のせりふだよー」
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.
dwave 0,"test.wav"
Loads a WAV file into memory for use with the commands dwaveplay and dwaveplayloop .
dwaveload 0,"test.wav" dwaveplay 0
The same as dwave , but in this case it loops the WAV file.
Plays the file loaded by dwaveload .
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.
effect 2,4,1000
effect 3,15,2000,"m3.bmp"
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.
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.
effectskip 1
Enables
NScripter English mode. Only half-width alphabetical sentences will be
displayed correctly.
Please begin text with the ">" character when using this mode.
*define english game *start >Peter Piper picked a peck of pickled peppers;@ end
After exiting a button wait, if a textbutton was pressed, then this command will set the textbutton back to its original color.
If 0, the text window stays during effect runtime.
If 1 (this is the default), the text window is hidden during effect
runtime.
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.
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.
spstr "C10"
spstr "C11P10"
spstr "C11P10,2P9"
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.
exbtn_d "P3C4C5C6P7,0"
Calls the given DLL with the specified parameters.
exec_dll "execdll.dll/テストですよー。"
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.
ld c,":a;test.bmp",1 if fchk ":a;test.bmp" ;returns true if fchk "test.bmp" ;same result
Assigns 1 to the given variable if the file exists, 0 if not. This will also check within NSA archives.
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.
Special effect; may be
graphic-intensive.
Ends with a white background, so please load a background in one of the
next instructions.
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.
font "ＭＳ 明朝"
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.
for %0=1 to 10 add %1,%0 next
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.
;gameid ToHeart-Extra
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).
Retrieves the total number of csel choices.
getcselnum %0
Acquires a character string given as a csel choice.
getcselstr $0,0
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.
Retrieves the text-window position of the text cursor - where a character would next be displayed.
getcursorpos %0,%1
The same as getcursorpos , except that this command returns the pixel coordinates of the top-left of the last displayed text character.
getcursorpos2 %0,%1
Use
this between
btndef
and
btnwait
commands.
The wait command will return -19 when the Enter key is pressed.
Use
this between
btndef
and
btnwait
commands.
The wait command will return -21 to -32 for presses of keys F1 to F12.
Use
this between
btndef
and
btnwait
commands.
The wait command will return -50 when the Insert key is pressed.
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
.
getlog $0,%5
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.
Use
this between
btndef
and
btnwait
commands, like with
getfunction
.
The wait command will return -70 if the middle mouse button is clicked.
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.
btndef clear getmouseover 0,9 btnwait %0
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.
getmousepos %0,%1
Retrieves the position of the start of the following line of text in the text window.
getnextline %0,%1
Use
this between
btndef
and
btnwait
commands.
The wait command will return -12 on PageUp keypress and -13 on PageDown.
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
Opens the Windows registry and queries for a
variable.
Will search only in HKEY_CURRENT_USER.
getreg $0,"software\leaf\toheart","datadir"
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
.
Retrieves the character string that was stored with a particular save number using savegame2 .
getsavestr $1,12
Collects a screenshot. This only stores the image in memory - you will need to call savescreenshot to save it to a file.
getscreenshot 160,120
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.
btndef clear getskipoff textbtnwait %0 if %0=-60 gosub *clearskipicon
This returns 1 if the given sprite is displayed, 0 if the sprite is hidden.
getspmode %2,10
Retrieves the size of the
given sprite.
This will also return the sprite cell number if the optional variable is
provided.
getspsize 0,%0,%1,%2
Use
this between
btndef
and
btnwait
commands.
The wait command will return -20 when the Tab key is pressed.
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.
gettag $0,$1
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.
Retrieves the text currently displayed in the text window.
gettext $0
Retrieves the text of the textbutton with the given
number.
Returns a value of "" if the textbutton doesn't exist.
gettextbtnstr $0,12
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.
Gets the current version string, as a 3-digit number: for instance. version 1.90 would be returned as 190.
Retrieves the size of the program window (the drawing area, not including the menubar). By default, the return values are 640 and 480.
getwindowsize %0,%1
Use
this between
btndef
and
btnwait
commands.
The wait command will return -51 on Z keypress, -52 on X, and -53 on C.
Turns on the use of global variables. If you enable this or filelog , nscr.exe cannot be run from write-protected media.
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.
Specifies characters that allow linebreaks. Equivalent to the pbreakstr command.
h_breakstr ^ ,-^
Sets the default text styling. Equivalent to the command pfontstyle .
h_fontstyle ^si^ ^Here is a page of italic text.\ ^And it's still italic!\ h_fontstyle ^d^ ;back to regular style
Specifies characters that will set an indent. Equivalent to the pindentstr command.
h_indentstr ^"'‘“^
Adds or removes shortcut sequences. Equivalent to the command pligate .
Maps a font file to the given font slot. Equivalent to the command pmapfont .
h_mapfont 0,"myprettyfont.ttf"
Configures the Freetype text rendering mode. Equivalent to the command prendering .
Specifies the overlapping priority for standing images.
humanorder "rcl",1
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.
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.
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.
if %0=1 quakex 2,500 ;basic conditional form
if %0=1 && %2=5 end ;more complex form - both conditionals must be true
if %0=2 mov %1,1:skip 2 ;execute multiple commands sep. by ':'
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.
indent 2
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.