ponscr — the Ponscripter novel-game interpreter
ponscr
[
options
]
[
script-path
]
[
script-file
]
This manpage documents the ponscr command itself. See Overview for an overview of other documentation.
ponscr should be invoked in one of two ways: either from within a game directory, or from an arbitrary location with a game directory specified as an option.
On Unix-like operating systems other than Mac OS X, it is recommended that you use the second option. Game packagers will ideally provide wrapper scripts that launch ponscr indirectly, so users will not have to know anything about the underlying interpreter.
On Mac OS X, the recommended approach is to create an application bundle containing a Ponscripter binary and the game data in the bundle's Resources directory; things will then “just work”.
On Microsoft Windows, the simplest approach is to store a Ponscripter binary in the game directory.
Up to two positional options may be provided, to give the root
path and script filename, like -r and
-s. If a parameter names a directory, it is
given an implicit -r; otherwise it is given
an implicit -s. If a filename is encountered
that includes a path, and no root path has been provided at
this point, then ponscr assumes that the
path part of the filename should be the root path.
If that doesn't do what you expected, use explicit options.
The following named options are recognised by
ponscr, in addition to the standard
--help and --version flags
(which should need no explanation):
-r path, --root path
Execute the game located at path.
If this option is not specified, any positional parameter will be used; otherwise the default behaviour on most platforms is to look for a game in the current working directory. The exception is OS X, where the Resources directory of the current application bundle is checked first if appropriate.
-s file, --script file
Use the script named file. If
a path is given, it is interpreted relative to the current
working directory; if no path is given, the file is sought
in the root path (determined as described above).
If this option is not provided at all, a script file is sought automatically in the root path. The filenames searched for, and their corresponding formats, are described in Overview. The same naming conventions are observed if this option is used, except that multipart scripts cannot currently be loaded this way, and unobfuscated scripts may have non-numeric names.
--save pathSet the path to use for saved data.
This option should not normally be used; a sensible default will be generated.
On most Unix-like platforms, saved games will be stored in
~/. (where
GAMEGAME is the name of the game being
played, or a semi-unique default if no name was provided.
See directives in Overview.)
On Mac OS X,
~/Library/Preferences/
is used instead.
GAME
Under Microsoft Windows, data is stored in
%COMMON_APPDATA%\GAME
-d, --debug--cdaudio--cdnumber number
--registry filePonscripter simulates NScripter's Windows registry access commands by reading from a fixed text file. This option is used to specify that file.
(This applies even on Microsoft Windows; real registry access is not supported, period.)
--dll filePonscripter simulates access to arbitrary NScripter DLL extensions by reading predefined function results from a fixed text file. This is enough to make games work, though often not enough to make them work properly.
Proper support for some extensions may be built into Ponscripter itself.
(This applies even on Microsoft Windows; real DLL extensions are not supported, period.)
--fullscreen--window--force-png-alpha--force-png-nscmask--force-button-shortcut
Disables four NScripter commands: spclclk,
getenter, getcursor,
and useescspc.
(This option was inherited from ONScripter; the reason for it is lost in the mists of time.)
--enable-wheeldown-advance--key-file filenscript.___ files and their
accompanying archives. This option is provided only for
use with legacy games; native Ponscripter games cannot be
obfuscated with this method. (What would the point be?
Anyone could adapt Ponscripter to extract the files.)
--disable-rescale--edit
On Microsoft Windows, all output to
stdout and stderr
is stored in files in the
%COMMON_APPDATA%\Ponscripter
Most fatal error messages are printed to stderr, which for 99% of users means the interpreter dies silently with no hint as to the cause. They should be displayed with some kind of popup dialog; preferably a platform-native one, where feasible.
The entire design of this interpreter is arguably a bug.
The behaviour of PNG images is not well-defined, since NScripter does not support them directly. Historically, some interpreters/plugins have expected them to use alpha channels for transparency, while others have expected them to use NScripter-style masks like BMP files do (i.e. the bitmap is double width, with the left-hand side being the full-colour image, and the right-hand side being a greyscale mask).
By default, Ponscripter uses a heuristic approach: if a PNG
has an alpha channel that is not completely opaque, that is
used, otherwise an NScripter-style mask is used if present.
If this fails to work for some images, and you cannot fix the
images in question directly, then you can use the
--force-png-alpha or
--force-png-nscmask options to overrule the
automatic detection.