ONScripter page

Source files

https://github.com/ogapee/onscripter

Source package

Latest release	onscripter 20230825
Previous release	onscripter-20230824.tar.gz

Binary package (Android packages are tested by ME)

Platform	Distributor
Android (2.0 and later)	ONScripter in Google Play
	ONScripter on Android
Zaurus (SL-C700, etc.)	SDL on Zaurus page
Linux	Debian Official Unstable (sid)
	Debian Official Testing (trixie)
	Debian Official Stable (bookworm)
MacOSX	Homebrew
	ONScripter Launcher and Binary for Mac OS X
Windows	ONScripter on Windows
iPhone, iPod touch	iPodOns
NetWalker	Qt beginner's memo
Brain (WindowsCE 6.0)	ONScripter for Brain
NetBSD	pkgsrc
OS2/Warp	packages
Playstation3	PS3 Linux de zisaku soft wo tanoshimo
Wii	ONScripter WiiBrew
FreeBSD	Official FreeBSD package
	Private Ports for FreeBSD
Dreamcast	ONScripter for Dreamcast
Let me know if you have others

Derived projects

The following are projects derived from ONScripter. They are maintained by others.

• onscripter-insani
  A project maintained by Seung Park of nscripter.insani.org.
• ponscripter-fork-wh (wh-dev branch)
  PONScripter project.
• ONScripter-EN
  A variant of ONScripter that can handle English scripts as well as Japanese scripts. It has been maintained by Haeleth and Uncle Mion.

Features

1. You can load and save save files that are compatible with the latest NScripter (2011/12/15). Please see How to play on different platforms at the same time.
2. All operations can be done from the keyboard. Of course, you can also use the mouse.
3. You can change CD Audio playback to music file (MP3, Ogg) playback.
4. It supports multiple platforms, including Windows, Linux, MacOS X, MacOS 9, Android(1.6 or later), iPhone, iPad, PSP, Zaurus (SL-5500, SL-A300, SL-B500, SL-C700), FreeBSD, OpenBSD, Haiku, Solaris(on SPARC), Tru64 UNIX, OS/2Warp, iPod, PocketPC, Playstation3, Wii, GP2X, NetWalker and Dreamcast. It should also work on other platforms as well if Requirements are satisfied.
5. Since we have not implemented all the commands and specifications, some games may behave strangely. If this happens, please report it to the bug-tracking system above.

Requirements

The following programming languages and libraries are required. The versions listed are for my development environment, but you don't need to adapt to this version.

Required

• C++ programming language
  • g++ 10.2.1 (Linux)
  • Visual Studio 2019 C++ (Windows)
• Japanese TTF file based on Unicode renamed as "default.ttf"
• libjpeg-6b (Independent JPEG Group)
• bzip2-1.0.5 (bzip2)
• SDL-1.2.14, SDL_image-1.2.10, SDL_mixer-1.2.8, SDL_ttf-2.0.9 (Simple Directmedia Layer)
• FreeType 2.3.11 (the Free Type Project)

Recommended

• SMPEG-0.4.5
  SMPEG is required to play MPEG1 movie files. Either SMPEG or MAD is required to play MP3 music files.
• ogg-1.2.0, vorbis-1.3.1 (The Ogg Vorbis CODEC Project)
  Ogg Vorbis is required to play Ogg Vorbis music files. It is enabled by default in Makefile.Linux and Makefile.ArmLinux that are included in the source package. Tremor Vorbis can be used instead that decodes music using integer arithmetics only.

Optional

• mad-0.15.1b (MAD: Mpeg Audio Decoder)
  MAD is an MP3 decoding library that uses only integer arithmetics. This is essential if you want to play MP3 music files on Android or Zaurus. To use MAD, SDL_mixer library must be built with MAD enabled instead of SMPEG.
• avifile-0.7.48 (avifile)
  Avifile is necessary if you want to play AVI files with avi command. It is enabled when USE_AVIFILE is defined and AVIWrapper.o is linked.

ONScripter has been tested on Linux (Debian Buster), Android (Sony (8.0)), iOS (iPad2), and sometimes on Windows.

How to build

Unpack the ONScripter source package in an appropriate location. Type " make -f Makefile.Linux " on Linux, or type " nmake -f Makefile.Win " on Windows. On Windows, the path to the header files and libraries for bzip2, SDL, SMPEG, etc., should be modified in Makefile.Win depending on your environment.

How to run

[Required] Copy the necessary archives of a game to the same location. Usually, you need a script file (0.txt or nscript.dat) and archive files (arc.sar or *.nsa or *.ns2). If there are multiple archive files such as arc1.nsa to arc9.nsa, you need to copy them as well. In some games, images and sounds are placed outside archive files. In that case, you also need to copy them all. The easiest way is to copy the directory including sub-directories where a game is installed.

[Required] Following Displaying Kanji using TrueType font, put a Japanese TrueType font file renamed as "default.ttf".

[Optional] If you want to play music files instead of CD audio tracks, please follow the instructions in Using music files instead of CD audio to prepare music files.

[Required] Run ONScripter. It reads from nscript.dat and archives in the same directory, and the game will start. Since ONScripter outputs save files and status files in the same directory, please be sure that the directory is writable.

Keyboard shortcut

All operations including mouse operations can be performed by keyboard short-cuts, though the shortcut keys defined in the script have higher priority.

Key	Description
Space	Same as mouse left click, except it behaves as if the area outside the button is clicked even if the mouse cursor is just on a button.
Enter	Same as mouse left click.
Esc	Same as mouse right click.
P, K, ↑	Move the mouse cursor onto the previous choice (button) at the decision branch (button selection).
N, J, ↓	Move the mouse cursor onto the next choice (button) at the decision branch (button selection).
S	Skip sentences to the next decision branch.
O	Switch to one-page display mode.
H, ←	Same as mouse wheel up.
L, →	Same as mouse wheel down.
F	Switch between full-screen mode and windowed mode.
A	Enter into the auto-read mode if automode or mode_ext is defined.
Z	Enter into the volume and variables modification mode if "--edit" is specified in the command line options.
1, 2, 3	Change the speed of drawing characters.
Shift + q	Quit. (end command is issued)

Command line options

Options	Description
-h, --help	Show the help messages and exit.
-v, --version	Show the version information and exit.
--cdaudio	Use CD audio if available. Even if it is not available, sound files are not used instead. [default: use Music files instead of CD audio]
--cdnumber cd_number	Choose the CD-ROM drive number to use if there are many. [default: 0]
-f, --font file	Set a TTF font file. [default: default.ttf in the current directory]
--registry file	Set a registry file.
--dll file	Set a dll file.
-r, --root path	Set the directory where the script and archives are placed. [default: current directory]
--fullscreen	Start in full-screen mode.
--window	Start in windowed mode.
--force-button-shortcut	Ignore "getenter" and "useescspc" commands. In other words, "esc", "space" and "enter" keys are forced to behave as a mouse click.
--enable-wheeldown-advance	Advance the text by turning the mouse wheel downwards when it waits for a click at the end of a sentence. If the behavior of waiting for a click is customized by "textgosub", this option has no effect.
--disable-rescale	Do not rescale the images in the archives to fit in the screen when compiled with PDA_WIDTH or PDA_AUTOSIZE defined. Along with the compressed archives as mentioned in Compression of archives, ONScripter will run faster by avoiding the need for resizing. Note that image files outside the archives are resized as before.
--render-font-outline	Render the outline of a text in black (or white if the color of the text is dark) using the outline rendering function supported in SDL_ttf since 2.0.10. Text will be clearly shown.
--edit	Enable online modification of the volume and variables when "z" is pressed.

How to play on different platforms at the same time

You can share save files among different platforms such as desktop PC (Windows, Linux, MacOSX), smartphone (Android, iPhone), etc. To do this, you need to prepare game data on all platforms and move all output files generated from ONScripter (or NScripter) from one platform to another.

NScripter or ONScripter generates/updates the following files. Some may not be generated depending on the games.

Output files	Description
archive_path/gloval.sav	global variables
archive_path/envdata	environmental variables
archive_path/kidoku.dat	already-read texts
archive_path/NScrflog.dat	already-read files
archive_path/NScrllog.dat	already-read labels in a script
archive_path/save*.dat	save files (those generated by ONScripter can not be read from NScripter, but those generated by NScripter can be read from ONScripter)
archive_path/sav/save*.dat	save files compatible with NScripter (not warranted) generated by ONScripter
archive_path/other images	Screenshots may be saved as images. The directory and name of images are dependent on the games.

The format of a save file may change when a newer version of NScripter (or ONScripter) is released. So, ONScripter generates a save file having extra information about the version number of a save file in the header. A save file without a version number is also generated under "sav" directory if it exists and is compatible with a save file generated from the latest NScripter. Note that the version number of a save file is different from the version number (e.g. 20120225) of ONScripter.

ONScripter can load any save files with version number and save files in the latest format without version number.

From ONScripter to ONScripter

Simply copy all the above-mentioned modified files including save*.dat.

ONScripter_dir/* → ONScripter_dir/*

From NScripter to ONScripter

Simply copy all the above-mentioned modified files including save*.dat.

NScripter_dir/* → ONScripter_dir/*

From ONScripter to NScripter

Copy all the above-mentioned modified files excluding save*.dat.

ONScripter_dir/* -> NScripter_dir/*

Copy save files under "sav" directory

ONScripter_dir/sav/save*.dat -> NScripter_dir/save*.dat

Notice

• Save files generated from the latest NScripter (nscr.exe released in 2011/12/15) are supported. ONScripter doesn't load save files generated from older versions of NScripter.
• Compatibility between the latest NScripter and ONScripter is not guaranteed, but there has been no problem as far as I know.
• Use the above-mentioned latest NScripter from the beginning if you use both ONScripter and NScripter. In that case, be sure to make "sav" directory in advance.

Reading from the registry

getreg command reads data from the registry of Windows. ONScripter emulates this command by reading from registry.txt (text file) that describes the data.

The format of registry.txt is as follows. Letters are case-sensitive. Be careful not to have extra space. If you use Kanji characters, use Shift JIS code set.

[The second argument of getreg command (excluding quotation marks around)]
The third argument of getreg command = string to be compared (including quotation marks around)

Example of registry.txt

[software\StudioOGA\ONScripter]
"INSTALL"="FULL"

[software\StudioOGA\のまど]
"Download log file"="c:\nomad_down.log"
"Upload log file"="c:\nomad_up.log"

You can share a registry file among games if ONScripter is launched with --registry option. Without --registry option, it looks for registry.txt in the current directory.

Loading DLL

exec_dll command executes DLL (Dynamic Link Library) that is built to run on Windows. ONScripter emulates this command by reading from dll.txt (text file) which describes the relationship between the name of a DLL and its return value. So, DLL is not executed and the return value is fixed.

The format of dll.txt is as follows. Letters are case-sensitive. Be careful not to have extra space. If you use Kanji characters, use Shift JIS code set.

[Name of DLL]
str = "string" (string value received in getret command)
ret = integer (integer value received in getret command)

Example of dll.txt

[test.dll]
str = "山田/太郎/やまだ/たろう"
ret = 1

[test2.dll]
str = "StudioOGA"
ret = 2

You can share a dll file among games if ONScripter is launched with --dll option. Without --dll option, it looks for dll.txt in the current directory.

Online modification of volume and variables

This is a temporary function and might be modified or removed in the future.

It is enabled by setting '--edit' option when launching ONScripter.

If you press the z key when waiting for the key-in, you will enter edit mode and the title bar becomes as follows.

[EDIT MODE]  MP3 vol (m)  SE vol (s)  Voice vol (v)  Numeric variable (n)

If you further press any of the M, S, V, or N keys, you will enter sub-edit mode where you can change corresponding variables. You can escape from edit mode by pressing the ESC key.

If you press the N key, you have to choose a variable first and then change its value.

You can use the '0' to '9', '-', BackSpace, Esc, and Enter keys when you change numeric variables. The '-' key is accepted when you are editing a numeric variable and the value is 0. If the value is other than 0, you need to clear the value by pressing the BackSpace key and then pressing the '-' key.

Displaying Kanji characters using TrueType font

Japanese TrueType font is required to display Kanji characters. For example, msgothic.ttc under c:\Windows\Fonts in Windows 7, or freely available TrueType fonts shown below can be used.

Genjyuu gothic

It is a round gothic style font derived from Gennokaku gothic. Among them, I recommend GenJyuuGothicX-Monospace-Bold.ttf because it is bold, beautiful, and easy to read.

M+ and IPA compositional font

Re-distributable fonts based on M+ font and IPA font. Among them, I recommend Migu-2M-bold.ttf because it is bold, beautiful, and easy to read.

IPA font

Re-distributable Gothic and Mincho font.

Mika-chan font

Handwritten font.

Because SDL_ttf renders Kanji characters badly when TTF_STYLE_BOLD is enabled, ONScripter just ignores "bold" settings. If you use a small device like a smartphone, it is better to use a bold TrueType font such as Migu-2M-bold.ttf mentioned above and HG Gothic E (HGRGE.TTC).

TrueType font file should be renamed to default.ttf and be placed in the same directory where a script file is placed before launching ONScripter.

Using sound files instead of CD audio

Create a directory named "cd" in the directory where scripts and archives are placed, and put sound files as follows.
cd/track01.xxx
cd/track02.xxx
cd/track03.xxx
...
cd/track14.xxx
...
MP3, OGG and WAV format are supported. Please change the above "xxx" according to the format of the sound files.

The behavior of a command to play the first CD audio track, i.e. play "*1", is changed to play "track01.mp3". This is the default behavior unless "--cdaudio" option is specified. In case of missing sound files, "play" command is just ignored.

Playing MIDI

MIDI is played by SDL_mixer. When playing MIDI, a temporary file "tmp.mus" is created because SDL_mixer can only load MIDI data from a file.

Playing MIDI using a software sound module on Unix (tested on Linux and Zaurus) (default)

Playing MIDI using timidity, a software sound module incorporated in SDL_mixer. In this case, you need to download a set of sound patches timidity.tar.gz and expand them under, for example, /usr/local/lib/.

Playing MIDI on Windows

You need to download a set of sound patches timidity.tar.gz and expand them under c:\.

Playing MIDI using a hardware sound module on Unix (tested on Linux)

Please install a MIDI player that can use an external sound source such as playmidi and set the environment variable MUSIC_CMD. (e.g. MUSIC_CMD=/usr/bin/playmidi)
We have confirmed that it works by connecting an external sound source via serial connection and setting '/usr/bin/midiplay -q -o /dev/ttyS0' in MUSIC_CMD.
playmidi can only play to MIDI ports recognized by the kernel, but midiplay can play directly to the serial port.
If you use the patch that turns serial ports into MIDI ports, you may be able to use serial-connected sound sources with playmidi as well, but this has not been tested.

Compression of archives

The screen size of Linux Zaurus (320x240) or PSP (360x270) is smaller than the size expected in the script. By resizing the images in the archives beforehand, you can keep the size of the archives small and use the storage efficiently. Images with SPB format are stored in BMP format unless the -e option is specified.

Usage

sarconv                    src_screen_width dst_screen_width src_SAR_filename dst_SAR_filename
nsaconv [-e] [-ns2] [-ns3] src_screen_width dst_screen_width src_NSA_filename dst_NSA_filename

src_screen_width can be 640 or 800.

dst_screen_width can be any width such as 176(iPod), 320(QVGA), 360(PSP), 384(PSP), 640(VGA).

Examples

Converting a SAR archive from 640x480 to 320x240.

> sarconv 640 320 arc.sar zaurus_dir/arc.sar
...

Converting a NSA archive from 800x600 to 320x240.

> nsaconv [-e] 800 320 arc.nsa zaurus_dir/arc.nsa
> nsaconv [-e] 800 320 arc1.nsa zaurus_dir/arc1.nsa
...

Converting a NSA (ns2) archive from 800x600 to 640x480.

> nsaconv [-e] -ns2 800 640 arc.nsa zaurus_dir/arc.nsa
> nsaconv [-e] -ns2 800 640 arc1.nsa zaurus_dir/arc1.nsa
...

You have to manually distinguish the version (1, 2, or 3) of NSA archives. The use of ns2 command in the script indicates version 2, while the use of ns3 command indicates version 3. If you cannot check the script, please try without -ns2 first. If it fails, please try with -ns2 or -ns3.

With the -e option, wav and bmp files are compressed in nbz format. This sets a special value, incompatible with NScripter, for the flag indicating the compression type of NSA archives. This extension may conflict with an extension by NScripter in the future. In that case, it can be solved by modifying the converter and reconverting archives. Since reconverting doesn't affect save files, etc., those who use ONScripter in Zaurus are advised to convert with this option. Since wav files are compressed with bzip2, archives become quite small in games that heavily use wav files. As a disadvantage, the game speed is slightly slower because it additionally decodes bzip2, but it's not noticeable.

With the -j option, bmp files are converted to jpeg files while keeping the filenames unchanged. Except, bmp files using palette color are not converted.

The option -q sets the quality of jpeg compression ranging from 0 to 100. A small value indicates low quality but a small file size. The default value is 75.

The option --disable-rescale is required when a rescaled archive is used.

You can enjoy a game in 320x240 resolution on Linux if ONScripter is compiled with -DPDA.

Problem of chattering MP3 music on Windows platform

Some MP3 files are played with muddled sound when ONScripter is linked with pre-built SMPEG binaries on Windows. It is due to an optimization problem when compiling SMPEG with MSVC and can be solved by suppressing some of MSVC's global optimization, as shown below, and compiling it yourself.

File to be modified: audio/mpeglayer3.cpp
Add the following #pragma specification before and after the function layer3reorderandantialias.

#pragma optimize( "g", off )
void MPEGaudio::layer3reorderandantialias(int ch,int gr,
                                          REAL  in[SBLIMIT][SSLIMIT],
                                          REAL out[SBLIMIT][SSLIMIT]){
  ......
}
#pragma optimize( "g", on )

How to write an English novel

This feature is an extension of ONScripter based on a request from Chend (chendo[at]gmail.com). He has contributed significantly to ONScripter by proposing specifications and sending patches.

By defining ENABLE_1BYTE_CHAR at compile-time, the text from `(back quote) to the end of the line or another ` is displayed as a sentence written in 1-byte characters. In the text, single-byte spaces are enabled for display, but the display of variables within the text is disabled, and the color and time specifications are also disabled depending on the starting position. If you want to change the color in the middle of the text, use / to separate lines. However, the forced click character is ignored (_) immediately after waiting for a click (@) or page break (\).

If any function is assigned to ` in the future, it may be removed or changed to another character. The current function of ` may be available with ENABLE_1BYTE_CHAR defined as it is now, but this is not guaranteed.

In addition, if FORCE_1BYTE_CHAR is specified together with ENABLE_1BYTE_CHAR at compile-time, it is possible to display all characters in 1-byte characters entirely. Specifically, in addition to the above, the right-click menu will be displayed in English and numeric variables will be displayed in 1-byte characters.

An example script is written below.

*define 
clickstr `.?"`, 2 
savename `Save the scene`, `Load the scene`, "Memory "
rmenu `Save to file`,save,`Load from file`,load
game
 
*start
`Hi, this was test.
`Hi, this is test again.
`_"He said so."
`_"She said so."
`Does it work??
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
            

Memo

event_mode

The values in the table below are used exclusively.

Value	Description	Example
IDLE_EVENT_MODE	Not clickable wait.	wait
WAIT_BUTTON_MODE	Wait for selection using ButtonLink (image).	btnwait, select, right-click menu
WAIT_INPUT_MODE	Wait for clickable user input.	delay, click, @, \, text rendering, screen effect

The values in the table below are used in conjunction with the values in the table above.

Value	Description	Example
WAIT_TIMER_MODE	Wait for the specified time, animation is processed while waiting	Most cases except for screen effect and text rendering.
WAIT_VOICE_MODE	Wait until voice is finished.	automode, btntime2 only
WAIT_TEXT_MODE	Wait at the end of the text.	@, \, select
WAIT_RCLICK_MODE	Wait for right click.	lrclick

Order of rendering layers

In the table below, the lower layer is hidden by the upper layer. The initial value of "humanz" is 499.

Text is always rendered at the top when appears.

Normal	"windowback" is used
Button
Cursor
Text window and text	Numeric label
Numeric label	Bar
Bar	Sprite (from humanz to 0)
** monochrome and negation effect **	Text window and text
Sprite2 (from 255 to 0)	Sprite2 (from 255 to 0)
Sprite (from humanz to 0)	** monochrome and negation effect **
Tachi-e (standing characters)
Sprite (from 999 to humanz+1)
Background