Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
PONSCR-EXT(7)		      Ponscripter manual		 PONSCR-EXT(7)

       ponscr-ext - Ponscripter	extension commands

       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.

       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:

	       glyphs are unhinted (default)

	       Freetype	hinting	is used

	       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

	   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

	   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:

	       Clears all definitions, including the defaults. To restore the
	       default definitions, use	default	as well	(see following).

	       Redefines the standard shortcuts, i.e. curly quotes and the
	       #-sequences used	to escape some special syntax.

	       Defines all sequences mentioned in this section.

	       Defines ligatures for fi, fl, ff, ffi, and ffl.

	       Defines the following shortcuts:

	       ...    ellipsis
	       --     en dash
	       ---    em dash
	       (c)    copyright	symbol
	       (r)    registered trademark
	       (tm)   trademark	symbol
	       ++     dagger
	       +++    double dagger
	       **     bullet
	       %_     non-breaking space
	       %-     non-breaking hyphen
	       %.     thin space

   Text	controls
   Sprite controls
   Soft	subtitles
   Extensions to existing commands

Ponscripter 20160615		  2021-11-28			 PONSCR-EXT(7)


Want to link to this manual page? Use this URL:

home | help