PONSCR(6) Ponscripter manual PONSCR(6)NAMEponscr - the Ponscripter novel-game interpreter
SYNOPSISponscr [options] [script-path] [script-file]
DESCRIPTION
This manpage documents the ponscr command itself. See ponscripter(7)
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.
OPTIONS
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 ponscripter(7). 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 path
Set 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 ~/.GAME
(where GAME is the name of the game being played, or a semi-unique
default if no name was provided. See “directives” in
ponscripter(7).)
On Mac OS X, ~/Library/Preferences/GAME is used instead.
Under Microsoft Windows, data is stored in %COMMON_APPDATA%\GAME.
-d, --debug
Enable debugging output. Repeating this option may increase the
verbosity even further.
--cdaudio
Use CD audio, if available.
--cdnumber number
Choose the CD-ROM drive number.
--registry file
Ponscripter 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 file
Ponscripter 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
Force Ponscripter to start in fullscreen mode.
--window
Force Ponscripter to start in windowed mode.
--force-png-alpha
Always use alpha channels for PNG transparency, even if an image
looks as though it might contain an NScripter-style mask. See
“notes” below.
--force-png-nscmask
Always use NScripter-style masks for PNG transparency, even if an
image contains an alpha channel. See “notes” below.
--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
Allow mouse-wheel-down events to advance text.
--key-file file
Specify key file to use to read obfuscated nscript.___ 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
This is an ONScripter option that I've never used.
--edit
This is an ONScripter option that I've never used.
BUGS
· On Microsoft Windows, all output to stdout and stderr is stored in
files in the %COMMON_APPDATA%\Ponscripter directory. These are
clobbered each time the program is launched and deleted upon
termination if empty. Output is never printed to the console, even
if the interpreter was launched from the command line, and the
behaviour if multiple instances are launched at the same time is
undefined.
· 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.
NOTES
PNG transparency
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.
SEE ALSOponscripter(7)Ponscripter 20111009 2014-03-28 PONSCR(6)
