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.
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.
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 portable.
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.
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 ; define section game *start ; game section end
The first directive line begins with a semicolon and contains one or more comma-separated tags:
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.
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
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.
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.
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.
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 http://nscripter.insani.org.