NAME

ponscr - the Ponscripter novel-game interpreter

SYNOPSIS

ponscr [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.