Welcome to chaoskaiser72's Perfect NScript Class!

This page is a crash course on the basics of NScripter and contains some more advanced information about ONScripter that would make the main page too wordy. This page assumes that you will be using ONScripter-EN.

To Begin

The first two things you will need to download are the ONScripter-EN engine and the ONScripter Tools built for your system, both downloadable here. If using Windows, get the build with the separate SDL.dll -- this allows the engine to use DirectSound which is a major improvement.

A good text editor will be necessary; Notepad++ is recommendable for Windows albeit buggy. If dealing with existing Japanese games, you will need to set your system locale to Japanese, and it will be helpful to set your editor font to a comfortable (and recommendably, fixed-width) Japanese font, such as MS Gothic.

You will need a fixed-width font for the game. Proportional fonts are not supported -- in order to use those you would need to go with PONScripter or ONSlaught. It is best to get a free (as in freedom) font if you are to distribute your game; Sazanami Gothic or Sazanami Mincho is most recommendable, but you can experiment with anything you like. Simply drop the font file into your game folder and rename it to default.ttf.

Make a text file named 0.txt, and give it Shift-JIS encoding. The engine can sometimes read text files with the wrong encoding, but it is not meant to. Notepad++ has a bug which causes it not to change file encodings, so you may have to prepare the file elsewhere. Before release, you may choose to obfuscate your script into an nscript.dat file with nscmake so as to keep readers from spoiling themselves, but this is not necessary at any point.

You will most likely want to pack all your game assets in an arc.nsa (NScripter Archive) before release, but while you are still writing the game you can keep all the asset folders in your game folder, and the engine will read them as if the game's root directory were the inside of the archive.

Scripting Foreknowledge

Make the SECOND line in your 0.txt a ;gameid. This is absolutely essential, as later versions of ONScripter-EN keep save files in the C:\ProgramData\ directory (or ~/ on *nix) with each ONS game recieving its own named folder. If a ;gameid is not set, your save files will be stored in a folder with a randomly generated name. If you happen to be running a game from before the ;gameid function was added, you can put a text file named game.id in its folder with the name you want.

NScript syntax is roughly similar to that of BASIC, and comments are done with ; rather than #. The % marks numeric variables while $ marks string variables, and the visual novel line breaks and page breaks are done with @ and \, respectively.

NScripts consist of a define block, which contains setting commands that affect the whole game, and a game block, which contains the game and all subroutines thereof. The barest essentials to make a game run are as follows:

;gameid [your game name]

*define

;the define block can be empty so long as it exists, but you'll want to make use of it

game
*start

`Now here in the game block, you give the game some text to display,@
`and a line/page break so that the engine won't close immediately after.\

The engine will close without an error if it reaches the end of the file with no further instruction. As you can see, the barest basics of (O)NScripter development are as simple as can be, and in sections to come, you will learn how to display images, use effects, create branching choices, and script your very own graphical menu.

Sprites, Backgrounds and Effects

Now that your script file is fully capable of displaying text, the next step is to give your game some sort of visuals. NScripter was originally able to display JPEG and PNG only through DLL plugins, but now ONScripter can display both of those by default; text cursor and effect mask images still need to be BMP, though.

We'll say that you have a 640x480 background file called trees.jpg in a folder called image. To display it, you can simply add...

bg "image\trees.jpg",1
`Here's a filler line of text and a clickwait so the game won't close.\

To have it display instantly. The number at the end tells the engine how to display the image, as outlined in the command reference under effect. The number 1 causes the image to display instantly, but you can choose a numbered transition effect and specify the time it must take to complete, like so:

bg "image\trees.jpg",10,1000
`Fancy!\

This command now calls effect no. 10 which is a regular fade in/out, and takes one thousand milliseconds to complete. You can try different effects and specify your own amount of time for them to display.

Now, assuming you have got a background showing, you may now wish to add a standing sprite. The most simplified way to do this is to use the ld command, which gives you three preset slots for sprites to go into: l, c, and r; corresponding to the left, centre, and right. We will assume you have a sprite which uses PNG transparency, prepared to fit into a 640x480 window; and for the sake of the tutorial we will say it is sprite\imouto1.png.

ld c,"sprite\imouto1.png",3,2000

This will cause your sprite to display in the centre of the screen, use a right-sided shutter effect, and take two thousand milliseconds to do so.

To clear a sprite loaded with ld, simply use cl, specifying the current position of the sprite to be cleared:

cl c

Images will display separately rather than all at once when separate effects are specified. If you would like to have two images display at the same time, you can put the effect number following only the last image display command, like so:

ld l,"sprite\imouto2.png"
ld r,"sprite\imouto3.png",3,2000

Or alternatively, use the print command. It simply displays effects/refreshes the screen state.

ld l,"sprite\imouto2.png"
ld r,"sprite\imouto3.png"
print 3,2000

The old way of making images transparent on NScripter was to create an alpha mask, which required no actual transparency on the image's part, which meant BMP and JPEG files could be used as sprites. This is still a good, reliable, and supported way of doing things, so if you would like to make your own, you can simply use this image as an example. Transparency can be dictated by just how one side compares to the other, so for example if you lighten the silhouette on the right, the displayed sprite will become transparent accordingly.

Extracting NScripter Games for Examples

This could be considered a "step one", as both beginners and experts alike will benefit from seeing what other creators have done. A beginner may find complicated scripts overwhelming, but by searching around and making an effort to understand, it will always be possible to find out why a game does what it does. (Unless, of course, it's a bug or some unknown behaviour in the engine...)

This process will be much easier if you add the ONScripter Tools to your system path so that your command prompt or terminal can find it. Else, you will have to have the tool executables, and the script to be extracted, in a folder together in order to do any extraction. At any point, you can run one of these executables in order to see an explanation of how to use it.

To extract a script, open a command prompt and navigate to the folder where the script resides. Then, for example...

nscdec nscript.dat 0.txt

And that will turn nscript.dat into a human-readable text file which (O)NScripter will still recognise.

To extract an average arc.nsa asset archive, navigate to where it is and run...

nsadec -o ext arc.nsa

And that will put the contents of arc.nsa into a folder called ext.

Frequently Questioned Problems

Wonky text - Most likely you've chosen a custom font that is variable-width rather than fixed-width. If that's not the problem, it could be an issue with SDL_ttf, which handles text rendering -- the latest version has a regression which causes it not to work with ONScripter-EN correctly. Using the version bundled with the ONScripter-EN source code is the better option.
Sound effect lag - This is a problem with SDL, which is ONScripter's chief dependency. Most notably, when SDL was built into the Windows binaries instead of included separately, there was a problem with DirectSound's buffer sizes that causes sound effects to load slower. Simply use the binary that includes a separate SDL.dll on Windows; if it's happening on another platform you might be in for a bad time.
The main ONScripter branch supports English, why can't I use it? - Though it does, it breaks lines in the middle of words because it's not tuned to Western languages. It also requires Visual Studio for Windows 8 or above to build, and it doesn't have ONS-EN's nice enhancements like scaling.