ONScripter for PSP

ONScripter for PSP
ONScripter for PSP
General
Author	tormtorm
Type	Game Engine
Version	20110111_psp
License	GPL-2.0
Last Updated	2011/01/11
Links
	ONSforPSP - Tools Download
	Website

Port of ONScripter for the PSP. ONScripter (O-N-Scripter) is an open-source implementation of NScripter, a game creation engine that significantly contributed to the rise of visual novels in Japan.

NScripter was widely adopted by developers to create many influential titles in the genre, such as Tsukihime (月姫) by TYPE-MOON and Mizuiro (みずいろ) by Nekonekosoft.

Installation

Binary and tools:

ONScripter for PSP (v20110111 + old release with source)
ONScripter for PSP tools (sort by: extract/repack tools, image related, audio related, scenario related)
ONScripter kit (backup from psppcg.wiki, contains audio tool to batch convert WAV to OGG)

Folder structure

ms0:/PSP/GAME/ONS/

EBOOT.PBP
0.txt or nscript.dat (script file)
arc.nsa or arc.sar (archive for image, music, etc. converted for PSP)
default.ttf (TrueType Fonts for Windows that support Unicode)
ons.ini (configuration file)
additional folder with BGM or movies (e.g. cd/Track01.xxx, cd/Track02.xxx, cd/Track03.xxx... cd/Track14.xxx)

Preparing game data

Supported format

Resolutions - 320x240, 360x270, 384x288, 480x360
Image - JPG, BMP, PNG
Audio - OGG, MP3, WAV
Video - MPG

Extract archive

If there is a arc.nsa / arc.sar, you can extract it with any of the following tools:

nsadec.exe / sardec.exe
crass-0.4.14.0
Susie+NScripter Susie plugins.
(See also Resources section for game specific converters.)

Resize images

The PSP screen resolution is 480x272, so images need to be proportionally resized. The images can be converted and resized using FastStone Photo Resizer. Keep the aspect ratio according to the game’s original resolution (e.g., 4:3 or 16:9) and PSP's display limit.

For instance, if the game's resolution is 800x600 (4:3) and you would like to resize to 360x270, you would scale down the original images to 45% of their sizes. (In FastStone Photo Resizer, check Use Advance Options > Resize In Percentage).

Sometimes there may be slight alignment issues with images like character sprites due to decimal points in the scaling percentage (e.g. when converting from a resolution of 640x480 to 360x270). To avoid these issues, try to choose a resolution that result in whole number scaling percentages whenever possible. (see notes below)

Also, the icon files (i.e. cursor1.bmp) can become distorted when resized, instead you can use the default icons set (available in 13x13 and 15x15), just replace the existing icon files with these.

Audio conversion

For the audio files, OGG with a sampling rate of 44100 Hz is recommended. Use a bitrate between 64kbps and 80kbps.

WAV to OGG - While ONSforPSP can play WAV files without issues, but depending on the game size you may want to convert them to OGG to save space. You can use tools like foobar2000 for batch conversion.
MIDI to OGG/WAV/MP3 - ONSforPSP cannot play MIDI files directly, so they need to be converted to OGG, WAV, or MP3.
CD Tracks to OGG/WAV/MP3 - CD audio tracks must be converted and placed in the following format:
- (game directory)\cd\Track01.???
- (game directory)\cd\Track02.???
- ??? can be .ogg, .wav, or .mp3. When ONSforPSP plays CD tracks, it will automatically play the corresponding audio files.

Videos can be converted using smjpeg4.zip (require ffmpeg.exe).

Repack archive

Once you've converted all the files, repack them back into arc.nsa with tools such as nsaarc.exe or nsaed.exe.

Make sure to keep the same folder arrangement as you had before converting.

Update the script file

If the script file is a nscript.dat, decrypt it with Yet Another nsdec or an online converter into a text file.

Rename it to 0.txt, then open it with a text editor and update the script to reflect the changed filenames from the conversion, examples:

BMP to JPG:
- .bmp -> .jpg
MIDI to OGG/MP3:
- .mid -> .ogg or .mp3
- playonce -> bgmonce
- play -> bgm
- playstop -> bgmstop
WAV to OGG:
- .wav -> .ogg
- wave -> dwave 1（depends, see API for reference）
- waveloop -> dwaveloop 1（same as above）
- wavestop -> dwavestop

If you are using the default icons set, remember to leave them as .bmp.

If the game doesn't have arc files, you can still pack the assets into arc.nsa, and then write nsa on a single line in the 0.txt. Refer to Section 07 from this tutorial for more details. (If you have video file, you will also need to update 0.txt.)

Notes

If there is black lines appearing on the screen/background, check the ons.ini file and make sure the RESOLUTION= value matches the converted image size.
If you notice vertical lines appearing next to the character sprites, try adding a 2px white right margin to the sprites (example image from kaisernet.org).
Alternatively you can try using the ONScripter Multi Converter (an image, audio and scenario converter for ONSforPSP).

ons.ini

If ons.ini is missing or has typos, default settings are applied:

RESOLUTION=320
SCREENSIZE=ORIGINAL
SCREENBPP=16
CPUCLOCK=222
FONTMEMORY=OFF
ANALOGKEY=ON1
CURSORSPEED=5

Settings:

RESOLUTION=320/360/384/480/640/XXX
- Sets the screen resolution width. Higher resolutions may slow down performance.
- 320: 320x240 (QVGA)
- 360: 360x270 (PSP)
- 384: 384x288 (PSP2)
- 480: 480x360 (PSP2)
- 640: 640x480 (VGA)
SCREENSIZE=ORIGINAL/NORMAL/FULL
- ORIGINAL: Displays in original size. (QVGA, PSP)
- NORMAL: Displays at maximum size while maintaining aspect ratio. (QVGA, PSP, PSP2, VGA)
- FULL: Displays at maximum size, possibly distorting aspect ratio. (QVGA, PSP2, VGA)
SCREENBPP=15/16/24/32
- Sets the color depth of images. Higher values increase color quality but use more memory.
CPUCLOCK=133/166/222/266/333
- Sets the CPU clock frequency in MHz. Higher values increase processing speed but drain the battery faster.
FONTMEMORY=OFF/ON
- OFF - Accesses default.ttf from the system for each text display.
- ON - Loads default.ttf into memory (reduce system access but increase memory usage).
ANALOGKEY=OFF/ON1/ON2
- OFF: Disables analog key functionality.
- ON1: Enables shortcut keys; allows key binding changes.
- ON2: Displays and allows cursor movement with adjustable speed.
CURSORSPEED=1 ～ XXX
- Sets cursor movement speed when ANALOGKEY=ON2.
- The value represents pixels moved per analog key response. Higher values increase speed but reduce precision.
SAMPLINGRATE=11025/22050/44100
- Sets the audio sampling rate.
CHANNELS=1/2
- Sets the number of audio channels.
Key Bindings:
- Change key bindings with SETTING=VALUE, where VALUE corresponds to SDL keyboard values. Examples:
- TRIANGLE=
- CIRCLE=
- CROSS=
- SQUARE=
- DOWN=
- LEFT=
- UP=
- RIGHT=
Key Value:
- 27: Open menu or cancel
- 13: Confirm selection or advance text
- 32: Advance text only
- 305: Skip text while holding down
- 111: Toggle page display
- 115: Switch to skip mode (skip already read text)
- 274: Move to next choice
- 273: Move to previous choice
- 48: Toggle automode mode (only if automode or mode_ext is set)
- 97: Change text display speed (slow > normal > fast)
- 276: View backlog (only if the usewheel command is set in the script)
- 275: Advance in backlog

Note: Key settings for Analog are only active when ANALOGKEY=ON1.

Resources

Controls

Circle - Return (Confirm, Advance text)

Cross - Space (Advance text)

Square - Ctrl (Hold to skip text)

Triangle - ESC (Menu)

L - O (1 Page On/Off)

R - S (Skip On/Off)

Down/Right - Move to next choice

Up/Left - Move to previous choice

Start - A (Automode On/Off)

Select - Change text display speed

Screenshots

Credits

Original by し〜くる氏 (shinshin319): ぼくだけのちいさな世界

Updated by すとーむ氏 (tormtorm): 霧雨の降る日に

External links

Author's website - http://www.geocities.jp/stm_torm/ons/ons.html (archived)