PONSCR-EXT(7) Ponscripter manual PONSCR-EXT(7)NAMEponscr-ext - Ponscripter extension commands
DESCRIPTION
This page documents Ponscripter-specific extensions, i.e. commands that
are not present (or operate differently) in NScripter or ONScripter.
See ponscripter(7) for an overview of other documentation.
Detecting Ponscripter
It may occasionally be desirable to have a single script that will load
in both Ponscripter and other NScripter-type interpreters. (The test
scripts in the Ponscripter distribution are an example of such a case.)
A script can detect whether it is running under Ponscripter by defining
a numalias:
numalias PONSCRIPTER, 0
Ponscripter treats this as a special case, and gives the numalias the
value 1 instead, so platform-specific code can then be included by
testing the value of PONSCRIPTER and branching as appropriate.
Fonts
h_mapfont slot, filename, [metrics]
Maps filename to font slot number slot (0-7).
For TrueType and OpenType fonts, filename should name the .ttf or
.otf file. For Type 1 fonts, filename> should name the .pfa or .pfb
file, and the metrics argument should be used to provide the
corresponding .afm file.
Filenames are relative to the game's data path. If a file is not
found, it is then sought within a fonts subdirectory of the data
path, then in the game's archive, and then the game binary itself
is checked in case the font has been embedded there. Finally, for
compatibility, Ponscripter checks for a file named default.ttf in
the game's data path, and uses that if it exists. Note that at no
stage does Ponscripter look at the fonts installed on the user's
computer; games must distribute their own fonts. Note also that
fonts are loaded lazily, so the point of failure if a file is
missing will be when that font is first used, not when this command
is executed.
The intended convention is that the eight font slots should
represent two typefaces (a text face and a display face), each with
regular, italic, bold, and bold-italic styles. These are assigned
in ascending order: slot 0 (the default face) should be the regular
text font, slot 1 the italic text font, slot 4 the regular display
font, etc. You can, of course, assign the fonts however you like,
but following the convention permits straightforward use of
mnemonic formatting tags. See “Font selection tags” in ponscr-
syntax(7) for details of font selection.
Mapping fonts in this way is optional. If a slot is used that has
not had a font assigned to it, the default filename will be
faceN.ttf, where N is the slot number.
h_rendering hinting, positioning, [rendermode]
Configures Freetype text rendering.
hinting should be one of the following barewords:
none
glyphs are unhinted (default)
full
Freetype hinting is used
light
Light hinting is used
The optimum settings depend on the fonts in use. In general,
Freetype hinting makes TrueType fonts look hideous, but it does
sometimes help with Type 1 fonts.
positioning should be the bareword integer, which causes characters
to be aligned to whole pixels. The alternative is float, which uses
subpixel positioning and would in theory give better spacing, but
has never worked properly and generally looks awful.
The optional rendermode parameter can be used to override the
Freetype rendering mode. It should be one of the barewords light or
normal. By default, light rendering is used for light hinting, and
normal rendering otherwise; this should always be what you want.
h_fontstyle string
Sets the default text styling. This command is equivalent to
inserting ~dstring~ at the start of every subsequent text display
command (though it has no effect on sprites).
Only font style tags may be used; size and position tags are not
supported.
For example, to set an entire section of the game in your italic
display font, you could use the code
h_fontstyle ^si^
^Your text here\
^Several pages in italic display font\
h_fontstyle ^d^ ; to reset
h_ligate input, action, h_ligate preset
Add or remove shortcut sequences. (See “Ligatures and shortcuts” in
ponscr-syntax(7).)
The two-argument form of this command adds or removes a single
sequence. input is a string representing the sequence; action is
either the bareword remove, which causes any shortcut associated
with the sequence to be undefined; an integer, which is taken as
the Unicode codepoint to be inserted when the sequence is
encountered; or a string, the first character of which is inserted
when the sequence is encountered. For example:
h_ligate "fi", 0xfb01
The one-argument form is used to apply preset settings. preset is
one of the following values:
none
Clears all definitions, including the defaults. To restore the
default definitions, use default as well (see following).
default
Redefines the standard shortcuts, i.e. curly quotes and the
#-sequences used to escape some special syntax.
all
Defines all sequences mentioned in this section.
f_ligatures
Defines ligatures for fi, fl, ff, ffi, and ffl.
punctuation
Defines the following shortcuts:
... ellipsis
-- en dash
--- em dash
(c) copyright symbol
(r) registered trademark
symbol
(tm) trademark symbol
++ dagger
+++ double dagger
** bullet
%_ non-breaking space
%- non-breaking hyphen
%. thin space
Text controls
Sprite controls
Debugging
Soft subtitles
Extensions to existing commands
SEE ALSOponscripter(7)Ponscripter 20111009 2016-02-18 PONSCR-EXT(7)
