Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
PONSCRIPTER(7)		      Ponscripter manual		PONSCRIPTER(7)

       ponscripter - Ponscripter overview

       Ponscripter is an interpreter for visual-novel-type games, derived from
       the NScripter design but	modified significantly to improve support for
       Western languages (at the cost of diminished support for	Japanese).

   Documentation contents
       Ponscripter documentation is split into a number	of sections.

       This page provides an overview of Ponscripter itself and	the overall
       structure of a game.

       The other sections are:

	   The ponscr binary: invocation, usage, and implementation notes.

	   Syntax of a Ponscripter script.

	   Commands that don't exist, or behave	differently, in	other
	   NScripter-type interpreters.

   NScripter implementations
       NScripter is a popular novel-game engine	written	by Naoki Takahashi.
       It's available at no cost even for commercial use, but its source code
       is not free, and	it's only supported on Microsoft Windows. Since	it has
       been used to drive a large number of popular commercial and amateur
       games, this has inspired	a number of open-source	cloning	efforts. As
       the original implementation, it serves as the definition	of the
       NScripter standard; sadly its documentation leaves something to be

       Ogapee's	ONScripter is the most significant of the clones. It supports
       a wide range of platforms, including handheld devices. When the
       attention of the	English-speaking fan translation community turned to
       NScripter games,	ONScripter was the interpreter we chose	to adapt to
       better support the English language. The	official ONScripter source
       code can	be compiled with basic English support;	since ONScripter
       development is aimed more at supporting new Japanese games and new
       platforms than at supporting localisation, the English-speaking
       community also maintains	a branch called	ONScripter-En which has	a
       number of improvements of interest to us, including better English
       support as standard.

       Ponscripter is a	fork of	ONScripter-En that drops any attempt to	remain
       in synch	with the upstream source code, and instead concentrates	on
       providing the best possible support for Western languages. It is	no
       longer fully NScripter-compatible, but remains an easy target to	port
       NScripter games to when localising them.

       The main	enhancements are support for Unicode and for formatted text,
       including multiple fonts	and styles, with proportional spacing,
       kerning,	ligatures, arbitrary text size and position, etc.

   Basic game structure
       Ponscripter games consist of a directory	containing scripts, either in
       NScripter format	or an extended derived format, plus other files
       (graphics, sound, fonts,	etc) on	which the script depends; these	may be
       packed into archives in the NScripter NSA or SAR	formats.

       Unlike other NScripter-derived interpreters, which attempt to a greater
       or lesser degree	to support Japanese filenames, Ponscripter requires
       that all	files have plain ASCII names. It's the only way	to be

   Script files
       Ponscripter is able to read two styles of script: native	and legacy.
       Native scripts are encoded in UTF-8, and	provide	all the	features
       documented below. Legacy	scripts	are an attempt to provide a modicum of
       backwards-compatibility:	they are NScripter-format scripts, in CP932
       (Microsoft's version of Shift_JIS) with some of the same	extensions as
       provided	by ONScripter-En. Many Ponscripter features are	disabled when
       processing a legacy script. There is little reason to use them, unless
       you want	to try to play an unported NScripter game using	proportional
       fonts. It's better to port where	possible.

       Script formats are distinguished	by filename. The following filenames
       are sought, in this order:

	   Native script in human-readable form.

	   Human-readable scripts can be multipart: the	engine checks all
	   numbers from	1 to 99	(both with and without leading zeroes, for
	   numbers below 10), and appends them to script 0.

	   Legacy script in human-readable form. Can be	multipart, as for
	   native scripts.

	   Legacy script, trivially obfuscated by xoring against a fixed
	   cyclic key with hexadecimal representation 79 57 0D 80 04.

	   Legacy script, trivially obfuscated using a key file.

	   The key must	be supplied using the --key-exe	parameter to
	   ponscr(6). This file	is used	to construct a simple permutation
	   table holding the plaintext equivalents to each byte	of the
	   obfuscated file.

	   Native script, trivially obfuscated by xoring against the constant
	   byte	0x84.

	   This	is the only form of obfuscation	supported for native scripts.
	   It does not pretend to provide any security,	but protects careless
	   tinkerers from accidental spoilers.

	   Legacy script, trivially obfuscated as for pscript.dat.

   Script structure
       Scripts are conventionally divided into three sections: directives,
       define, and game.

       In reality these	are parsing modes, rather than lexical sections, and
       control flow can	be mixed up with unscrupulous use of goto and skip
       commands, but best practice is to keep concerns strictly	separate.

       A skeleton script has the following form:

	   ; directives
	   ; define section
	   ; game section

   The Directives section
       The directives section is optional. It consists of one or two directive
       lines at	the very top of	the first script file; these are processed
       during interpreter initialisation.

       The first directive line	begins with a semicolon	and contains one or
       more comma-separated tags:

       mode NUM
	   Sets	the screen mode	to the 4:3 resolution with horizontal
	   dimension NUM. Values recognised are	800 (by	600), 640 (by 480),
	   400 (by 300), and 320 (by 240). The default is 640.

       value NUM
	   Sets	the global variable border; variables with indices greater
	   than	or equal to NUM	will become globals if the globalon command is
	   used. The default is	200.

       -*- anything -*-
	   Tags	of this	format are used	by popular text	editors	such as
	   emacs(1) to identify	the format of a	file.

	   Ponscripter ignores everything between the -*- delimiters, so users
	   of such editors can use this	feature	as expected.

       The second directive line, if present, has the form

	   ;gameid text

       This is used to specify the name	of the game. The gameid	thus defined
       is used when automatically selecting a path for saved games and other
       variable	data (see --save in ponscr(6)).

       Ideally you should always specify a gameid with this directive. If you
       don't, Ponscripter tries	to determine the name of the game by looking
       for a caption or	versionstr command; if that also fails,	a semi-unique
       identifier is generated based on	the length of the script.

       A complete directives section might thus	have the form

	   ;mode800,value500,-*- ponscripter -*-
	   ;gameid My Ponscripter game

       which would specify a game called "My Ponscripter game" that used an
       800x600 display,	treated	all variables indexed 500 and above as
       globals,	and would be easily identified as a Ponscripter	script.

   The Define section
       The define section is mandatory,	and is typically placed	at the start
       of the first script file, after any directives section and before the
       game section.

       It is introduced	with the label *define,	and continues until a game
       command is encountered.

       Code in this section is evaluated non-interactively at startup, and
       then only touched again if the definereset command is used. It contains
       definitions of things like aliases, arrays, windows, subroutines, and
       fonts. Most of the commands valid in this section are invalid in	game
       code, and vice versa.

   The Game section
       The game	section	is mandatory, and makes	up the bulk of the script. It
       typically follows the define section.

       It is introduced	with the game command, which transfers control
       immediately to the *start label (which must exist, and is normally the
       next thing in the script).

       Processing then remains in game mode until an end command, which
       terminates the program, or a definereset	command, which returns
       processing to define mode at the	*define	label.

       ponscr(6), ponscr-syntax(7), ponscr-ext(7)

       Existing	NScripter documentation, for a description of the basic
       operation of NScripter-style games and documentation of most of the
       functionality supported.	Most NScripter references are only available
       in Japanese, but	there is some English-language documentation at

Ponscripter 20111009		  2014-03-28			PONSCRIPTER(7)


Want to link to this manual page? Use this URL:

home | help