20100615 A game scripting engine An open-source NScripter emulator English branch of ONScripter Proportional ONScripter: supports Unicode and proportional fonts Keywords or labels with predefined functions Commands that may only be used in the definition block Commands that may only be used in the program block Commands that may be used in the program or the definition block Special characters that may be used as command substitutes within displayed text blocks Case-insensitive string of alphanumerics and/or '_'; must begin with an alphabet letter or '_' Character string consisting of '*' followed by a NAME Numeric expression: string(s) of numeric digits possibly connected by any of the operators '+', '-', '*', '/' Character string enclosed by '"'s; (originally) intended for full-width Japanese chars Variable that may store numeric values Variable that may store character strings RGB value: '#' followed by 6 hexadecimal chars Built-in effect number w/duration, or number defined by an earlier "effect" command Argument must be one of the comma-separated values within the {}s Expression that returns a true/false value A single command, or multiple commands separated by ':' Surrounds a string literal Surrounds optional argument(s) Follows an argument pattern that may be repeated If 4096 is used, the initial value is undefined. Unbounded? This could cause memory issues. Use of 1000 will cause an error. Use of 512 will cause an error. Use of 256 will cause an error. Unbounded? This could cause memory issues. NScr ver2.82+ allows (0-199) Game Start/End/Quit Syntax Markers Text Window Text Display Click Wait Cursor Image Display Visual Effects Character/Number/Bar Display Music/SFX Playback Movie Playback Choices Jumps Click Traps Image Buttons Wait/Timer Variable Manipulation/Calculations Conditionals/Loops Right-Click Functionality Log Mode Skip Mode File Access Logs/Global Variables Save/Load Miscellaneous Special Mode Settings Plugins/Archives Console Data Acquisition Window Menubar System Customization Screenshot Button Extensions Ruby Text Demo Draw Commands Log Mode Customization Pretext Tags Development Support External Command Execution CSV File Manipulation Text Buttons Extended Sprites New Button Processing PONScripter Commands NOEP label denoting the start of the definition block *define A special label that denotes the start of the definition block. A definition block that does nothing *define game NOEP label denoting the start of the program block *start This label denotes the start of the program block proper. A program block that does nothing *start end NOEP end definition block and execute game game Ends the definition block and begins the game. NOEP reset game reset Resets the game and returns to the start of the program block. NOEP force total script reset definereset This is a special reset command that forces reinterpretation of the script starting at *define. NOEP end game and close window end End the program and close the window. NOEP prefix for labels '*'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) *asterisk NOEP prefix for comments ; A command that starts with ';' is a comment - Nscr will skip these. defsub abs ; This is just a comment. NOEP write and execute multiple commands on a line 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 ... On a right-click, hide sprites and then enter Log Mode btnwait %0 if %0=-1 allsphide:systemcall lookback NOEP prefix for numeric variables '%'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) NOEP prefix for character variables '$'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) NOEP prefix for array variables '?'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. NOEP destination point for jumpf/jumpb ~ Tags that are targets for jumpf and jumpb.
Please do not place any display text between a jumpf/jumpb command and a ~. NOEP ignore linefeed / If you write a newline directly after this slash, then the newline will be ignored. NE set variables within a text block '{'$VAR|%VAR,STR|NUM[,...]'}' A string or numeric variable Provide a string value if VAR was a string variable 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) 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。\ 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.\ NOEP set up text window and character display attributes setwindow NUM,NUM,NUM,NUM,NUM,NUM,NUM,NUM,NUM,NUM,NUM,COLOR,NUM,NUM,NUM,NUM X-coordinate of top left for text Y-coordinate of top left for text Number of (full-width) text columns Number of text lines (Full-width) text font size X Text font size Y Text spacing X Text spacing Y Default text speed Boldface toggle (0=off/1=on) Drop shadow toggle (0=off/1=on) Window color Window top left X-coordinate Window top left Y-coordinate Window bottom right X-coordinate Window bottom right Y-coordinate setwindow NUM,NUM,NUM,NUM,NUM,NUM,NUM,NUM,NUM,NUM,NUM,STR,NUM,NUM X-coordinate of top left for text Y-coordinate of top left for text Number of (full-width) text columns Number of text lines (Full-width) text font size X Text font size Y Text spacing X Text spacing Y Default text speed Boldface toggle (0=off/1=on) Drop shadow toggle (0=off/1=on) Image file name Window top left X-coordinate Window top left Y-coordinate Sets up the text window.
The first form is used when the backdrop for the text window is an alpha-layered solid color.
The second form is used when the backdrop for the text window is a graphic file.

By default, the text window takes up the full screen and is somewhat translucent, the font is 26x26 pixels, the spacing is 0,2, the top left coordinate is 8,16, there are 23 2-byte columns and 16 lines, boldface and drop shadow enabled, 20 speed, and a translucent color of #999999. Text window with default settings setwindow 8,16,20,23,26,26,0,2,20,1,1,#999999,0,0,639,479 Text window with default settings, but using image file "bgi.bmp" as backdrop setwindow 8,16,20,23,26,26,0,2,20,1,1,"bg1.bmp",0,0 NOEP modify text window appearance setwindow2 COLOR Window color setwindow2 STR Image file name This modifies the appearance of the text window without deleting either it or the text backlog.
This command can only modify the color or image file that was first specified in setwindow, and none of the other parameters. This modifies the text window to use image file "twindow2.bmp" as backdrop. setwindow2 ":c;twindow2.bmp" NOEP hide text window textoff Hide the text window. NOEP show text window texton Unhide/show the text window. NOEP specify an effect for the text window windoweffect EFFECT Effect specification Sets an effect to use when the text window is hidden or unhidden. The parameters are identical to effect, except that there's no effect number parameter here. This sets the window effect to do cross-fade for 1 second. windoweffect 10,1000 NOEP toggle text display during effect runtime erasetextwindow 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. N text window won't be removed while buttons are in effect btnnowindowerase The text window won't be erased when buttons are active. N people won't be erased when the text window is removed noteraseman Standing images will not be erased when the text window is removed. Does this actually do anything? (by Mion) NOEP retrieve the contents of the text window gettext VAR String variable to hold text window contents Retrieves the text currently displayed in the text window. Retrieves the contents of the text window and stores in $0. gettext $0 NOE toggle text display during effect runtime tateyoko NUM Flag (1: vertical text mode, 0: horizontal text mode) Toggles vertical text display mode. See sample for details. Sets vertical text display mode tateyoko 1 NOE> show the specified sprite whenever the text window is displayed windowchip NUM Sprite number to show with the text window Attaches the given sprite to the text window, so it displays and disappears when the window does. Sets Sprite 2 to display with the text window. windowchip 2 NOEP same as setwindow, but doesn't clear Log buffer setwindow3 NUM,NUM,NUM,NUM,NUM,NUM,NUM,NUM,NUM,NUM,NUM,COLOR,NUM,NUM,NUM,NUM X-coordinate of top left for text Y-coordinate of top left for text Number of (full-width) text columns Number of text lines (Full-width) text font size X Text font size Y Text spacing X Text spacing Y Default text speed Boldface toggle (0=off/1=on) Drop shadow toggle (0=off/1=on) Window color Window top left X-coordinate Window top left Y-coordinate Window bottom right X-coordinate Window bottom right Y-coordinate setwindow3 NUM,NUM,NUM,NUM,NUM,NUM,NUM,NUM,NUM,NUM,NUM,STR,NUM,NUM X-coordinate of top left for text Y-coordinate of top left for text Number of (full-width) text columns Number of text lines (Full-width) text font size X Text font size Y Text spacing X Text spacing Y Default text speed Boldface toggle (0=off/1=on) Drop shadow toggle (0=off/1=on) Image file name Window top left X-coordinate Window top left Y-coordinate This behaves the same as setwindow but without clearing the Log mode buffer. Entering Log Mode may be buggy if the text window isn't set to the same width and height. Sets text window with default settings without clearing log setwindow3 8,16,20,23,26,26,0,2,20,1,1,#999999,0,0,639,479 Sets text window with default settings, but using image file "bgi.bmp" as backdrop, without clearing log setwindow3 8,16,20,23,26,26,0,2,20,1,1,"bg1.bmp",0,0 NE change to default text display speed textspeeddefault Sets text display speed to the default.
Same as !sd, this command is especially meant for use in english mode. N change the text display font font 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. Changes display text font to "ＭＳ 明朝" font "ＭＳ 明朝" N specify default font defaultfont 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) NOEP set the character display speed !sNUM 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. NOEP change character color #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. NOEP clear displayed text textclear Remove the contents of the text window, but not the window itself. NOEP change the position of character output within the text window locate NUM,NUM Horizontal position (in full-width chars) Vertical position (in chars) Changes the (absolute) position of text insertion within the text window.
Note that the position values are in text metrics, not pixels. NOEP output a short bit of text (like after an if statement) puttext STR Character string to display Displays the given character string onscreen. This command is most often used within if statements to display some short indicator; otherwise its efficacy is limited.
When using puttext, you may not use any of the variable designation/value functions (e.g. % or $) with it. NOEP insert a carriage return into the displayed text br Inserts a linefeed into the text window.
Use this when you want a blank line or something similar. NOEP change text display speed textspeed NUM Character display speed (msec) Changes the text display speed.
This has the same functionality as !s, except that you can specify a variable here. NOEP specify the text shadow offset shadedistance NUM,NUM Shadow offset width (pixels) Shadow offset height (pixels) Sets the text shadow position. NScr Ver.2.62 added this command to the program block as well.
The shadow position will not return to the default setting even at reset. (by senzogawa) Sets the text shadow offset to 2 pixels right and 3 pixels down shadedistance 2,3 NE set forbidden start/end characters for Japanese addkinsoku STR,STR String of characters forbidden at line start String of characters forbidden at line end Much as English has linebreak rules, Japanese defines certain characters as "kinsoku" - forbidden from either starting or ending a line of text (e.g. end/start quotes, parentheses, and other punctuation).

This command specifies which (fullwidth) text characters will be treated as "kinsoku" for the purposes of text display: the first string contains characters forbidden at the start of a line, while the second string contains characters to be forbidden at the end of a line.

The default kinsoku characters for NScripter are "」』）］｝、。，．・？！ヽヾゝゞ々ー" (start) and "「『（［｛" (end). NE add forbidden start/end characters for Japanese addkinsoku STR,STR String of characters forbidden at line start 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. NE toggle enforcement of forbidden Japanese start/end chars kinsoku {on,off} on: use kinsoku rules; off: ignore kinsoku rules kinsoku on causes "kinsoku" (forbidden start/end character) rules to be enforced, while kinsoku off causes those rules to be ignored. This works with both regular text display and the strsp command. (by senzogawa) N use NScripter English mode 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) Displays the text "Peter Piper picked a peck of pickled peppers;" *define english game *start >Peter Piper picked a peck of pickled peppers;@ end N change the color for text output textcolor COLOR Color to use for text Changes the color of the text, using HTML hexadecimal color codes (e.g. #000000 for black, #ffffff for white, and #ffffaa for pale yellow).
Please note that it only changes the color of text displayed after this command, and not any of the text that came before. This seems to have been added in the 2007/11/04 release. You must use this command to change text color if english mode is enabled. (by senzogawa) Displays the text "blue font" in blue. *define english game *start textcolor #0000ff >blue font@ end NOEP enter click wait state @ Enters click wait state. NOEP enter new-page wait state \ 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. NOEP enter click wait state upon hitting any of the specified chars clickstr STR,NUM Clickwait characters 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. Cause a clickwait at characters '」', '。', '！', '？' clickstr "」。！？",2 NOEP wait for click at the end of a line linepage Setting this causes new-page clickwaits to occur at the end of each line, even if you do not specify it using '\'.
This means that you never have to manually specify a line/page feed.
Please take care if you decide to use @, \, or clickstr along with this command. NOEP ignore the following click _ 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) NOEP play a specified sound when a click occurs clickvoice STR,STR Sound for click-wait 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. NOEP wait for click at the end of a line autoclick 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. NOEP enter click wait state without displaying the click wait cursor click Wait for a click. NOE wait for either a left or right click lrclick Waits for either a left or right click.
The type of click of occurred can be retrieved using getret:
getret %0
This will return 0 for a right-click and 1 for a left-click. NE skip to the new page clickwait upon click 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). NOEP set graphic file and relative position for click wait cursor setcursor NUM,STR,NUM,NUM Cursor number (0: click-wait cursor, 1: page-wait cursor) Cursor image filename Cursor horizontal displacement (right) Cursor vertical displacement (down) Loads and displays a cursor definition file for use during click wait states.
The numbers comprise an (x,y) coordinate positioned relative to the upper left pixel of the next text display character.

The default settings are:
setcursor 0,":l/3,160,2;cursor0.bmp",0,0
setcursor 1,":l/3,160,2;cursor1.bmp",0,0 NOEP set absolute position and graphic file for click wait cursor abssetcursor NUM,STR,NUM,NUM Cursor number (0: click-wait cursor, 1: page-wait cursor) Cursor image filename Cursor position X-coordinate Cursor position Y-coordinate This works the same as setcursor, but uses absolute onscreen coordinates, not text-relative coordinates. N specify file for general mouse cursor mousecursor STR Mouse cursor file Loads a Windows mouse cursor definition file (.cur) and utilizes it. Non-recommendation of this command is removed as of ver2.93. NE toggle mouse cursor display mousemode NUM Mouse cursor display flag (0: hidden, 1: displayed) Setting mousemode 0 hides the mouse cursor, while mousemode 1 displays it. NOEP move the mouse to a particular position on the screen movemousecursor NUM,NUM X-coordinate for mouse cursor destination Y-coordinate for mouse cursor destination Moves the mouse cursor to an arbitrary position on the screen. This moves the mouse to (100,10). movemousecursor 100,10 NE get the text window coordinates of the start of the following line getnextline %VAR,%VAR Numeric variable for the text window X-coordinate of the following line 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. This puts the X and Y coordinates of the next line in %0 and %1. getnextline %0,%1 NOEP change alpha blend transparency mode transmode {leftup,copy,alpha} leftup: top-left pixel color, copy: no transparency, alpha: alpha-blend Change the default transparency mode. leftup is the default setting.
This essentially makes any image-definition string without a transparency setting use "l" for leftup, "c" for copy, or "a" for alpha; see lsp for more details. NOEP set ground line for standing images underline NUM Y-coordinate of ground line Specifies the ground line for standing pictures. The default value is 479. This command was allowed in the program block since ver2.92. NOEP set parameters for a nonstandard background bgalia NUM,NUM,NUM,NUM Top-left X-coordinate Top-left Y-coordinate Background width 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). NOEP designate overlap priority for sprites and standing images humanz 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. NOEP insert text window at the same overlap level as standing image(s) windowback Inserts the text window at the same level as standing pictures. Can be used for a 'positional subtitle' effect. The text window is drawn on top of the standing image layer, which is drawn on top of the sprite at humanz level. Meanwhile, sprites with number less than the humanz value will appear on top of the text window. (by senzogawa) In reality, NScr draws the sprite at humanz level above the text window, which is above the standing image layer.
ONScripter-EN draws the sprite with humanz number between the text window and standing image layers when windowback is in effect; this allows placement of a graphic covering the images but under the text. (by Mion) NOEP set background image bg STR,EFFECT Image filename Effect for displaying background bg COLOR,EFFECT #rrggbb color for background Effect for displaying background bg {black|white},EFFECT Use basic black/white for background Effect for displaying background Loads the background image, using the given effect and final image/color. NOEP set standing image ld {l,c,r},STR,EFFECT standing pic position (l: left, c: center, r: right) Image filename Effect for displaying standing picture Loads a standing picture. Use l for left, r for right, c for center.
The character string is the image filename; the image tag is automatically generated as well. NOEP erase specified standing image cl {l,c,r,a},EFFECT standing pic position (l: left, c: center, r: right, a: all) 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. NOEP modify standing image opacity tal {l,c,r},NUM,EFFECT standing pic position (l: left, c: center, r: right) Opacity value (0 - 255) Effect for changing standing picture opacity Changes the opacity of the specified standing picture to the given value: 0 is fully transparent, 255 is fully opaque. The official manual omits the effect specification, which causes an error. (by senzogawa via "hau") NOEP display images while removing those that should be hidden print EFFECT Display effect Draws to the screen utilizing the designated effect.

You may set the effect to use in one of two ways:
1) By effect tag
0: draws only to memory, not to screen
1: instantaneous display
>1: the tag of an effect defined by the effect command

2) Direct designation
2-18: Use the same parameters as used for the effect command
99: Use for plugin-based effects. You must provide a plugin specification string of format: "plugin-name/plugin-parameters".


The following display commands, like print, take effect specs:
bg ld cl

All other display-related commands must be followed by print or one of the above commands in order to update the screen display. Plugin-based effect support was added in ver.2.03, and the effect plugin api was extended in ver.2.37. Only NScripter supports plugins.
At present, ONScripter-EN supports the following "plugin-based" wipe effects (originally created by Takashi Toyama), via emulation: "breakup.dll", "cascade.dll", "trvswave.dll", "whirl.dll". (by Mion) Display the background "test.jpg" and the standing picture "testman.jpg" simultaneously, then remove the standing picture using set effect 3. bg "test.jpg",0 ld c,"testman.jpg",1 cl c,3 Display the background "test.jpg" via a one-second crossfade, then display the standing picture "testman.jpg" on the left side via a two-second masked fade using "mask.bmp". bg "test.jpg",10,1000 ld "testman.jpg",15,2000,"mask.bmp" Display the background "test.jpg" via the plugin-effect "clockwip.dll". bg "test.jpg",99,1000,"clockwip.dll/l" NOEP load sprite into memory lsp NUM,STR,NUM,NUM[,NUM] Sprite number (0 - 999) Image filename or processing tag Top-left X-coordinate Top-left Y-coordinate Opacity value (0 - 255) Loads and displays a sprite. Sprite numbers may range from 0 to 999.
The other numbers are, from left to right: x coordinate of upper left pixel, y coordinate of upper left pixel, and optional opacity value (0 for transparent up to 255 for opaque).
The only difference between lsp and lsph is the beginning condition of the sprite - lsp displays the sprite, while lsph keeps the sprite hidden (which may later be displayed with vsp).

Image processing tag format:
"[:(trans-mode)[/(animation)];](filename)"
OR
":s[/(string-params);](color)[(color)...](text-string)" (added Ver.1.80)
OR
"[:(trans-mode)[/(animation)];]>(width),(height),(color)[(color)...]" (added Ver.2.93)

The first format is for processing image files - note that the (filename) by itself is fine for single-cell default transparency images. The possible arguments are:
(transmode):
l - for 'leftup'; the color of the top-left pixel will be used as the transparent color
r - for 'rightup'; the color of the top-right pixel will be used as the transparent color
c - for 'copy'; shows the image as-is, no transparency settings
a - for 'alphablend'; the right half of the image contains alpha-level data for the left half
m(filename) - for 'mask'; uses the given file as alpha-level data for the main image

Note that for alpha-levels, black (#000000) = opaque and white (#ffffff) = completely transparent.
If (transmode) is omitted, it assumes the default transparency setting provided via the transmode command.

(animation): (num-cells),(delay),(loop-type)
This optional parameter set tells how to animate a sprite with multiple cells.
The image gets 'cut' into (num-cells) pieces, going from left to right. If the image contains alpha-level data, then each cell contains its own alpha-data in its right-half.
The (delay) can either be a single value, telling the number of milliseconds to spend on each cell; or else it can have the format <(cell-1-delay),(cell-2-delay,...(cell-n-delay)>, giving varying delays per cell.
The (loop-type) is a number telling how to cycle between the cells:
0 - a repeated cycle (0,1,...n,0,1,...)
1 - single time through (0,1,...n)
2 - a 'bouncing' cycle (0,1,...n,n-1,...1,0,1,...)
3 - no cycle (0); cell number is changed via cell command or sprite control (see spstr)

The second tag format is for creating string sprites:
":s[/(string-params);](color)[(color)...](text-string)"
Note that at least one color setting (#rrggbb) must be provided with the text. Other arguments are:
(string-params): (char-width),(char-height),(X-spacing),(decor)
The character width, height, and spacing are the same kinds of numeric values used for setwindow, for example.
The (decor) value describes a style for the text:
0 - standard
1 - none
2 - open face
If (string-params) are omitted, the text uses the sizing, spacing and style set by setwindow or spfont.
If multiple (color) values are provided, it creates a string sprite with multiple cells - each cell with each different color. This can be useful for making text buttons.
For finer control and/or to make multiple-line string sprites, use the strsp command instead.

The NEW third format is for creating single-color rectangle sprites:
"[:(trans-mode)[/(animation)];]>(width),(height),(color)[(color)...]"
The (trans-mode) and (animation) have the same syntax as used in the first tag format. The (width) and (height) provide the width and height of the resulting rectangle.
Note that there must be at least one color value provided; if multiple (color) values are provided, it creates a rectangle sprite with multiple cells - one cell for each different color. Loads image "thing1.bmp", using default transparency type. lsp 2,"thing1.bmp",0,0 Loads image "thing1.bmp", using "mask1.bmp" for transparency data. lsp 2,":mmask1.bmp;thing1.bmp",0,0 The default clickwait cursor: 'leftup' transmode, bouncing through 3 cells (0,1,2,1,0,...) with 160ms delay per cell. lsp 0,":l/3,160,2;cursor0.bmp",0,0 The default clickwait cursor, but with 'jerky' animation. lsp 0,":l/3,<160,1000,400>,2;cursor0.bmp",0,0 Creates a 100x50 rectangular sprite with 2 cells (white and gray). lsp 0,":c;>100,50,#FFFFFF#888888",200,200 NOEP load sprite into memory (hidden) lsph NUM,STR,NUM,NUM[,NUM] Sprite number (0 - 999) Image filename or sprite processing string Top-left X-coordinate Top-left Y-coordinate Opacity value (0 - 255) Loads a sprite in a hidden state.
The only difference between lsp and lsph is the beginning condition of the sprite - lsp displays the sprite, while lsph keeps the sprite hidden (which may later be displayed with vsp). NOEP delete sprite from memory csp NUM Sprite number (0 - 999), or -1 for all Erases the given sprite.
If the given value is -1, it erases all sprites. NOEP toggle display of a loaded sprite vsp NUM,NUM Sprite number (0 - 999) visibility flag (0: not visible, 1: visible) Toggles display of specified sprite. 0 is off, 1 is on. NOEP execute the given control string for complex-button sprite display spstr STR sprite control string You can use this command to manually control sprites using the control string format of the exbtn command.

Just like with csp, lsp and vsp, you need to call print afterwards to have anything show up on screen. Clears Sprite 11, displays cell 2 of Sprite 10, and displays Sprite 9. spstr "C11P10,2P9" NOEP change sprite position (relative) msp NUM,NUM,NUM[,NUM] Sprite number (0 - 999) X-coordinate offset Y-coordinate offset Opacity offset Moves the sprite of the designated number, adjusting the position and opacity relative to their current values.

Like the tal command, and other sprite system commands, The results of msp will not show up immediately on screen (this is for ease and speed of batch processing).
So before you call any text or image display commands after an msp, please call a print command to update the screen before continuing. NOEP change sprite position (absolute) amsp NUM,NUM,NUM[,NUM] Sprite number (0 - 999) X-coordinate Y-coordinate Opacity (0 - 255) Similar to msp, but moves the sprite to an absolute instead of relative position. This moves Sprite 2 to position (5,2) and gives it an opacity of 100 (out of 255). amsp 2,5,2,100 NOEP manually designate the cell of a sprite cell NUM,NUM Sprite number (0 - 999) 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. NOEP blit image onto screen instantaneously blt NUM,NUM,NUM,NUM,NUM,NUM,NUM,NUM Onscreen top-left X-coordinate Onscreen top-left Y-coordinate Onscreen width Onscreen height In-buffer top-left X-coordinate In-buffer top-left Y-coordinate In-buffer width 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). NOEP transfer an image drawn by blt to the offscreen buffer ofscpy Copies things drawn using a blt command to the offscreen buffer.
Explanation:
Once you have blitted an image onto the screen, and want to use an effect on it, you would use this command to copy it to the offscreen buffer.
The offscreen buffer saved by this command may be used in effects, just like any other screen buffer.
The image and the effect will display, but they will not be remembered via load/save.

By using blt and ofscpy together, you can create engine cutscenes and such (like those found in AIR). btndef "～" ;read animation images bg ～ ld c,～ ;all commands up until this point have been standard image commands, so they will show fine. resettimer blt ～ waittimer 100 blt ～ waittimer 100 ;in this fashion we display images one after the other for an engine cutscene. ;now that we've blitted a bunch of stuff, to use effects on the image, we need to copy it to the offscreen buffer. ofscpy bg ～ ;and now you can do anything you want to either the onscreen or the offscreen buffer. bg ～ ld c,～ NOEP redraw screen repaint Repaints the screen. Call this command if you start getting strange artifacting and such onscreen. NOEP hide all sprites at the same time allsphide Hides all sprites at the same time. NOEP redisplay sprites hidden with allsphide allspresume Redisplays the sprites that were hidden by allsphide. NOEP set priority levels for standing image positions humanorder STR,EFFECT Standing image positions in priority order, e.g. "lcr" Transition effect to use during image priority change Specifies the overlapping priority for standing images. Sets the standing picture priorities to display right atop center atop left. humanorder "rcl",1 NE set coordinates for standing image positions humanpos NUM,NUM,NUM Standard X-coordinate for "l" standing image position Standard X-coordinate for "c" standing image position 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. NOEP copy current screen to the background 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. NOEP return the sprite's size getspsize NUM,%VAR,%VAR[,%VAR] Sprite number Result numeric variable for sprite width Result numeric variable for sprite height 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. Grabs the size of Sprite 0 and assigns %0 its width, %1 its height, and %2 its current cell. getspsize 0,%0,%1,%2 NOEP return whether the given sprite is displayed getspmode %VAR,NUM Result numeric variable Sprite number This returns 1 if the given sprite is displayed, 0 if the sprite is hidden. Sets %2 to 1 if Sprite 10 is displayed, 0 if it is hidden. getspmode %2,10 N set the font used for string sprites spfont STR,NUM,NUM,NUM,NUM,NUM,NUM Font name (Full-width) text font width Text font height Text spacing X Text spacing Y Boldface toggle (0=off/1=on) Drop shadow toggle (0=off/1=on) spfont clear clear: use font settings from setwindow spfont STR Font name This sets the font to use for string sprites, e.g. ":s;名".
spfont clear reverts to using the font settings from setwindow.

It's also possible to omit all but the first argument: spfont (font-name)
Doing so will have string sprites use the given font face but all other settings will come from setwindow. This command was allowed in the program block since ver2.62.
Ver2.66 corrected bugs with using spfont and setwindow settings.
The "clear" option was added in ver2.67. Change the string sprite font to (JP) MS Gothic, 16x16, no spacing, bold & drop-shadowed. spfont "ＭＳ ゴシック",16,16,0,0,1,1 Revert to the font settings of setwindow for string sprites. spfont clear NOEP create and display a sprite of a multi-line character string strsp NUM,STR,NUM,NUM,NUM,NUM,NUM,NUM,NUM,NUM,NUM,NUM[,COLOR[,...]] Sprite number String of text to render as a sprite X-coordinate of top left Y-coordinate of top left Number of (full-width) text columns Number of text lines (Full-width) text font width Text font height Text spacing X Text spacing Y Boldface toggle (0=off/1=on) Drop shadow toggle (0=off/1=on) Optional color(s) This creates a multi-line string sprite, using the font face specified by spfont.
Use "\" to move to the next line. Note that text will run to the end of the available columns and continue onto the next line, without using linebreak or kinsoku conventions, so the "\" are necessary for proper string display.
If optional colors are provided, then the sprite will have a cell for each given color, with the text in that color. This command was originally an alias of logsp2, but was given its own specification in ver2.65. NE create a sprite of a multi-line character string, hidden strsph NUM,STR,NUM,NUM,NUM,NUM,NUM,NUM,NUM,NUM,NUM,NUM[,COLOR[,...]] Sprite number String of text to render as a sprite X-coordinate of top left Y-coordinate of top left Number of (full-width) text columns Number of text lines (Full-width) text font width Text font height Text spacing X Text spacing Y Boldface toggle (0=off/1=on) Drop shadow toggle (0=off/1=on) Optional color(s) Works the same as strsp, except that the sprite starts out hidden. NOEP designate an effect effect NUM,NUM[,NUM[,STR]] Effect number (2 - 255) Built-in effect number (1 - 18,) Duration (msec) 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. Sets Effect 2 to be an upwards shutter of one second. effect 2,4,1000 Sets Effect 3 to be a two second masked fade. effect 3,15,2000,"m3.bmp" NOEP designate wait duration after an effect is over effectblank 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. NOEP toggle effect runtime during "skip to next choice" mode effectcut Skip all effects in "skip to next choice" mode. NE specify whether effects can be skipped effectskip 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. Allows skipping during an effect with click. effectskip 1 NOEP cause a shaking screen effect quake NUM,NUM Amplitude (pixels) Duration (msec) Causes an onscreen random quake effect of the given amplitude and duration. Can be slow on older graphics cards. This shakes the screen for 1 second with an 8-pixel amplitude. quake 8,1000 NOEP cause a horizontal shaking effect quakex NUM,NUM Amplitude (pixels) Duration (msec) Works just like quake, except it only shakes the screen from side-to-side (horizontally). NOEP cause a vertical shaking effect quakey NUM,NUM Amplitude (pixels) Duration (msec) Works just like quake, except it only shakes the screen up-and-down (vertically). NOEP make screen monochrome/color-toned monocro COLOR Base color monocro off Fades the screen to monochrome, using the given color as a base.
The text window and cursor will not follow suit.
Use "off" as the parameter to make the colors return to normal. NOEP set negative screen display nega NUM Display flag (0: off, 1: monochrome-priority, 2: negative-priority) If flag is 1 or 2, it causes a negative of the current image.
Use 1 to apply (any) monocro on top of the nega, 2 to apply nega atop the monocro (i.e. 1 applies nega first, 2 applies monocro first).
If 0, the image flips back to positive.
Neither monocro nor nega update the screen themselves, so please call print afterwards. NE execute flushout effect flushout 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. NOEP display contents of numeric variable %NUM Numeric variable number Tag for numeric variables. Use this to access their contents within text. NOEP display contents of string variable $NUM String variable number Tag for character string variables. Use this to access their contents within text. NOEP display contents of array variable ?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. 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 ＶＡＬ＝?0[2][3]@ An example of array usage in single-byte text `Array value = `?0[2][5]`.@ NOEP create and display a (graph) bar bar NUM,NUM,NUM,NUM,NUM,NUM,NUM,COLOR Bar number Bar current value Top-left X-coordinate Top-left Y-coordinate Bar width Bar height Bar maximum value 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. NOEP clear bar display barclear Clears out bars.
You can think of the bars as being like life bars in fighting games, kind of. NOEP initialize a numeric label prnum NUM,NUM,NUM,NUM,NUM,NUM,COLOR Numeric label number Current value Top-left X-coordinate Top-left Y-coordinate Character width Character height Label color Creates a numeric value label, and then blits its current value in the given position at the given size and color.
A label can take 3 columns, so they can range from 0 to 999 in value.
You need to call a print command or something like it to actually display this onscreen.

bar and prnum were specifically created for mode_saya, which was in-turn specifically created for the doujin game "Saya ~Labyrinth of Immorality~".
There are plans to replace these commands with something a little bit more generalized and powerful. Deprecated since ver2.93; the behavior of this command is environment-dependent. NOEP clear numeric labels prnumclear Clears the numeric value labels. N specify duration of CD-DA fade-out cdfadeout 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) N determine if CD drive contains a file called "filename" chkcdfile STR,STR File name to check for 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". This checks the CD for "file.dat". chkcdfile "file.dat","CDがありません" N determine if CD drive contains a file called "filename" chkcdfile_ex %VAR,STR Result numeric variable 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. This checks the CD for "file.dat" and assigns the result to %0. chkcdfile_ex %0,"file.dat" NE specify duration of BGM fade-out mp3fadeout NUM MP3 playback fade-out time (msec) Sets MP3 (BGM) fadeout time in milliseconds. Same as bgmfadeout (added in Ver2.21). In versions of ONScripter-EN before 20090417, mp3fadeout did an immediate fadeout instead of setting the behavior for mp3stop. (by Mion) NOEP play specified CD-DA track or MIDI file in a loop play STR MIDI filename or CD track number label Plays a MIDI file or CD audio track.

If you specify a file name, then the corresponding MIDI file will be played, but if you specify "*(number)", then the appropriate CD track will play.

play will loop the MIDI file/CD audio; if you want a file/track to play once, use the playonce command. NOEP play specified CD-DA track or MIDI file only once playonce STR MIDI filename or CD track number label Plays a MIDI file or CD audio track.

If you specify a file name, then the corresponding MIDI file will be played, but if you specify "*(number)", then the appropriate CD track will play.

Use play to loop the MIDI file/CD audio instead of playing just once. NOEP stop playback of CD track or MIDI file playstop Stops MIDI/CD audio playback. NOEP play a WAV file only once wave STR WAV filename Plays the specified WAV file.
wave plays it once, while waveloop loops it. NOEP loop WAV file playback waveloop STR WAV filename Plays the specified WAV file.
wave plays it once, while waveloop loops it. NOEP stop WAV file playback wavestop Stops WAV file playback. NOEP play compressed music file only once mp3 STR MP3 filename If mp3dec.dll is used (this functionality is built into ONScripter), you can use this to play an mp3 file. mp3 plays the file only once, while mp3loop loops the file. You may issue wave commands while mp3's are playing with no ill effects. NOEP play compressed music file in a loop mp3loop STR MP3 filename If mp3dec.dll is used (this functionality is built into ONScripter), you can use this to play an mp3 file. mp3 plays the file only once, while mp3loop loops the file. You may issue wave commands while mp3's are playing with no ill effects. NOEP if game saved during playback, resume playing upon reload mp3save Just like the mp3 command, this plays back an mp3 only once; however, if the player saves during playback, the mp3 will start playing upon reload. NOEP declare that you are using DirectSound (unnecessary in latest versions) 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. NOEP play WAV file using DirectSound only once dwave NUM,STR Channel number (0 - 49) 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) This plays "test.wav" in channel 0 just once. dwave 0,"test.wav" NOEP loop-play a WAV file using DirectSound dwaveloop NUM,STR Channel number (0 - 49) 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) NOEP stop DirectSound WAV file playback dwavestop NUM Channel number (0 - 49) Silences that particular channel. NOEP load WAV file into memory dwaveload NUM,STR Channel number (0 - 49) 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) This loads "test.wav" into channel 0, then plays it just once. dwaveload 0,"test.wav" dwaveplay 0 NOEP play a preloaded WAV file only once dwaveplay 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) NOEP loop-play a preloaded WAV file dwaveplayloop NUM Channel number (0 - 49) Loops the WAV file loaded by dwaveload. NOEP stop all music playback stop Stop playback of all sound. Here, "all sound" means bgm and wave playback, but not loopbgm or dwave playback. (by Mion) NOEP stop playback of compressed music mp3stop Stops playback of compressed music. NE specify duration of BGM fade-in mp3fadein NUM BGM playback fade-in time (msec) The same as bgmfadein. NOEP play compressed music file in a loop bgm STR Music filename Plays the given compressed music file in a loop. Equivalent to the mp3loop command. Plays "bgm01.mp3" in a loop bgm "bgm01.mp3" NOEP play compressed music file only once bgmonce STR Music filename Plays the given compressed music file one time through. Equivalent to the mp3 command. Plays "bgm01.mid" once bgm "bgm01.mid" NOEP stop playback of compressed music bgmstop Stops playback of compressed music. NE specify duration of BGM fade-out bgmfadeout NUM BGM playback fade-out time (msec) Sets BGM fadeout time in milliseconds. NE specify duration of BGM fade-in bgmfadein NUM BGM playback fade-in time (msec) The same as bgmfadeout, except that this is for fadein time. NOEP play intro, then loop repeatedly loopbgm STR,STR Intro music filename Looped music filename Plays the first music file, then once it's finished, loops the second file until stopped. First plays "bgm_s.wav" then loops "bgm_l.wav" ("bgm_s.wav" -> "bgm_l.wav" -> "bgm_l.wav" -> ...) loopbgm "bgm_s.wav","bgm_l.wav" NOEP stop playback of loopbgm loopbgmstop Stops playback of loopbgm music. NOEP change BGM sound volume mp3vol 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) Sets BGM volume to maximum (100) mp3vol 100 NOEP change sound volume of the given dwave channel chvol NUM,NUM DWAVE channel number (0 - 49) 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. Sets Channel 3 volume to maximum (100) chvol 3,100 NOEP change voice sound volume voicevol NUM Sound volume (0-100) Changes the sound volume for voices. Volume changes are not saved, so manage them manually or with variables. Sets voice volume to maximum (100) voicevol 100 NOEP change SFX sound volume sevol NUM Sound volume (0-100) Changes the sound volume. Volume changes are not saved, so manage them manually or with variables. Sets sound effect volume to maximum (100) sevol 100 NOEP change BGM sound volume bgmvol 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) Sets BGM volume to maximum (100) bgmvol 100 NOEP voice playback, shorthand cmd (wave) 'v'NUM':' Voice file number This is a shorthand command for playing voice files.
It is equivalent to wave "voice\(num).wav". (p)onscr seem to map this command to wave "wav\(num).wav" instead. (by Mion) This plays "voice\0001.wav" via the wave command before outputting text. v0001:「これが０００１番のせりふだよー」 NOEP voice playback, shorthand cmd (dwave) 'dv'NUM':' Voice file number This is a shorthand command for playing voice files.
It is equivalent to dwave 0,"voice\(num).wav". This plays "voice\0001.wav" via the dwave command on channel 0 before outputting text. dv0001:「これが０００１番のせりふだよー」 NE playback an mp3 voice file 'mv'NUM':' Voice file number This is a shorthand command for playing mp3 voice files.
It is equivalent to mp3 "voice\(num).mp3". This plays "voice\0001.mp3" via the mp3 command before outputting text. mv0001:「これが０００１番のせりふだよー」 NE toggle turning down BGM volume when voices are played bgmdownmode NUM 0: off, 1: on Sets whether the BGM volume should be lowered while a voice sound is playing. Sets to have music volume turned down during voice playback. bgmdownmode 1 N playback an AVI file avi STR,NUM Movie filename 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. NOEP playback an MPEG movie mpegplay STR,NUM Movie filename Interrupt flag (0: play whole thing, 1: click-interruptible) Plays an MPEG video file. The second parameter can be 0 or 1, and determines whether the player must watch the whole movie (0) or can skip the movie by clicking (1). This plays "test.mpeg", click-interruptible. mpegplay "test.mpeg",1 NOE play a movie movie STR[,'pos',NUM,NUM,NUM,NUM][,'click'][,'loop'][,'async'] Movie filename Movie window top-left X coordinate Movie window top-left Y coordinate Movie window width Movie window height movie stop This movie playback command is intended to replace mpegplay.

The following options may be combined:
movie "filename" ;Plays until completion, can't be interrupted
movie "filename",pos,10,20,320,240 ;Positions the movie within a 320x240 window with top-left at (10,20)
movie "filename",click ;Movie playback is click-interruptible (not valid in async mode)
movie "filename",loop ;Plays the movie repeatedly (must be combined with either click or async, otherwise it can't be stopped!)
movie "filename",async ;Asynchronous playback. The script returns to command interpretation while playback continues. The movie will always be the top layer on-screen, even atop text.
movie stop ;Use this to stop async movie playback The movie image remains on-screen after playback finishes.
Since the movie is considered invalid data, it's possible to revert to the screen as it was beforehand by using print. This plays "test.mpg" looped, within a 320x240 window at coordinate (10,20), and asynchronously; it then stops playback after a 30 second wait. movie "test.mpg",pos,10,20,320,240,async,loop wait 30*1000 movie stop This plays "test.mpg", click-interruptible, then crossfades to the previous screen after playback is complete. movie "test.mpg",click print 10,1000 NOEP designate the text colors for choices selectcolor COLOR,COLOR Mouseover color Mouseoff color Specifies, in order, the mouseover and the mouseoff colors for choice text. NOEP designate sound(s) to play during choice selection selectvoice STR,STR,STR WAV file that plays at choice dialog entry WAV file that plays upon mouseover of a choice WAV file that plays when a choice is clicked Designate WAV files to play in the choice dialog. From left to right: upon entry into choice dialog, upon mouseover of choice text, and finally upon clicking on a choice text. NOEP create a choice select STR,LABEL[,STR,LABEL[,...]] Displayed choice Choice select destination Displays a selection of choices, and then jumps to the label associated with the selected choice.
If the character string is set to "", then that choice will not be displayed.
(This works the same way as selnum and selgosub.)
But be careful, as this command will cause the interpreter to hang if you do not specify even a single choice as a parameter. NOEP create a choice that jumps to a subroutine selgosub STR,LABEL[,STR,LABEL[,...]] Displayed choice Choice select destination Works the same as select, except this command jumps to a subroutine, not a generalized label. NOEP create a choice that returns a number based on selection selnum %VAR,STR[,STR[,...]] Numeric result variable Displayed choice Works somewhat like select and selgosub, except that there are no jumps - instead, depending on which character string is clicked, a number (starting at 0, then incrementing by 1 for each string) is loaded into the given numeric variable. Unlike with select and selgosub, a null character string ("") can't be provided as a choice. (by senzogawa) NOEP jump to designated label goto LABEL Jump destination Jump to the given label name. (Can cause spaghetti code.) NOEP skip the next n lines of script skip NUM Number of script lines to skip Skips the designated number of lines. Can skip forward (-) or backward (+). NOEP call a subroutine gosub 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. NOEP return from a subroutine return [LABEL] Optional return destination Used at the end of a routine called by gosub to return to the next command after the gosub call itself. The optional return destination label was added in Ver.2.67. (by senzogawa) NOEP jump forward to the next ~ symbol 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) jumpf ;I am a line that gets skipped. ~ ;I am a line that isn't skipped. NOEP jump back to the previous ~ symbol jumpb Return to the last ~ symbol. Be careful about "~" chars in comments and such around this command. (by senzogawa) NOEP jump to a label in the table based on the numeric value tablegoto %VAR,LABEL[,LABEL[,...]] Numeric variable with an index into the jumptable A jump destination label within the table Creates a jump table.
If the variable is set to 0, it jumps to the first label; if 1, the second label; and so forth. Jumps to one of *label0 - *label3, depending on the value of %0 tablegoto %0,*label0,*label1,*label2,*label3 NOEP jump to specified label on left click trap LABEL Destination for jump upon left-click trap off After this command, a left-click will cause a jump to the specified label.
This trap mode deactivates itself immediately thereafter, or you can deactivate it manually (before the jump happens) by using trap off. NE jump to specified label on right click r_trap LABEL Destination for jump upon right-click r_trap off After this command, a right-click will cause a jump to the specified label.
This trap mode deactivates itself immediately thereafter, or you can deactivate it manually (before the jump happens) by using r_trap off.
It behaves the same as trap and lr_trap, except that it only activates on right-clicks. This command also reacts to left-clicks since ver2.75. (by senzogawa) -WHY? isn't that what lr_trap is for? (by Mion) NOEP jump to specified label on left or right click lr_trap LABEL Destination for jump upon click lr_trap off Traps left and right clicks (or turns said trap off), directing the interpreter to the given label name. NOEP jump to label on left click when "skip to next choice" mode is set trap2 LABEL Destination for jump upon left-click during skip mode trap2 off This is the same as trap, except it is the one that should be used when "skip to next choice" mode is active. NOEP jump to label on left or right click when "skip to next choice" mode is set lr_trap2 LABEL Destination for jump upon click during skip mode lr_trap2 off Similar to lr_trap, except this one functions in "skip to next choice" mode. NOEP load image file into button memory buffer btndef 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. NOEP initialize image as button (method 1) btn NUM,NUM,NUM,NUM,NUM,NUM,NUM Button number Top-left X-coordinate Top-left Y-coordinate Button width Button height X-shift 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. NOEP display image button and enter a click-wait state (method 1) btnwait %VAR 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. NOEP display image button and enter a click-wait state (method 2) btnwait2 %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) NOEP designate a sprite as an image button spbtn NUM,NUM Sprite number Button number Just like the btn command, except it sets up an image button using a sprite. It uses cell 0 as the graphic for the nonclicked state and cell 1 for the clicked state.
When the button is pressed during a btnwait, it returns the given button number as a value. NOEP designate a sprite as a button only if the sprite has at least 2 cells cellcheckspbtn NUM,NUM Sprite number 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.) 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 NOEP acquire how much time passed during btnwait getbtntimer %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). NOEP set a time limit for image button functionality btntime 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) NOEP same as btntime, but waits for voice to finish btntime2 NUM Time limit for button wait (msec) This is the same as btntime, except that the timeout will wait for voices to finish. Sets so the next btnwait will have a 1 second timeout. btntime2 1000 NOEP create a complex button exbtn NUM,NUM,STR Sprite number Button number 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. Clears Sprite 10. spstr "C10" Clears Sprite 11 and displays Sprite 10. spstr "C11P10" Clears Sprite 11, displays cell 2 of Sprite 10, and displays Sprite 9. spstr "C11P10,2P9" NOEP create a complex button only if the sprite has at least 2 cells exbtn NUM,NUM,STR Sprite number Button number 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. 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" NOEP specify default behavior for when complex buttons are used exbtn_d 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. 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" NE ignore transparent areas when creating a button from an image transbtn This will prevent transparent areas of a button image from activating the button.
Please use this command after a btndef but before the btnwait command. NOEP wait for the specified time !dNUM 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. NOEP wait for the specified time, ignoring clicks !wNUM 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. NOEP cause a time delay (method 1) delay 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. NOEP cause a time delay (method 2) wait NUM Amount of time to wait (msec) Causes a delay of specified time (in milliseconds) that may not be escaped out of by clicking.
This works the same as the special text command '!w', but here you can supply a variable as the argument. NOEP reset the internal timer resettimer Sets the internal timer back to 0. This timer runs on a millisecond scale. NOEP wait until the internal timer reaches the specified time value waittimer NUM Time-value to wait for on the internal timer (msec) Waits until the internal timer has passed the specified time before proceeding.
This command is the single most accurate timing measure in all of NScripter.
The timing intervals of things like image effect runtimes are not nearly this accurate, so be careful when you mix and match timing methods. It may be necessary to do wait 0 in cases where sprite animation stalls due a mismatch with the internal timer. (by BBS) NOEP get the value of the internal timer gettimer %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. N wait until the designated sprite's animation has ended spwait NUM Sprite number Waits for the animation of the given sprite number to be either finished or cut short by the user. Waits for the animation of Sprite 0 to finish. spwait 0 NOEP create an alias for a filename or character string stralias NAME,STR Alias name String value given by alias Makes an alias for the given character string as then given name - in other words, after this declaration, you can refer to that character string using that NAME in all cases. Use an alias "man_a0" for the file ":a/10,20,2;man_alpha.bmp". stralias man_a0,":a/10,20,2;man_alpha.bmp" ;Now the following 2 lines are equivalent. ld c,man_a0,1 ld c,":a/10,20,2;man_alpha.bmp",1 NOEP create an alias for a numeric value numalias NAME,NUM Alias name Numeric value given by alias Creates a name that serves as an alias for a numeric value. Use an alias "ef_lshutter" for the number 2. numalias ef_lshutter,2 ;Now the following 2 lines are equivalent. bg "test.bmp",ef_lshutter bg "test.bmp",2 (Advanced) Use a numeric alias for a variable number. numalias akari_love,0 ;Now the following 2 lines are equivalent. add %akari_love,10 add %0,10 NOEP set the allowed range for a numeric variable intlimit NUM,NUM,NUM Numeric variable number Minimum allowed value 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. This sets the allowed range for numeric variable 0 to be 10 to 20. intlimit 0,10,20 NOEP declare an array variable dim '?'NUM'['NUM']' [ '['NUM']'... ] Array number (0 - 199) 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! 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]. ＶＡＬ＝?0[2][3]@ ;used in text Using an alias with an array numalias enemyparam,10 dim ?enemyparam[10] NOEP load a numeric/string variable with a value mov %VAR,NUM Numeric variable Numeric value mov $VAR,STR String variable Character string value Assigns a variable with a new value. Sets numeric variable %3 to 24. mov %3,24 Sets string variable $0 to a filename. mov $0,"myfile.jpg" NOEP load numeric values into 3 consecutive variables mov3 %VAR,NUM,NUM,NUM Numeric variable Numeric value #1 Numeric value #2 Numeric value #3 This command fills 3 numeric variables - starting from the one specified and incrementing upward - with the specified numbers.

mov4, mov5, mov6, mov7, mov8, mov9, and mov10 all follow suit from this. This can't be used with string variables. (by senzogawa) Sets %3 to 2, %4 to 4, and %5 to 6. mov3 %3,2,4,6 ;is equivalent to ;mov %3,2 ;mov %4,4 ;mov %5,6 NOEP load numeric values into 4 consecutive variables mov4 %VAR,NUM,NUM,NUM,NUM Numeric variable Numeric value #1 Numeric value #2 Numeric value #3 Numeric value #4 This command fills 4 numeric variables - starting from the one specified and incrementing upward - with the specified numbers. This can't be used with string variables. (by senzogawa) Sets %3 to 2, %4 to 4, %5 to 6, and so forth. mov3 %3,2,4,6,8 ;is equivalent to ;mov %3,2 ;mov %4,4 ;mov %5,6 ;mov %6,8 NOEP load numeric values into 5 consecutive variables mov5 %VAR,NUM,NUM,NUM,NUM,NUM Numeric variable Numeric value #1 Numeric value #2 Numeric value #3 Numeric value #4 Numeric value #5 This command fills 5 numeric variables - starting from the one specified and incrementing upward - with the specified numbers. This can't be used with string variables. (by senzogawa) Sets %3 to 2, %4 to 4, %5 to 6, and so forth. mov3 %3,2,4,6,8,10 ;is equivalent to ;mov %3,2 ;mov %4,4 ;mov %5,6 ;mov %6,8 ;mov %7,10 NOEP load numeric values into 6 consecutive variables mov6 %VAR,NUM,NUM,NUM,NUM,NUM,NUM Numeric variable Numeric value #1 Numeric value #2 Numeric value #3 Numeric value #4 Numeric value #5 Numeric value #6 This command fills 6 numeric variables - starting from the one specified and incrementing upward - with the specified numbers. This can't be used with string variables. (by senzogawa) Sets %3 to 2, %4 to 4, %5 to 6, and so forth. mov3 %3,2,4,6,8,10,12 ;is equivalent to ;mov %3,2 ;mov %4,4 ;mov %5,6 ;mov %6,8 ;mov %7,10 ;mov %8,12 NOEP load numeric values into 7 consecutive variables mov7 %VAR,NUM,NUM,NUM,NUM,NUM,NUM,NUM Numeric variable Numeric value #1 Numeric value #2 Numeric value #3 Numeric value #4 Numeric value #5 Numeric value #6 Numeric value #7 This command fills 7 numeric variables - starting from the one specified and incrementing upward - with the specified numbers. This can't be used with string variables. (by senzogawa) Sets %3 to 2, %4 to 4, %5 to 6, and so forth. mov3 %3,2,4,6,8,10,12,14 ;is equivalent to ;mov %3,2 ;mov %4,4 ;mov %5,6 ;mov %6,8 ;mov %7,10 ;mov %8,12 ;mov %9,14 NOEP load numeric values into 8 consecutive variables mov8 %VAR,NUM,NUM,NUM,NUM,NUM,NUM,NUM,NUM Numeric variable Numeric value #1 Numeric value #2 Numeric value #3 Numeric value #4 Numeric value #5 Numeric value #6 Numeric value #7 Numeric value #8 This command fills 8 numeric variables - starting from the one specified and incrementing upward - with the specified numbers. This can't be used with string variables. (by senzogawa) Sets %3 to 2, %4 to 4, %5 to 6, and so forth. mov3 %3,2,4,6,8,10,12,14,16 ;is equivalent to ;mov %3,2 ;mov %4,4 ;mov %5,6 ;mov %6,8 ;mov %7,10 ;mov %8,12 ;mov %9,14 ;mov %10,16 NOEP load numeric values into 9 consecutive variables mov9 %VAR,NUM,NUM,NUM,NUM,NUM,NUM,NUM,NUM,NUM Numeric variable Numeric value #1 Numeric value #2 Numeric value #3 Numeric value #4 Numeric value #5 Numeric value #6 Numeric value #7 Numeric value #8 Numeric value #9 This command fills 9 numeric variables - starting from the one specified and incrementing upward - with the specified numbers. This can't be used with string variables. (by senzogawa) Sets %3 to 2, %4 to 4, %5 to 6, and so forth. mov3 %3,2,4,6,8,10,12,14,16,18 ;is equivalent to ;mov %3,2 ;mov %4,4 ;mov %5,6 ;mov %6,8 ;mov %7,10 ;mov %8,12 ;mov %9,14 ;mov %10,16 ;mov %11,18 NOEP load numeric values into 10 consecutive variables mov10 %VAR,NUM,NUM,NUM,NUM,NUM,NUM,NUM,NUM,NUM,NUM Numeric variable Numeric value #1 Numeric value #2 Numeric value #3 Numeric value #4 Numeric value #5 Numeric value #6 Numeric value #7 Numeric value #8 Numeric value #9 Numeric value #10 This command fills 10 numeric variables - starting from the one specified and incrementing upward - with the specified numbers. This can't be used with string variables. (by senzogawa) Sets %3 to 2, %4 to 4, %5 to 6, and so forth. mov3 %3,2,4,6,8,10,12,14,16,18,20 ;is equivalent to ;mov %3,2 ;mov %4,4 ;mov %5,6 ;mov %6,8 ;mov %7,10 ;mov %8,12 ;mov %9,14 ;mov %10,16 ;mov %11,18 ;mov %12,20 NOEP load a line of numbers into an array movl ARRAY,NUM[,NUM[,...]] Array variable Numeric value Enters numbers into an array all at once. Define an array ?10 of length 5 and populate it. dim ?10[4] movl ?10,0,1,2,3,4 Define a two-dimensional array ?20 of size 3x4 and populate it, line by line. dim ?20[2][3] movl ?20[0],0,1,2,3 movl ?20[1],0,2,4,6 movl ?20[2],0,3,6,9 NOEP add/concatenate to variable add %VAR,NUM Numeric variable Numeric value to add add $VAR,STR String variable Character string to concatenate Add a number to a numeric variable. If used with strings, performs string concatenation instead. Replace the value stored at %0 with %0 + 6. add %0,6 Take the string variable $5 and tack "ああああ" to the end. add $5,"ああああ" NOEP do addition/concatenation NUM'+'NUM Numeric value to add Numeric value to add STR'+'STR Character string to be augmented 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. Adds 1 to the value of Array 0 Element 0. mov ?0[0],?0[0]+1 Assigns "●" to $1, then sets $2 to the concatenation of "あいうえお", $1, and "さしすせそ". mov $1,"●" mov $2,"あいうえお"+$1+"さしすせそ" ;Now $2 contains "あいうえお●さしすせそ". Assigns "Text" to $0, then concatenates " String" onto it. mov $0,`Text` mov $0,$0+` String` ;Now $0 contains "Text String". NOEP subtract a number from a variable sub %VAR,NUM Numeric variable Numeric value to subtract Subtract a number from a numeric variable. Subtract 6 from %0, then subtract the value of %2. sub %0,6 sub %0,%2 NOEP do subtraction NUM'-'NUM Numeric value to be subtracted from 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. NOEP increment a variable inc %VAR Numeric variable to increment Increments the value of the numerical variable by one. NOEP decrement a variable dec %VAR Numeric variable to decrement Decrements said variable by 1. NOEP multiply variable by a number mul %VAR,NUM Numeric variable Numeric value to multiply Multiplies the variable by the number and stores the result in the variable. NOEP do multiplication NUM'*'NUM Numeric value to multiply 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. NOEP divide variable by a number div %VAR,NUM Numeric variable Numeric value to divide by Divides the variable by the number, truncating the remainder. NOEP do division NUM'/'NUM Numeric value to divide 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. NOEP get the remainder (modulo) mod %VAR,NUM Numeric variable Numeric value to divide by and get remainder Finds the remainder after the variable is divided by the number (same as the x % y command in C). You can also use mod as an expression operator, as follows:
mov %0,%1 mod 2 NOEP generate a random number (method 1) rnd %VAR,NUM Numeric variable Upper range for the random number (0 to n-1) Generates a random number and sticks it in the numerical variable, ranging from 0 to (number - 1). The command has no effect if 0 is given as the second number. (by senzogawa) Get a random value from 0 to 99 and assign it to %5. rnd %5,100 NOEP generate a random number (method 2) rnd %VAR,NUM,NUM Numeric variable Lower range for the random number Upper range for the random number Generates a random number ranging from number 1 to number 2. Get a random value from 10 to 20 and assign it to %3. rnd2 %3,10,20 NOEP convert a numeric value into a string itoa $VAR,NUM String result variable Numeric value to convert Converts a number into a (half-width digit) character string. Similar to the itoa function in C. Populates $0 with "120", and $1 with the string conversion of %2. itoa $0,120 itoa $1,%2 NOEP convert a numeric value into a fullwidth character string itoa $VAR,NUM String variable for the fullwidth result 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. The numeric value of %4 is converted to a fullwidth string, which is then assigned to $0. itoa2 $0,%4 NOEP convert a string into a numeric atoi %VAR,STR Numeric result variable 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) Populates %0 with 123, and %3 with the number extracted from $0. atoi %0,"123" atoi %3,$0 NOEP find the length of a character string len %VAR,STR Length result variable Character string to measure Finds the length of the given character string. Sets %0 to the length of $0 len %0,$0 NOEP get a substring of the given character string mid $VAR,STR,NUM,NUM String variable to receive the substring Character string to extract from Starting index of the substring Number of (half-width) characters to extract Extracts a substring from the given character string. Use starting index 0 for the first character. Also, to get exactly 1 full-width character, specify 2 as the number of chars to extract. Extracts a substring of length %1 starting at index %0 from string $1, and assigns the result to $0. mid $0,$1,%0,%1 Grabs the first 5 characters of $1 and assigns the substring to $0. mid $0,$1,0,5 NOEP split a character string using the given delimiter split STR,STR,$VAR|%VAR,$VAR|%VAR[,...] Character string to split Delimiter (must be just one character) Result variable Splits the given string at each occurrence of the given delimiter, and assigns the resulting portions to the given variables.
Use this command to process the results returned by readfile. If a variable is repeated, its final result will be the last value portion assigned to it. (by eijipou)
If the string cannot be split (i.e. the delimiter never occurs), then numeric variables will be assigned the value 0 and string variables will receive the entire "split" string. (by senzogawa) Splits $0 at every occurrence of "/", assigning the results to $1, $2, %0, %1, and $3. mov $0,"あいうえお/かきくけこ/15/25/さしすせそ" split $0,"/",$1,$2,%0,%1,$3 ＄１＝$1 ; あいうえお ＄２＝$2 ; かきくけこ ％０＝%0 ; 15 ％１＝%1 ; 25 ＄３＝$3 ; さしすせそ \ NOEP find the sine of the given angle sin %VAR,NUM Numeric result variable Angle (in degrees) Acquires the trigonometric sine of the given angle, and returns the value multiplied by 1000. Assigns the sine of 90 degrees to %0. sin %0,90 ;%0=1000, since sin(90)=1 NOEP find the cosine of the given angle cos %VAR,NUM Numeric result variable Angle (in degrees) Acquires the trigonometric cosine of the given angle, and returns the value multiplied by 1000. Assigns the cosine of 60 degrees to %1. cos %1,60 ;%1=500, since cos(60)=0.5 NOEP find the tangent of the given angle tan %VAR,NUM Numeric result variable Angle (in degrees) Acquires the trigonometric tangent of the given angle, and returns the value multiplied by 1000. Please note that tan will return infinity if given values 90 and 270. Assigns the tangent of 45 degrees to %2. tan %2,45 ;%2=1000, since tan(45)=1 NOEP evaluate if a condition is true if CONDITION[{&&,&} CONDITION[...]] SENTENCE Relative operation, check instruction, or some other truth-value returning expression 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. If %0 equals 1, do a 1/2 second horizontal screen shake. if %0=1 quakex 2,500 ;basic conditional form 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 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 ':' NOEP evaluate if a condition is false notif CONDITION[{&&,&} CONDITION[...]] SENTENCE Relative operation, check instruction, or some other truth-value returning expression Command(s) to execute if the condition was False The commands following the if statement are executed if the conditional statement(s) evaluate false; if you want branch control in which a command executes if a conditional statement is true, use if.
The conditions compare numerical values, else you can employ fchk.
& and && are logical 'ands', and are equivalent to each another.

Conditions:
(numerical variable) {>,<,=,>=,<=,==,!=,<>} (numeric variable)
- or -
fchk (character string) If %0 is not equal to 1, do a 1/2 second horizontal screen shake. notif %0=1 quakex 2,500 NOEP compare character strings cmp %VAR,STR,STR Numeric variable for result of comparison Character string #1 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) NOEP check whether or not a image file has been loaded (and tagged) fchk 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. ld c,":a;test.bmp",1 if fchk ":a;test.bmp" ;returns true if fchk "test.bmp" ;same result NOEP check whether or not a label has been accessed lchk LABEL Label to confirm Like fchk, this command is used in if statement conditionals. It checks to see whether the given label has been used/accessed.
Any of the following are allowed syntax:
lchk *test
lchk "*test"
lchk $0 NOEP loop instruction for %VAR=NUM to NUM[ step NUM] Numeric variable used as counter Initial value for counter Ending value for counter 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. Looping %0 from 1 to 10, add each value of the counter to %1. for %0=1 to 10 add %1,%0 next NOEP end a loop next This ends a for block. Please refer to the documentation of for for more details. NOEP break out of a for loop 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. 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 NOEP initialize menu to display upon right-click rmenu STR,{skip,reset,save,load,lookback,windowerase}[,...] Right-click menu display string Right-click menu function name Defines a system menu to show upon right-click.
The character string is menu item text, and the function is picked from the list defined below.

SYSTEM MENU FUNCTION NAMES:
skip - same as "skip to next choice"
reset - reset program
resetdlg - same as reset? save - go to save menu
load - go to load menu
lookback - go to log mode
windowerase - remove text window
end - exit the program Display 3 elements in the right-click menu: "セーブ" for the Save menu function, "ロード" for the Load menu function, and "回想" for Log Mode. rmenu "セーブ",save,"ロード",load,"回想",lookback NOEP initialize window for right-click menu menusetwindow NUM,NUM,NUM,NUM,NUM,NUM,COLOR (Full-width) text font width Text font height Text spacing X Text spacing Y Boldface toggle (0=off/1=on) Drop shadow toggle (0=off/1=on) Window color Creates a menu dialog window.
This window displays above all other items in the screen when active.
From left to right, the arguments are: character font size x, character font size y, kerning x, kerning y, boldface (1 - yes; 0 - no), drop shadow (1 - yes; 0 - no); the final #rrggbb parameter is the window color. NOEP specify names to use for savefiles in right-click menu savename STR,STR,STR Save menu title Load menu title Savefile line heading Designates the display strings for savefiles.
From left to right, the strings are: title for the save menu, title for the load menu, and then the name of the save itself.
By default, these are "＜セーブ＞","＜ロード＞","しおり" -- note that these are all double-byte character strings. ONScripter-EN and PONScripter have the following for defaults: "Save", "Load", "Slot". NOEP designate the text colors for choices menuselectcolor COLOR,COLOR,COLOR Mouseover color Mouseoff color Empty savefile slot color This command sets the colors of the right-click menu when the right-click menu functionality is enabled. In order, the colors are the mouseover color, the mouseout color, and the "no savefile exists" color. NOEP specify right-click menu system sounds menuselectvoice STR,STR,STR,STR,STR,STR,STR Sound file that plays when a menu opens Sound file that plays at menu cancel Sound file that plays upon mouseover of a menu item Sound file that plays when a menu item is clicked Sound file that plays at an error Sound file that plays when 'Yes' option chosen Sound file that plays when 'No' option chosen Designates the WAV files that are played for menu choices, and other system sounds.

From left to right, the strings are: menu open, menu cancel, menu item mouseover, on click, forbidden operation, "yes" confirmation, "no" confirmation.

If any of these are set to "", no sound plays.
By default, all of these sounds are set to "". NOEP jump to Log Mode upon right-click rlookback Activate Log Mode by using a right click. NE set a routine to call upon right-click rgosub LABEL Destination to jump to upon right-click This sets a routine to call at right-clicks.
The given label will be called using a gosub, so that a return will go back to the waiting point where the right-click was detected. The systemcall command doesn't work if rgosub is defined (by BBS) NOEP ignore right-clicks roff Set default behavior of right-click as null/do nothing. NOEP toggle availability of right-click menu rmode NUM Right-click active toggle (0:off, 1:on) Toggles right-click functionality on (1) or off (0). NOEP specify button images for Log Mode lookbackbutton STR,STR,STR,STR Page-up active button image Page-up inactive button image Page-down active button image Page-down inactive button image Loads buttons for use in Log Mode.
By default, these are "uoncur.bmp","uoffcur.bmp","doncur.bmp","doffcur.bmp".
The images must be of the same size or else this command will fail.
Log mode buttons cannot be animated.
The button to enter log mode is located at the upper right of the text window. Its position cannot be changed once set, so please make sure you set it right the first time around. NOEP designate text color for Log Mode lookbackcolor COLOR Log Mode text color Sets the text color for Log Mode.
The color is an #rrggbb hex value, like that used in HTML. NOEP play a sound when paging through Log Mode lookbackvoice STR Paging sound filename Designates a WAV file to play back when the pageup/pagedown button is clicked in Log Mode. NOEP use sprites instead of the default Log Mode buttons lookbacksp NUM,NUM PageUp button sprite number PageDown button sprite number Uses the given sprites as lookback buttons instead of the defaults. Uses Sprites 2 and 3 as the Log Mode Pageup and Pagedown buttons. lookbacksp 2,3 NOEP set maximum number of pages to store for Log Mode maxkaisoupage NUM Maximum number of pages to store in backlog buffer Sets the maximum number of pages that may be stored for Log Mode. Allows access to only the previous 10 pages in Log Mode. maxkaisoupage 10 NOEP clear Log Mode buffer lookbackflush Flushes the Log Mode buffer. N stop accumulating Log Mode data lookbackon Stops collecting Log Mode data; data collection can be restarted with lookbackon. N begin accumulating Log Mode data lookbackon Turns on accumulation of Log Mode data; use this to return regular log buffering after turning it off with lookbackoff. NOEP enable 'stop at unread' in 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". NEP play WAV files even during Skip Mode mode_wave_demo Usually WAV files are not played during "skip to next choice" mode, but specifying this command will have them be played. ONScripter doesn't recognize this command, but plays WAV files during skip mode anyway. ONScripter-EN supports this command since ver.20090816 (as does PONScripter since ver.20100205) by playing WAV files during skips only if mode_wave_demo is used. (by Mion) NOEP turn off Skip Mode skipoff Exits both "skip to next choice" mode and "auto mode". Skip Mode can be enabled with "systemcall skip".
So, using defsub, you can create a "skipon" command with the follow code. (by senzogawa)
*skipon
systemcall skip
return Exits any Skip Mode that may have been active. skipoff NOEP toggle Skip Mode's 'stop at unread' setting kidokumode 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. NOEP enable file access logging 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. NOEP enable use of 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. NOEP enable label access logging labellog This command behaves somewhat like filelog, except in this case it keeps a record of labels.
Whenever a goto, gosub or similar command is called, a record of which label was called will be stored if labellog was specified. NOEP set the maximum number of saves allowed savenumber NUM Savefile capacity Change the limit on the number of save files. At most, this can be 20, and the default is 9.
If you are not careful to make sure that the save menu does not overflow the bottom of the screen (using menusetwindow), this command could cause the interpreter to hard crash. NE store save data in the designated folder savedir STR Name of directory where save data will be stored This specifies a folder to use for storing save data. When this command is used (in NScripter), only the file "envdata" will be stored in the same location as "nscr.exe".
Be sure the savedir exists beforehand. ONScripter-EN and PONScripter already store game & save data in a separate folder from the game; this location can be adjusted via the "-s" command line option.
This behavior is separate from the savedir command, which is used to specify a directory relative to the game/save folder (holding all but "envdata". (by Mion) Sets so that save data files will be stored in the folder "savedata". savedir "savedata" NOEP load game from the designated savefile loadgame NUM Savefile number Loads the save data corresponding to the given save number. This does not prompt for confirmation, so be careful.
This command gives no error indication if savefile cannot be loaded, and simply proceeds to the next command without stopping. NOEP save game in the designated savefile savegame NUM Savefile number Saves the game under the given save number. This does not ask for confirmation, so be careful. NOEP store a particular character string along with the savefile savegame2 NUM,STR Savefile number String to store with the save Stores a particular character string with each save file; otherwise, it works the same as savegame. Along with Save Game 12, this stores the string "８月５日　ヒロインＡルート" savegame2 12,"８月５日　ヒロインＡルート" Along with Save Game 12, this stores the string "Aug. 5 -Heroine A route-" savegame2 12,`Aug. 5 -Heroine A route-` NOE retrieve the string stored with a savefile using savegame2 getsavestr $VAR,NUM Result string variable Savefile number Retrieves the character string that was stored with a particular save number using savegame2. Gets the string stored with Save Game 12 by savegame2 and assigns it to $1. getsavestr $1,12 NOEP check whether or not a savefile exists savefileexist %VAR,NUM Result numeric variable (0: doesn't exist, 1: exists) Savefile number Returns 1 if the savefile exists, 0 if it does not. NOEP turn on Save Mode saveon Turns Save Mode back on (also see saveoff for more details). NOEP turn off Save Mode saveoff Turns Save Mode off.
This does not mean that you cannot save; it means that when you load, the position at which the player starts will be at the last place where saveon was set.
Why would you ever want to turn save mode off? When save mode is on, it records every sprite ever loaded into a log -- causing moderate to massive amounts of slowdown when you are attempting to do a fast animation. In these cases, you should definitely call saveoff before you start the animation, then call saveon once you've finished. NOEP set a routine to call immediately after loading a game loadgosub LABEL Subroutine to call upon game load Specifies a routine to call immediately after a game is loaded and its save state has been restored.
Please take care when scripting to be sure that all saveable points will work properly when restored with this loadgosub routine.
This command was created especially to handle games that use plugins for music reproduction. This command is necessary in NScr if a plugin is being used for music playback. Specifies that the script should call *loadlb whenever a game is loaded. loadgosub *loadlb N automatically save game status in savefile 999 when an error occurs 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. N disable (most) automatic save points 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. N update the save point savepoint Updates the save point.
Use this when the autosaveoff command is used in the define block.
Timing issues may slow down returns from data updates, for example when updating a save point after drawing over the entire screen, so please use common sense. N create a message box mesbox STR,STR Message to display Messagebox title Shows a message box.
The first string is the contents of the box, the second string is the title of said box. N create an OK/Cancel dialog box okcancelbox %VAR,STR,STR Result: 1 for OK, 0 for Cancel Message to display Dialog box title Shows a Windows OK/Cancel dialog box and retrieves user input. Creates an OK/Cancel dialog titled "セーブ確認" (Confirm Save) with the message "セーブします。" (About to Save). okcancelbox %0,"セーブします。","セーブ確認" N create a Yes/No dialog box yesnobox %VAR,STR,STR Result: 1 for Yes, 0 for No Message to display Dialog box title Shows a Windows Yes/No dialog box and retrieves user input. Creates Yes/No dialog titled "ロード確認" (Confirm Load) with the message "ロードしますか？" (Perform Load?). yesnobox %0,"ロードしますか？","ロード確認" N wait for player to give character input (method 1) inputstr $VAR,STR,NUM,NUM[,NUM,NUM,NUM,NUM] Input result string variable Message to display Maximum input length Force double-byte input (0: allow half-width, 1: full-width only) Window width (optional) Window height (optional) Input area width (optional) 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). N wait for player to give numeric input inputstr %VAR,STR[,NUM,NUM,NUM,NUM] Input result numeric variable Message to display Window width (optional) Window height (optional) Input area width (optional) 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). N wait for player to give character input (method 2) input $VAR,STR,STR,NUM,NUM Input result string variable Message to display Default input string Maximum input length 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. N create a text input window textfield $VAR,NUM,NUM,NUM,NUM,NUM,NUM,NUM String variable that stores both the default and input result strings Window top left X-coordinate Window top left Y-coordinate Window bottom right X-coordinate Window bottom right Y-coordinate Character width (single-byte) Character height Double-byte text (0: allow half-width, 1: full-width only) This creates a text input window on the screen (not a dialog box) and waits for input.
The prior contents of the given string variable will be used as the default text.
Input is returned by hitting the Escape, Tab or Enter keys, or by left-clicking on-screen outside the textfield area.
To see if the Tab key was pressed, use getret %0
If %0 is 0, then Tab was not pressed, but if %0 is 1 then the Tab key was pressed to return input. Produces a text input area within (100,50) to (320,70) that takes 10x20 (half-width) characters, with forced full-width input. textfield $0,100,50,320,70,10,20,1 NOEP retrieve the cursor coordinates at the last click clickpos %VAR,%VAR X-coordinate at last click Y-coordinate at last click Returns the position of the last click - the first variable is x, the second variable is y. NOEP perform a function as though called from the right-click menu systemcall NAME Menu function name Works identically to the system menu functions.
The available function names are similar to the ones used by rmenu:
SYSTEMCALL MENU FUNCTION NAMES:
skip - same as "skip to next choice"
reset - reset program
resetdlg - same as reset?
save - go to save menu
load - go to load menu
lookback - go to log mode
windowerase - remove text window
automode - automatically advance text at each clickwait (delay time set by automode_time)
rmenu - opens the right-click menu

If you use systemcall in routines like select/selgosub, then you'll end up with something not very different from the title menu.
(In that case, it would probably be better to temporarily toggle off right-click menu functionality through rmode.)

Calling systemcall rmenu has the same effect as calling the right-click menu itself.
You'd use this when you wanted right-click menu functionality during a button wait state. Once you exit this right-click menu, the interpreter continues its execution at the command after systemcall.
(This can leave the screen and the interpreter stack in an inconsistent state, so be careful when using this command.) NOEP check whether or not a file exists fileexist %VAR,STR Result for file check (1: exists, 0: not found) Filename Assigns 1 to the given variable if the file exists, 0 if not. This will also check within NSA archives. N delete a file fileremove STR Filename Deletes the given file. N check whether or not a label exists labelexist %VAR,LABEL Result for label check (1: exists, 0: not found) Label to check for Assigns 1 to the given variable if the label exists, 0 if not. Checks if "*message" routine exists, and calls it if so. labelexist %0,*message if %0==1 gosub *message N don't generate an error when an image or sound can't be loaded noloaderror The program won't fail with an error if a sound or image load command, such as ld or bgm, fails to load a file. NE minimize the game window minimizewindow Minimizes the game window. NOEP allow use of Auto Mode 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. NOEP specify delay time in Auto Mode when sounds aren't being played automode_time 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. NOEP set default volume for voices (dwave channel 0) defvoicevol NUM Default volume (0 - 100) Sets default volume for voices (DWAVE 0). Ranges from 0 to 100. Default value is 100. NOEP set default volume for SFX defsevol NUM Default volume (0 - 100) Sets default volume for sound effects (DWAVE 1+). Ranges from 0 to 100. Is 100 by default. NOEP set default volume for mp3 files (BGM channel) defmp3vol NUM Default volume (0 - 100) Sets the default volume for mp3s (BGM), from a range of 0-100. Is 100 by default. NE set default volume for BGM channel defbgmvol NUM Default volume (0 - 100) Sets the default volume for BGM, from a range of 0-100. Is 100 by default. NOEP use special mode created for "Saya ~Labyrinth of Immorality~" mode_saya A command mode written especially for the doujin game, "Saya ~Labyrinth of Immorality~". Once you specify this command, you enter: the legendary Saya Mode!
In Saya mode, when the text window disappears:

* Sprites 0-9 also disappear, regardless of whether they're flagged to be visible or not.
* Bars and numbers indicating status underneath the text window also disappear.

You would use this, for instance, when you had a parameter status window that you wanted to hide when the text window disappeared. NOEP allow use of Auto Mode created for "Gin'iro" mode_ext This is a command developed especially for the commercial software "Gin'iro". When you use this command, you can enter Auto Mode from the menu. It is similar in concept to the "skip to next choice" option, but displays characters much more slowly (with a delay defined by automode_time). This makes it almost like a mode in which the computer reads the text to you.

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

There are future plans to add more functionality to this command, and to make things conform to predefined syntaxes. NOEP set screen size to 800x600 ;mode800 Enables 800x600 screen mode (yes, the ';' in the beginning is necessary!). This command must be the first line in the script - even above *define. Even when this command is used, the text window is still sized as for 640x480. Therefore, you will need to adjust it with setwindow. Sets the game screen size to 800x600. ;mode800 *define NOEP set screen size to 400x300 ;mode400 Enables 400x300 screen mode. This command must be the first line in the script - even above *define. Even when this command is used, the text window is still sized as for 640x480. Therefore, you will need to adjust it with setwindow. Sets the game screen size to 400x300. ;mode400 *define NOEP set screen size to 320x240 ;mode320 Enables 320x240 screen mode. This command must be the first line in the script - even above *define. Even when this command is used, the text window is still sized as for 640x480. Therefore, you will need to adjust it with setwindow. Sets the game screen size to 320x240. ;mode320 *define NOEP change the starting number for global variables ';value'NUM Global variable start boundary (0 - 4000) If a script file has ";value500" as the first line, then this will set the starting number for global variables to 500.
To also change the window size mode, say to 800x600, use ";mode800,value500" as the first line of the script. If you use ";mode640,value500" as the first line of a script, then since ";mode640" is not a valid directive, the "value" setting will also be ignored. (by BBS) Sets the starting global variable number to 500. ;value500 *define EP give a name to use for an ONScr game save folder ';gameid' 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) Sets the game folder name to "ToHeart-Extra". ;gameid ToHeart-Extra N load compressed audio functionality via plugin/dll (can just use DirectSound instead) soundpressplgin STR Plugin specification Using this, you can designate a dll file with which to decode other kinds of compressed sound files that are not mp3s. The character string format is "plugin-name|3-char-file-extension". This specifies using "nbzplgin.dll" to open *.nbz sound files. soundpressplgin "nbzplgin.dll|nbz" N load compressed image functionality via plugin/dll spi STR Plugin specification Allows for utilization of image compression plugin dll's - image filetypes that are not supported in standard NScripter. The character string format is "plugin-dll-name|file-extension". This specifies using "jpgplgin.dll" to open *.jpg files, and "iflf2.spi" to open *.lf2 files. spi "jpgplgin.dll|jpg" spi "iflf2.spi|lf2" N use specified archive arc 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. This specifies using "scrunarc.dll" to open an "arc.sar" archive file. arc "arc.sar|scrunarc.dll" 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 NOEP enable NSA archive access nsa Allows for NSA archive mode. In this mode, resources such as BMPs may be read from nsa*.arc, located in the same directory as the executable itself. The nsa*.arc files themselves are generated by nsaarc.exe, which can be found in the NScr SDK.

Please note that you may consecutively name files as arc.nsa, arc1.nsa, arc2.nsa ... arc9.nsa, and for the purposes of the interpreter, they will all be considered as part of the same namespace - like one big archive. You may use this to quickly unpackage and repackage archives for testing. NOEP designate folder where NSA archives are located nsadir STR Directory to be read for NSA archives Sets the folder search path for nsa archives. By default, this is the same directory where the executable resides. NE add a directory to check for NSA archives addnsadir STR Directory to check for NSA archives Adds a directory to check for NSA archives. NOEP call a DLL exec_dll 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) Calls "execdll.dll" with the parameter string "テストですよー。". exec_dll "execdll.dll/テストですよー。" NOEP retrieve value returned from a DLL getret %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. NE create a layer setlayer NUM,NUM,STR Layer number Layer update interval (msec) DLL filename This registers a layer number for a particular plugin DLL.
Messages may be sent to the plugin via layermessage. At present, ONScripter-EN supports the following "plugin-based" layer effects (originally created by Takashi Toyama), via emulation: "hana.dll", "oldmovie.dll", and "snow.dll". (by Mion) NE send a message to a layer setlayer NUM,STR Layer number (defined using setlayer) Message to send to the layer An arbitrary character string is sent to the specified layer.
This command can be useful for achieving various effects within a layer.
To use this command, a layer plugin should export a function with this declaration:
BOOL Message(char *message, int *returnint, char *returnstr); NOEP change the version information versionstr STR,STR First line of version string Second line of version string Designates version strings to display in the "about" dialog. The first string is the first line, the second string is the second line. NOEP change the game window title caption STR String to use for the window title Sets the window title. NOEP retrieve the current year, month and date date %VAR,%VAR,%VAR Numeric variable for the retrieved year Numeric variable for the retrieved month Numeric variable for the retrieved date Retrieves the current date, in numeric values. NOEP retrieve the current hour, minute and second time %VAR,%VAR,%VAR Numeric variable for the retrieved hour Numeric variable for the retrieved minute Numeric variable for the retrieved second Retrieves the current time. NOEP retrieve the date and time of the given savefile savetime NUM,%VAR,%VAR,%VAR,%VAR Savefile number Numeric variable for the save month Numeric variable for the save date Numeric variable for the save hour Numeric variable for the save minute Gets the month, day, hour of the day, and minutes of the hour in which a particular save was recorded.
If the save file does not exist, then the %month parameter is set to 0. Retrieves the save time and date of savefile 3, or else explains that the savefile was not found. savetime 3,%0,%1,%2,%3 if %0=0 goto *non ;save found セーブ３番は%0月%1日%2時%3分@ end *non ;save not found セーブ３番は存在しない。@ end NOEP get the version number of the current NScripter build getversion %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. N get the area of the window client getwindowsize %VAR,%VAR Numeric variable for window width 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. Assign the screen window width to %0 and height to %1. getwindowsize %0,%1 N read from the registry getreg $VAR,STR,STR String variable for the registry key/value result A registry key A registry variable Opens the Windows registry and queries for a variable.
Will search only in HKEY_CURRENT_USER. getreg $0,"software\leaf\toheart","datadir" NOEP read from an ini file getini $VAR,STR,STR,STR String variable for the registry key/value result An INI filename INI section name INI key name Opens an ini file and reads a variable. N read file contents into a string variable readfile $VAR,STR String variable for the file read result A text filename Reads the contents of the given file into the given string variable. Note that this also reads CRLF (\x0d\x0a) line endings; when writing multiple lines to a file that will be processed with readfile, these ending bytes must be skipped since relative operators cannot process CR or LF.
Also, since calling readfile does not affect the file log, fchk cannot be used to determine if the file was read. Reads the contents of "file.txt" into $0. readfile $0,"file.txt" N erase a menubar item killmenu 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. N clear menubar for definition of a custom menu resetmenu Declares creation of a custom menubar. Add menu items after this command using insertmenu. N add a menubar menu option insertmenu STR,NAME[,NUM] Character string displayed for menu item Menu function code Submenu level (optional) Adds a menubar item. It always adds at the head position. 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 "ＯＮ",WAVEON,2 insertmenu "ＯＦＦ",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 "ＣＤ－ＤＡ",SUB,1 insertmenu "ＯＮ",CDON,2 insertmenu "ＯＦＦ",CDOFF,2 insertmenu "クリック設定",SUB,1 insertmenu "普通",CLICKDEF,2 insertmenu "ページごと",CLICKPAGE,2 N remove the Windows menubar from NScripter deletemenu Completely removes the Windows menubar from NScripter. NOEP designate text display speeds selectable via the menubar defaultspeed NUM,NUM,NUM Slow default text display speed Medium default text display speed 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. Sets the default text speeds as 50 for "Slow", 20 for "Medium", and 0 for "Fast". defaultspeed 50,20,0 NOEP use a text display speed provided via defaultspeed !sd Sets text display to the current default speed. You may set the three possible default speeds with the defaultspeed command. NOEP enter fullscreen mode menu_full Enters fullscreen mode. NOEP enter windowed mode menu_window Enters windowed mode. NE retrieve whether or not fullscreen mode is active isfull %VAR Result numeric variable (0: windowed, 1: full-screen) Retrieves the current full-screen status (full or windowed). 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 NE enter single-page text display mode menu_click_page Enters single-page text display mode, as provided via the 表示形式(Display Format) menubar item. This and menu_click_def affect what *ONScripter provides as "page-at-once" mode, using 'o' keystroke toggle. (by Mion) NE enter default text display mode menu_click_def Enters default text display (not single-page) mode; see menu_click_page. N display the volume setting dialog window menu_dwavvol Displays the volume change dialog box. E enable main volume menu_waveon Enables main volume (turning off volume mute, if set). E disable (mute) main volume menu_waveoff Disables (or mutes) main volume. NOEP a label that interacts with the csel command *customsel Jumps to this label whenever a csel command is executed.
Code for handling a custom select display follows this label. 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 NOEP give choices to present via system customization csel STR,LABEL[,STR,LABEL[,...]] Choice string to display 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. Sets up a customized selection where "Choice１" goes to *s1, "Choice２" goes to *s2, and "Choice３" goes to *s3. csel "Choice１",*s1,"Choice２",*s2,"Choice３",*s3 NOEP create custom buttons for choice text cselbtn NUM,NUM,NUM,NUM Choice index number (starting at 0) Top-left X-coordinate 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) Displays the first choice string as button 500 at position (%1,%2). cselbtn 0,500,%1,%2 NOEP jump to a label created by csel cselgoto NUM Choice index number (starting at 0) Jumps to the label of the given choice index set by csel. Jumps to the choice label indexed by the number in %0. cselgoto %0 NOEP get the total number of csel choices getcselnum %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) Assigns the total number of csel choices to %0. getcselnum %0 NOEP get the character string of a csel choice getcselstr $VAR,NUM String variable for choice Index number of the desired choice string Acquires a character string given as a csel choice. Grabs the 0th (first) choice string provided by csel and assigns it to $0. getcselstr $0,0 N returns whether or not the next command is csel nextcsel %VAR Numeric result variable (1: next cmd is csel, 0: not csel Returns 1 if the next command is csel, 0 otherwise. This may be useful in displaying choices without erasing text. NOEP enter click wait state within a *customsel selectbtnwait %VAR Numeric variable for button number Waits for a click during a *customsel routine. Waits for a click and assigns the clicked button number to %0. selectbtnwait %0 NOEP define a label for handling system customization during click wait states textgosub LABEL Label called at clickwaits Defines a label to jump to at click waits for system customization. The routine named by this label must handle all system menus, cursors, buttons, and user input during these wait states. Sets to jump to "*text_1b" at clickwaits. textgosub *text_lb NOEP enter click wait state within a custom wait routine textbtnwait %VAR Numeric variable for button number Waits for a click during a custom wait routine, as defined by textgosub. Waits for a click and assigns the clicked button number to %0. textbtnwait %0 NE retrieve skipoff keystrokes at textbtnwait 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. 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 NE return on mouseover of buttons at a button wait getmouseover getmouseover NUM,NUM Minimum button number to return mouseovers 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. This will wait and return if any of buttons 0-9 are moused over. btndef clear getmouseover 0,9 btnwait %0 NE check for a specified keypress checkkey %VAR,STR Numeric variable (1: got specified keypress, 0: didn't) 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 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" NOEP remove text for a page-wait condition texec Does text removal for a page-wait (within a textgosub routine). Also does line-feeds after regular clickwaits as applicable. N remove text for a page-wait condition (method 2) texec2 Similar to texec, except that it does not remove text immediately - only once the following line is displayed.
(This is used to prevent erasing text at choices.) Available since 2008/08/10 release NOEP get current position of text cursor getcursorpos %VAR,%VAR Variable for the text-window X-coordinate of the text cursor 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. Stores the text cursor position in (%0,%1). getcursorpos %0,%1 NE get top-left pixel coordinates of the last text character getcursorpos2 %VAR,%VAR Variable for the top-left pixel X-coordinate of the text character 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. Stores the top-left pixel coordinates of the last text character in (%0,%1). getcursorpos2 %0,%1 NOEP get current progress mode isskip %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) NOEP retrieve whether or not in a new page clickwait ispage %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. Retrieves the clickwait type and assigns it to %0. ispage %0 NOEP create a user-defined command name defsub 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. 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 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 NOEP retrieve the parameters given to a user-defined command getparam %VAR|$VAR|s%VAR|i%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. N replace default NScripter functionality with a Lua callback luacall NAME System function name (tag, text0, text, animation, close, end, savepoint, save, load) Many default NScripter system functions can now be replaced with Lua callbacks.
A Lua function could be created to handle text display using sprites, for example, as well as other sorts of system customization.
The specified character string need not be enclosed by double-quotes, and is case-insensitive.
The applicable Lua-side function must be named NSCALL_(sysfunc-name) and use the defined function argument structure for that particular call. luacall animation callback stub added in (Japanese) onscripter 20090510-exp. (by Mion) Specifies that Lua function NSCALL_text will be called for text display handling. luacall text N create a user-defined instruction that calls a Lua function luasub NAME Instruction name Defines a new command with the given name and ties it to a Lua function NSCOM_(cmd-name).
Any time the command is executed within the script, that Lua function will be called.
A Lua function registered with luasub must be void - no arguments or return values. Existing NScr commands may be replaced using luasub!
For example, luasub bg will cause Lua function NSCOM_bg() to be called instead of the standard bg command.
As with defsub, you can use _bg to call the original bg instruction. luasub stub added in (Japanese) onscripter 20090510-exp. (by Mion) Specifies that Lua function NSCOM_func will be called when the "func" command is executed. luasub func NOEP grab a screenshot getscreenshot NUM,NUM Screenshot image width 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. Grabs a screenshot of size 160x120. getscreenshot 160,120 NOEP save a screenshot image savescreenshot STR Screenshot filename Saves a screenshot collected via getscreenshot.
This also deletes the screenshot image from memory; use savescreenshot2 instead if you need to reuse the screenshot image. Saves the last collected screenshot as "thumb01.bmp". savescreenshot "thumb01.bmp" NOEP save a screenshot image savescreenshot2 STR Screenshot filename Saves a screenshot collected via getscreenshot as the given filename.
This does not delete the screenshot image from memory, so please use deletescreenshot to remove it from memory when finished. NEP remove a screenshot image from memory deletescreenshot Removes a screenshot image from memory.
This command is meant to be used with savescreenshot2. NE set an area for detecting mouse cursor entry btnarea 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) Sets from Y=400 to the bottom of the screen as a mouseover area for btnwait. btndef clear btnarea -400 NOEP set to return from button command while mouse button is pressed btndown 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). Sets to return from btnwait while a mouse button is pressed. btndown 1 NOEP return whether or not the mouse button is pressed isdown %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. This prints a line of "０"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 "０/":goto *onlclick puttext "" goto *waitloop NOEP retrieve mouse cursor position getmousepos %VAR,%VAR result numeric variable for mouse cursor X-coordinate 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. Assign the current mouse cursor coordinates to %0 and %1. getmousepos %0,%1 NOEP set the Spacebar to work the same as a left-click spclclk Use this between btndef and btnwait commands.
This will cause a wait command to give the same return value on a pressed Spacebar as for a left-click in the same situation. NOEP have button commands detect mouse wheel movement usewheel Sets btnwait commands to detect mouse wheel movement.
The wait command will return -2 on wheel up, -3 on wheel down.
Please note that, when usewheel is in effect, a button wait timeout (set by btntime) will return -5 instead of the usual -2. NOEP have button commands detect Esc and Spacebar keypresses useescspc Sets btnwait commands to detect when the Esc key or Spacebar is pressed.
The wait command will return -10 on Esc, -11 on Space. NOEP have button commands detect left/right/up/down arrow keys 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. NOEP have button commands detect Enter key getenter Use this between btndef and btnwait commands.
The wait command will return -19 when the Enter key is pressed. NOEP have button commands detect Tab key gettab Use this between btndef and btnwait commands.
The wait command will return -20 when the Tab key is pressed. NOEP have button commands detect Function keys getfunction Use this between btndef and btnwait commands.
The wait command will return -21 to -32 for presses of keys F1 to F12. NOEP have button commands detect PageUp/PageDown keys getpage Use this between btndef and btnwait commands.
The wait command will return -12 on PageUp keypress and -13 on PageDown. NOEP have button commands detect Insert key getinsert Use this between btndef and btnwait commands.
The wait command will return -50 when the Insert key is pressed. NOEP have button commands detect Z/X/C keys getzxc Use this between btndef and btnwait commands.
The wait command will return -51 on Z keypress, -52 on X, and -53 on C. NE detect middle-button mouse clicks getmclick Use this between btndef and btnwait commands, like with getfunction.
The wait command will return -70 if the middle mouse button is clicked. NOE produce ruby text '('STR'/'STR')' Main text to show ruby text above 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). 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 ルビ機能の(暫定仕様/ざんていしよう)です。@ ｒｕｂｙｏｎ時、(文字/もじ)は(下詰/したづめ)で表示されます。@ (縦/たて)の(字間/じかん)を、ルビが入る分とって下さい。@ 「(承/うけたまわ)」る、とか、「(論理的/ロジカル)」みたいに、文字幅をあわせようとする機能がついてます。 ルビは折り返し改行されませんのでご注意ください。\ end 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 NOEP turn off ruby mode rubyoff Turns off ruby mode, thereby disallowing ruby text. NOEP enter ruby mode rubyon [NUM,NUM[,STR]] Ruby char width (default: half of main text width) Ruby char height (default: half of main text height) Ruby text font name Turns on ruby mode. Enters ruby mode, using the set text font and half the set text sizes for displaying ruby text. rubyon Enters ruby mode, using the set text font, width 10, and height 8 for displaying ruby text. (It is probably best not to use ruby text bigger than 13x13, for anti-aliasing purposes.) rubyon 10,8 Enters ruby mode, using width 14, height 12, and Japanese font "MS Gothic" for displaying ruby text. rubyon 14,12,"ＭＳ ゴシック" NE enter this ruby mode only when ruby text appears rubyon2 NUM,NUM Ruby char width Ruby char height This changes to ruby mode, but only when ruby appears in the current line. (Assumed to be used for quick-display modes; will also allow ruby text in strsp commands.) Please note that text may be shifted to make room for ruby text. Still not clear to me what this command's documentation means; for now, ONScr-EN recognizes this command but does no special handling. (by Mion) NOEP send images created via demo draw commands to the screen 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. 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 NOEP paint the screen black drawclear Paints over the entire screen with the color black.
Must be followed by the draw command. NOEP paint over the screen with a specific color drawfill NUM,NUM,NUM Red component of RGB color (0-255) Green component of RGB color (0-255) 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. Paints over the screen with color #FF0080. drawfill 255,0,128 NOEP draw the background to the screen 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. NOEP draw the background to the screen in a special manner drawbg2 NUM,NUM,NUM,NUM,NUM Center X-coordinate Center Y-coordinate Width scaling factor (%) Height scaling factor (%) 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. 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 NOEP draw the text window 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. NOEP draw a sprite drawsp NUM,NUM,NUM,NUM,NUM Sprite number Cell number (of sprite) Opacity (0-255) Top-left X-coordinate 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. Draw Sprite 2, Cell 1 with top-left at (20,40) and half-transparency (128). drawsp 2,1,128,20,40 NOEP draw a sprite (scaled and rotated) drawsp2 NUM,NUM,NUM,NUM,NUM,NUM,NUM,NUM Sprite number Cell number (of sprite) Opacity (0-255) Center X-coordinate Center Y-coordinate Width scaling factor (%) Height scaling factor (%) 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. 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 NOEP draw a sprite with linear transformation drawsp3 NUM,NUM,NUM,NUM,NUM,NUM,NUM,NUM,NUM Sprite number Cell number (of sprite) Opacity (0-255) Top-left X-coordinate Top-left Y-coordinate Matrix top-left coefficient Matrix top-right coefficient Matrix bottom-left coefficient 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. 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 NOEP check whether a backlog page is available checkpage %VAR,NUM Result numeric variable 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. Set %5 based on whether or not the last page backlog is available. checkpage %5,1 NOEP get the character string for a backlog page getlog $VAR,NUM Result variable for backlog string 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. Sets $0 to the backlog string from %5 pages back getlog $0,%5 NOEP create a sprite from backlog text logsp NUM,STR,NUM,NUM[,COLOR[,COLOR[,...]]] Sprite number Text string (provided by getlog) Top-left X-coordinate Top-left Y-coordinate Log Text color (default: #FFFFFF) Log Text sprite additional cell color (optional) Creates a sprite from backlog text retrieved via getlog, positioned at the given coordinates.
If no color is specified, the sprite text will be white (#FFFFFF). If only one color is specified, then the sprite will have just one cell - provide additional colors if you need more cells, like for use as a button. Creates Sprite 8 from backlog text in $0, displayed at (60,90) logsp 8,$0,60,90 Creates Sprite 8 from backlog text in $0, displayed at (60,90), with color #FFFF88 logsp 8,$0,60,90,#FFFF88 Creates Sprite 8 from backlog text in $0, displayed at (60,90), with Cell 0 of color #888888 and Cell 1 of color #FFFF88 logsp 8,$0,60,90,#888888,#FFFF88 NOEP create a sprite from backlog text with custom text size logsp2 NUM,STR,NUM,NUM,NUM,NUM,NUM,NUM[,COLOR[,COLOR[,...]]] Sprite number Text string (provided by getlog) Top-left X-coordinate Top-left Y-coordinate Text font width Text font height Text spacing X Text spacing Y Log Text color (default: #FFFFFF) Log Text sprite additional cell color (optional) Same as logsp, but allows specifying the text character size. Creates Sprite 2 from backlog text in $0 with fullwidth char size 17x17, no horizontal spacing, and 1 pixel vertical spacing, displayed at (150,20) logsp2 2,$0,150,20,17,17,0,1 N get the character string for a backlog page (for use with strsp) getlogtext $VAR,NUM Result variable for backlog string 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. NOEP get the last pretext tag of a backlog page gettaglog $VAR,NUM Result variable for backlog string 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. NOEP hide text while leaving the text window visible texthide Hides the textwindow text, while leaving the window itself in place.
This is important for customized Log Mode display. NOEP reshow text hidden with texthide textshow Redisplays text that had been hidden with texthide. NOEP set a routine to jump to just before text display pretextgosub LABEL Label to jump to before a text command Sets a subroutine to jump to immediately before a display text command.
If this command is used, a script can use a "tag", or data enclosed within square brackets [], immediately before any line of text.
For example, in the following code, the [太郎/0001.wav] is a tag:
[太郎/0001.wav]テスト用の文章です。 Specifies that execution will jump to the *pretext_lb subroutine before each line of text pretextgosub *pretext_lb Example pretextgosub routine pretextgosub *pretext_lb *pretext_lb dwavestop 0 gettag $0,$1 ;assuming first item is person name, second is voice dialog file if $0="" indent 0:goto *next_tag mov $2,$0 add $2,"/" puttext $2 ;this displays "(Name)" right before the actual text ;the "/" is to keep puttext from adding a newline indent 3 ;indents text for character dialog *next_tag if $1="" return dwave 0,$1 ;play the voice file return NOEP specify tag data available to a pretextgosub routine '['STR']' Tag data elements, delimited by "/" Specifies tag data accessible to gettag within a pretextgosub routine, called immediately before the following text is displayed. This calls a pretextgosub routine before "「太郎の台詞」" is displayed, where gettag will extract "太郎" and "0001.wav". [太郎/0001.wav]「太郎の台詞」 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.` NOEP use within a pretextgosub routine to get tag data gettag $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. Processes a pretext tag, assigning the first two elements to $0 and $1. gettag $0,$1 NOEP when linebreaking, indent the next line by the given amount indent 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. Indent continuing lines by 2 (fullwidth) spaces indent 2 NOE only process pretext tags at the start of a page pagetag A pretextgosub-enabled script will only check for [] pretext tags at the start of a page, not at the start of every line (or text command). NOEP allow use of 【】 as pretext tag brackets zenkakko Enables use of 【】 (fullwidth black lenticular brackets) for pretext tag specifications, in addition to the standard [] brackets. This feature appears to be unsupported in the latest release (ver2.95), as NScr crashes when it reaches the 【】. Seems to work fine up through ver2.82. (by senzogawa)
Note that, although the brackets may be fullwidth, tag elements are still separated by standard / slashes. Uses fullwidth brackets for pretext tag specification. *define pretextgosub *pretextproc zenkakko game *start 【名前/音声】「せりふ」 click end *pretextproc gettag $0,$1 mesbox $0,$1 ; 題名が"音声"、本文が"名前"のダイアログを表示 return N split a BMP file into multiple pieces while preserving the original bmpcut STR,NUM,NUM Image filename Number of horizontal pieces (num. of horiz. cuts + 1) 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. Cuts "test.bmp" into three pieces horizontally and in half vertically. bmpcut "test.bmp",3,2 N generate an NScripter alpha image bw2a 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. Generates an NScr-style alpha image from "test_w.bmp" and "test_b.bmp". bw2a "test" N generate an NScripter alpha image bw2a3 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. Generates an NScr-style alpha image from "w\test.bmp" and "b\test.bmp". bw2a3 "test.bmp" N glue image files together chainbmp 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". N create a dummy image file createdummy 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) Creates a dummy image file called "test.bmp". createdummy "test.bmp" N log debug messages debuglog NUM Debug logging flag (0: off, 1: on) If enabled, saves the message displayed in the debug window to "debuglog.txt". NEP opens an external program, file, or URL via Explorer shell STR Name of external file (or URL) Executes the given file via Explorer, using the ShellExecute API.
Note that shell execution is asynchronous with the game engine.

ONScripter-EN supports the shell command in Windows builds, and has basic support in Mac and Linux for using it to open a URL in the default web browser. N execute an external program winexec STR,NUM Execution file name Synchronization flag (0: asynchronous, !=0: synchronous) Executes the given external program using the WinExec API.
If NScr is in full-screen mode, the call to WinExec will use display option SW_MAXIMIZE, while in windowed mode, it will use SW_SHOWNORMAL.
For any sync-flag value other than 0, the external program will run synchronously with NScr.
The executed program will send WM_USER+10 to the NScripter window if it restarted, and WM_USER+20 if the program ended.
This command is used to launch a demo program in "Dolls Antique". N open a CSV file csvopen STR,STR CSV file name 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) Opens "test.csv" for reading. csvopen "test.csv","r" Opens "angou.csv" for encrypted writing. csvopen "angou.csv","wc" N read data from an open CSV file csvread %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. 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 N write data to an open CSV file csvwrite STR|NUM[,...] numeric or string value to write (For use in write mode only)
Writes data items to a CSV file, in the specified order. Writes 4 data items to a CSV file: 12, "test", %1, and $2. csvwrite 12,"test",%1,$2 N detect whether or not at the end of an open CSV file csveof %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. Sets the value of %1 depending on the end status of the CSV file. csveof %1 N close an open CSV file csvclose Closes an open CSV file. Please use this command when finished with the file; otherwise it will remain open. NE set a text button '<'[NUM]STR'>' Textbutton number, must be nonnegative (optional) Textbutton display text A character string enclosed by '<' and '>' is converted into a text button. A textbutton numbered 3 `This is a `<3`textbutton`>`.@ NE set textbutton colors linkcolor COLOR,COLOR Textbutton standard color Textbutton mouseover color Sets the button colors for textbuttons.
The default colors are yellow and cyan. Sets the standard textbutton color to #FFFF88 and the mouseover color to #88FF88. linkcolor #FFFF88,#88FF88 NE specify starting number for unnumbered textbuttons textbtnstart NUM Starting number for unnumbered textbuttons (default: 1) Specifies the starting number for unnumbered textbuttons; 1 is the default value. Sets the starting number for unnumbered textbuttons to 3. textbtnstart 3 NE retrieve the text of a particular textbutton gettextbtnstr $VAR,NUM Result string variable Textbutton number Retrieves the text of the textbutton with the given number.
Returns a value of "" if the textbutton doesn't exist. Gets the text of textbutton number 12 and assigns it to $0. gettextbtnstr $0,12 NE clear a pressed textbutton erasetextbtn After exiting a button wait, if a textbutton was pressed, then this command will set the textbutton back to its original color. NE create a complex textbutton (similar to exbtn) textexbtn NUM,STR Textbutton number Sprite control string Adds complex behavior to a textbutton, in much the same manner as exbtn. NE inactivate textbuttons textbtnoff Textbuttons are usually active during a btnwait.
Using textbtnoff between btndef and btnwait commands will turn off text buttons during the wait.
This can be useful if, for example, textbuttons need to be off while other buttons are processed. Inactivates buttons and textbuttons before waiting for user input. btndef clear textbtnoff textbtnwait %0 NOEP load an extended sprite into memory lsp2 NUM,STR,NUM,NUM,NUM,NUM,NUM[,NUM] Extended-sprite number (0 - 255) Image filename or sprite processing string Center X-coordinate Center Y-coordinate Scaling factor X (%) Scaling factor Y (%) Rotation angle (degrees, counterclockwise) Opacity value (optional, default 255) Loads an extended sprite. Extended sprites add rotation about center and horizontal/vertical scaling to the existing sprite elements of position and opacity; it's also possible to flip images with the use of negative scale factors.
Like lsp, lsp2 loads images using the set display transparency mode.
The scaling factors are percentages; also note that providing a negative scaling factor will reverse the direction of the image. The lsp2 command does not correspond to current animation Loads and displays the image "test.bmp" without transparency, centered at (320,240), expanded to 200% vertically, and rotated 36 degrees counterclockwise. lsp2 0,":c;test.bmp",320,240,100,200,36 NOEP load an extended sprite into memory (hidden) lsph2 NUM,STR,NUM,NUM,NUM,NUM,NUM[,NUM] Extended-sprite number (0 - 255) Image filename or sprite processing string Center X-coordinate Center Y-coordinate Scaling factor X (%) Scaling factor Y (%) Rotation angle (degrees, counterclockwise) Opacity value (optional, default 255) Loads an extended sprite in a hidden state.
The only difference between lsp2 and lsph2 is the beginning condition of the extended sprite - lsp2 displays the sprite, while lsph2 keeps the sprite hidden (which may later be displayed with vsp2). NE load an extended sprite using additive composition lsp2add NUM,STR,NUM,NUM,NUM,NUM,NUM[,NUM] Extended-sprite number (0 - 255) Image filename or sprite processing string Center X-coordinate Center Y-coordinate Scaling factor X (%) Scaling factor Y (%) Rotation angle (degrees, counterclockwise) Opacity value (optional, default 255) Loads an extended sprite using additive composition.
lsp2add uses additive blending for display, but otherwise it works the same as lsp2. Loads the image "test.bmp" and displays without transparency using additive blending, centered at (320,240), expanded to 200% vertically, and rotated 36 degrees counterclockwise. lsp2add 0,":c;test.bmp",320,240,100,200,36 NE load an extended sprite using additive composition (hidden) lsph2add NUM,STR,NUM,NUM,NUM,NUM,NUM[,NUM] Extended-sprite number (0 - 255) Image filename or sprite processing string Center X-coordinate Center Y-coordinate Scaling factor X (%) Scaling factor Y (%) Rotation angle (degrees, counterclockwise) Opacity value (optional, default 255) Loads an extended sprite using additive composition, in a hidden starting state.
The only difference between lsp2add and lsph2add is the beginning condition of the extended sprite - lsp2add displays the sprite, while lsph2add keeps the sprite hidden (which may later be displayed with vsp2). NE load an extended sprite using subtractive composition lsp2add NUM,STR,NUM,NUM,NUM,NUM,NUM[,NUM] Extended-sprite number (0 - 255) Image filename or sprite processing string Center X-coordinate Center Y-coordinate Scaling factor X (%) Scaling factor Y (%) Rotation angle (degrees, counterclockwise) Opacity value (optional, default 255) Loads an extended sprite using subtractive composition.
lsp2sub uses subtractive blending for display, but otherwise it works the same as lsp2. Loads the image "test.bmp" and displays without transparency using subtractive blending, centered at (320,240), expanded to 200% vertically, and rotated 36 degrees counterclockwise. lsp2sub 0,":c;test.bmp",320,240,100,200,36 NE load an extended sprite using subtractive composition (hidden) lsph2add NUM,STR,NUM,NUM,NUM,NUM,NUM[,NUM] Extended-sprite number (0 - 255) Image filename or sprite processing string Center X-coordinate Center Y-coordinate Scaling factor X (%) Scaling factor Y (%) Rotation angle (degrees, counterclockwise) Opacity value (optional, default 255) Loads an extended sprite using subtractive composition, in a hidden starting state.
The only difference between lsp2sub and lsph2sub is the beginning condition of the extended sprite - lsp2sub displays the sprite, while lsph2sub keeps the sprite hidden (which may later be displayed with vsp2). NOEP delete extended sprite from memory csp2 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. NOEP toggle display of a loaded extended sprite vsp2 NUM,NUM Extended-sprite number visibility flag (0: not visible, 1: visible) Toggles display of specified extended sprite. 0 is off, 1 is on. NOEP change extended sprite position (relative) msp2 NUM,NUM,NUM,NUM,NUM,NUM[,NUM] Extended-sprite number X-coordinate offset Y-coordinate offset X scaling factor offset Y scaling factor offset Rotation angle offset Opacity offset Moves the extended sprite of the designated number, adjusting its position, scale, rotation and opacity relative to their current values. Takes Extended-Sprite 0 and moves it 10 pixels right and 20 pixels down, while decreasing its X-scale factor by 10, increasing its Y-scale factor by 10, and adding 5 degrees to its rotation. msp2 0,10,20,-10,10,5 NOEP change extended sprite position (absolute) amsp2 NUM,NUM,NUM,NUM,NUM,NUM[,NUM] Extended-sprite number (0 - 255) Center X-coordinate Center Y-coordinate Scaling factor X (%) Scaling factor Y (%) Rotation angle (degrees, counterclockwise) 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. 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 NOEP hide all extended sprites at the same time allsp2hide Hides all extended sprites at the same time. (Works essentially the same as allsphide.) NOEP redisplay extended sprites hidden with allsp2hide allsp2resume Redisplays the extended sprites that were hidden by allsp2hide. (Works essentially the same as allspresume.) N clear button definitions bclear Clears defined buttons. The same as btndef clear? (by Mion) N create a button from a sprite bsp NUM[,STR,STR,STR] Sprite number Sprite control string for mouseoff Sprite control string for mouseover 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. Creates a button from Sprite 1. bsp 1 Creates a button from Sprite 2, setting sprite control strings for mouseoff, mouseover, and mousepress. bsp 2,"P3,0","P3,1","P4,1" N specify behavior for when no sprite button is moused over bdef 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. Sets to hide Sprite 0 whenever none of the sprite buttons are moused over. bdef "C0" N specify button processing timeout duration btime NUM[,NUM] Timeout duration (ms) 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. Sets button timeout to 2 seconds. btime 2000 Sets button timeout to 1 second for after voices have finished. btime 1000,1 N execute button processing bexec $VAR[,%VAR] Input result 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. Executes button processing, storing input results in $0 and %0. bexec $0,%0 N return cursor key input during 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. N return from button processing while button is pressed 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. N ignore transparent areas during button processing btrans Executing btrans after bclear and before bexecwill cause button processing to treat transparent areas of sprite buttons as outside the respective buttons. OEP enter single-byte text mode ` 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) 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 E set preferred text language language {english/japanese} english: prefer English, japanese: prefer Japanese This sets the preferred text display language in ONScripter-EN, more-or-less replacing the FORCE_1BYTE_CHAR compilation option.
The right-click menu will use the preferred language for display messages, and text display will take preferred language, kinsoku settings, and whether a chunk of text contains single-byte and/or double-byte characters into account when performing linebreaks.
This command can be used within either the define or program block, and may be set by default from the command line or depending on the executable filename (i.e. "onscripter-en.exe" is assumed to prefer English).

Note that ENABLE_1BYTE_CHAR must be set at ONScripter compile time to be able to use language english. Sets preferred language to Japanese. language japanese P provide a numeric literal in hexadecimal format '0x'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. Defines a numeric alias using hexadecimal. numalias ascii_slash,0x2F P enter ponscripter text mode ^ 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"). P set a ponscripter formatting tag region '~'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.)
cNUMselect the font in slot NUM (0-7)
dselect the default font style (same as c0)
rdisable italics (default)
itoggle italics
tdisable bold (default)
btoggle bold
fselect the 'text' face (default)
sselect the 'display' face

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

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

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

Displays the text "Hello there" using font style 1. puttext ^~c1~Hello there^ 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.\ 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~ P map a font file to a ponscripter font slot pmapfont NUM,STR[,STR] Font slot (0-7) Font filename Font metrics file (Type 1 fonts only) Maps a font file to the given font slot.
For TrueType and OpenType fonts, the font file should be of type ".ttf" or ".otf"; for Type 1 fonts, the font file should be of type ".pfa" or ".pfb", with the metrics option providing the corresponding ".afm" file.

Filenames are relative to the game's data path. If a file is not found there, it is then sought within a "fonts" subdirectory of the data path, then in the game's archive, and then in the game binary itself (in case the font has been embedded).
As a last resort, and for compatibility, Ponscripter checks for a file named "default.ttf" in the game's data path.

The eight font slots are intended to represent two typefaces (a text face and a display face), each with regular, italic, bold, and bold-italic styles, as follows:
slot 0 - text face, regular font
slot 1 - text face, italics font
slot 2 - text face, bold font
slot 3 - text face, bold-italic font
slot 4 - display face, regular font
slot 5 - display face, italics font
slot 6 - display face, bold font
slot 7 - display face, bold-italic font
You can, of course, assign fonts however you like, but following this convention permits straightforward use of mnemonic formatting tags.

Note that mapping fonts in this way is optional - a slot that has not had a font assigned to it via pmapfont will use the default filename "faceN.ttf", where N is the slot number. Maps font slot 0 to "myprettyfont.ttf". pmapfont 0,"myprettyfont.ttf" P configure ponscripter text rendering prendering {none|full|light},{integer|float}[,{light|normal}] Hinting (either none, full, or light) Positioning (either integer or float) Optional Freetype rendering mode (light or normal) Configures the Freetype text rendering mode.

Hinting can be one of the following:
none - no hinting (default)
full - Freetype hinting
light - Light hinting
The optimum settings depend on the fonts in use. In general, Freetype hinting makes TrueType fonts look hideous, but it does sometimes help with Type 1 fonts.

Use the bareword integer for positioning - although float is available and uses subpixel positioning, which would in theory give better spacing, it has never worked properly and tends to look awful.

The optional parameter can be used to override the Freetype rendering mode. It should be one of the barewords light or normal. By default, light rendering is used with light hinting, and normal rendering otherwise. P set the default font style pfontstyle STR Font style tag Sets the default text styling. This command is equivalent to inserting a ~d STR~
formatting tag at the start of every subsequent text command (though it has no effect on sprites).

Only font style tags are may be used; size and position tags are not supported. Displays text in italic display font (slot 5). pfontstyle "si" ^Here is a page of italic text.\ ^And it's still italic!\ pfontstyle ^d^ ;back to regular style P add or remove a ligature or shortcut sequence pligate STR,NUM|STR Shortcut matching text Unicode codepoint for shortcut result (if numeric) (Unicode) char for shortcut result (if string) pligate STR,remove Shortcut matching text Keyword to remove the defined matching shortcut pligate {none|default|basic|punctuation|f_ligatures|specials|all} Keyword for a preset shortcut set Adds or removes shortcut sequences. This commands lets you define a sequence of ASCII (or Unicode) characters to be replaced with a single Unicode character within text, for use as shortcuts or mappings to ligatures.

The Unicode result for a particular shortcut may be given either as the numeric value of a Unicode codepoint, or as a string whose first (Unicode) character will be used as the result. Use the bareword remove to remove the shortcut with the defined sequence.

In its single-argument form, this command enables the specified preset shortcuts. Valid arguments are:

none - will remove all defined shortcuts, even defaults
all - adds all of the following preset shortcuts
default - enables basic and specials presets (default)
f_ligatures - adds ligatures for "ff", "fi", "fl", "ffi", and "ffl"
specials - adds the hash escape sequences for the special characters @, /, \, _, ^, `, !, #
basic - adds the following sequences for quotes:
"`" ‘ (left single quotation mark)
"``" “ (left double quotation mark)
"'" ’ (right single quotation mark)
"''" ” (right double quotation mark)
punctuation - adds shortcuts for these punctuation symbols:
"%-" ‑ (non-breaking hyphen)
"%_" U+00A0 (non-breaking space)
"%." U+2009 (thin space)
"..." … (horizontal ellipsis)
"--" – (en dash)
"---" — (em dash)
"(c)" © (copyright sign)
"(r)" ® (registered sign)
"(tm)" ™ (trademark sign)
"++" † (dagger)
"+++" ‡ (double dagger)
"**" • (bullet)

To display a shortcut sequence as-is within text, insert a Unicode zero-width non-joiner (ZWNJ) or its builtin shortcut | within the sequence to prevent it from matching the shortcut. (The ZWNJ will not be displayed).
If the Unicode character for a shortcut/ligature is not present in the current font, that shortcut sequence will not be replaced in text.

Please note that this command, and ligature/shortcut processing in general, are not available in onscripter compatibility mode. Defines shortcuts and displays text using them. pligate basic ;presets for curly quotes pligate "-->",0x2192 ;rightwards arrow pligate "'",remove ;don't replace single apostrophe with curly quote ^``Check it out --> it's my funky-cool shortcut example.''\ ;assuming a font that contains all those glyphs, the previous text should display as: ;“Check it out → it's my funky-cool shortcut example.” P specify characters that cause indents pindentstr STR Indent characters pindentstr basic Keyword for the standard indenting characters Specifies a set of characters where, if one appears as the first character of a page, it will set an indent; this is equivalent to following the character with a ~n~ formatting tag.
Giving an empty string will clear all indent characters.

Using the basic keyword will cause indenting on the following characters:
( U+0028 (left paren)
- U+2014 (em dash)
‘ U+2018 (left single curly quote)
“ U+201c (left double curly quote)
「 U+300c (left corner bracket)
『 U+300e (left white corner bracket)
（ U+ff08 (fullwidth left paren)
～ U+ff5e (fullwidth tilde)
｢ U+ff62 (halfwidth left corner bracket) Since ponscripter-20091015, scripts start out with nodefined indent characters, so please use this command if you want indenting characters.
pindentstr basicwill restore the default indent characters from earlier ponscripter versions. (by Mion) Sets quote marks (undirected and left) as indenting characters. pindentstr ^"'‘“^ P specify characters that allow linebreaks pbreakstr STR Break characters pbreakstr basic Keyword for the standard linebreaking characters Specifies a set of characters that allow linebreaks; if necessary for word-wrapping, ponscripter will make a new line right after one of these characters.
Giving an empty string will clear all linebreak characters (including space!)

Using the basic keyword will set the following characters as breaking:
' ' U+0020 (space - default)
- U+202d (hyphen-minus)
– U+2013 (en dash)
- U+2014 (em dash)
Since ponscripter-20091015, scripts start out with only the space character defined for linebreaking, so please use this command if you want other break characters. pbreakstr basicwill restore the default break characters from earlier ponscripter versions. (by Mion) Sets space, comma and hyphen as break characters. pbreakstr ^ ,-^ P localize a right-click menu message string localestring {message_reset_confirm|message_end_confirm|message_yes|message_no|message_empty|message_space} STR Locale string identifier Locale string localestring {days|months|am_pm|digits} STR,... Locale string list identifier Locale string list item(s) localestring {message_save_label|message_save_exist|message_save_confirm|message_load_confirm} STR Save/load related locale string identifier Save/load related locale string Changes a string or set of strings related to the default right-click menu.
There are three separate types of localestring commands: standard dialog items, localization lists, and processed dialog items.

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

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

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

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

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

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

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

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

Try the following examples of localestring settings. Use French abbreviated months and days of the week. localestring months "janv.","févr.","mars","avr.","mai","juin","juill.","août","sept.","oct.","nov.","déc." localestring days "Dim","Lun","Mar","Mer","Jeu","Ven","Sam" Use fullwidth Japanese digits and space. localestring digits "０","１","２","３","４","５","６","７","８","９" localestring message_space "　" Use Russian confirmation messages and responses. localestring message_save_confirm "Сохранить %s%n?" localestring message_load_confirm "Загрузить %s%n?" localestring message_reset_confirm "Выйти в главное меню?" localestring message_yes "Да" localestring message_no "Нет" Display savefile slot with the default format. localestring message_save_exist "%b %d%i %_H:%i%M" ;e.g. "Feb 06 0:45" Other savefile slot formats. localestring message_save_exist "%Y/%m/%d %H:%M" ;e.g. "2008/02/06 00:45" localestring message_save_exist "%m/%d/%Y %i%I:%M %i%p" ;e.g. "02/06/2008 12:45 AM" localestring message_save_exist "%a, %b %d, %I:%M %p" ;e.g. "Wed, Feb 6, 12:45 AM" P map a font file to a ponscripter font slot h_mapfont NUM,STR[,STR] Font slot (0-7) Font filename Font metrics file (Type 1 fonts only) Maps a font file to the given font slot. Equivalent to the command pmapfont. Maps font slot 0 to "myprettyfont.ttf". h_mapfont 0,"myprettyfont.ttf" P configure ponscripter text rendering h_rendering {none|full|light},{integer|float}[,{light|normal}] Hinting (either none, full, or light) Positioning (either integer or float) Optional Freetype rendering mode (light or normal) Configures the Freetype text rendering mode. Equivalent to the command prendering. P set the default font style h_fontstyle STR font style tag Sets the default text styling. Equivalent to the command pfontstyle. 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 P add or remove a ligature or shortcut sequence h_ligate STR,NUM|STR Shortcut matching text Unicode codepoint for shortcut result (if numeric) (Unicode) char for shortcut result (if string) h_ligate STR,remove Shortcut matching text Keyword to remove the defined matching shortcut h_ligate {none|default|basic|punctuation|f_ligatures|specials|all} Keyword for a preset shortcut set Adds or removes shortcut sequences. Equivalent to the command pligate. P specify characters that cause indents h_indentstr STR Indent characters h_indentstr basic Keyword for the standard indenting characters Specifies characters that will set an indent. Equivalent to the pindentstr command. Sets quote marks (undirected and left) as indenting characters. h_indentstr ^"'‘“^ P specify characters that allow linebreaks h_breakstr STR Break characters h_breakstr basic Keyword for the standard linebreaking characters Specifies characters that allow linebreaks. Equivalent to the pbreakstr command. Sets space, comma and hyphen as break characters. h_breakstr ^ ,-^