Documentation snippets that don't (yet) have a home

Graphics Speed
===============

  Under X11, you should try to run the programs on the same machine
  as the X server, so they can use shared memory to communicate.
  Currently, redraw is not optimized too well; the VCR will easily
  saturate a Fast Ethernet connection. If you have to run it over a
  network, switch down to 8 bpp (command-line option `-bpp 8'). This
  only has an effect if your X server actually offers an 8-bit visual.


Sound
======

  To turn off sound from the command line, set the environment variable
  "SDL_AUDIODRIVER" to an invalid value:
    C:> set SDL_AUDIODRIVER=.
    C:> playvcr ....
  resp.
    $ SDL_AUDIODRIVER=. playvcr ....

  Under Windows, use `set SDL_AUDIODRIVER=waveout' to make PlayVCR not
  use DirectX. Depending on your sound driver, you may have only one
  DirectX program running at a time.

  Sound settings (keys for the dialog in parentheses):
  - "Enable sound" (e): what its name says. When you don't have a soundcard
    or you used the above method to turn off sound, this has no effect of
    course.
  - "nn kHz" (1,2,4): set the mixing speed. 11 kHz is a bit better than the
    average telephone, 22 kHz is FM radio, 44 kHz is CD. I think 22 kHz
    is good enough for most of us. The higher this frequency, the higher
    the CPU and memory usage.
  - "16 bit" (b): if enabled, mix in 16 bit mode; if disabled, use 8 bit.
    16 bit sounds better than 8. Actually, 8 bit sounds *very* poor on
    my computer.
  - "Stereo" (s): ...
  - "Reverse stereo" (r): only works when Stereo is enabled: reverse the
    channels. Some people need this.
  - "Headphone" (h): only has an effect when Stereo is enabled: when you have
    headphones (not speakers) connected to your computer, stereo should
    sound better with this option. This does not affect how sound is played
    (i.e. through a "speaker" or "headphone" port if you have both).

  My preferred settings are "Enable", "22 kHz", "16 bit" and of course
  "Stereo". When your soundcard doesn't support a particular setting,
  it will be ignored. The actual configuration used will be logged on the
  console.

  There is not yet a volume switch. Use a normal mixer program and/or the
  volume switch of the speakers for that. SDL doesn't offer a platform-
  independant way of affecting volume other than manually mixing it down
  (which loses quality).


Plugins
========

  A plugin is defined by a *.c2p file. This is a regular .ini file
  that supports the following keywords:

    Name = <short name of plugin>
      (this is displayed in menus as the plugin title.)

    Description = <long description>
      (multiple Description lines yield multiple paragraphs.)

    Provides = <feature>, <feature>
    Requires = <feature>, <feature>
      (dependencies, see below)

    File = <file name>
      (a regular file that comes with the plugin)

    ScriptFile = <file name>
      (a script file that comes with the plugin; the file is
      automatically loaded as if by "Load".)

    ResourceFile = <resource file>
      (a resource (*.res) file that comes with the plugin; the file
      is automatically loaded as if it were listed at the end of
      cc-res.cfg.)

    HelpFile = <help file>
      A help (*.xml) file that comes with the plugin. Help pages from
      that file are made available to the UI.Help command.

    Exec = <script command>
      (a script command that is executed when the plugin is loaded.)

  Order of Script/Resource/Exec is significant, i.e. an Exec command
  can rely on a previous Script to be loaded.

  For installation, files from File/Script/Resource must reside in the
  same directory as the *.c2p file. When a file myplugin.c2p file is
  installed, it is copied into the directory ~/.pcc2/plugins/, and the
  referenced files are copied to ~/.pcc2/plugins/myplugin/.

  The name of the plugin definition file serves as the plugin
  identifier in technical contexts (scripts, command line).

  The Script and Exec commands will be executed within the plugin's
  context, see <pcc2interpreter.html#int:index:group:pluginproperty>.

  PlayVCR will only load Resource files.

  When uninstalling or updating a plugin, PCC2 will unload resource
  files provided by the plugin, but it will not unload scripts.


Dependencies
-------------

  PCC2 has a rudimentary dependency management system. Plugins can
  provide and require features. You cannot install a plugin if a
  dependency is missing, and you cannot remove a plugin if another one
  relies on it.

  Each feature is a word optionally followed by a version number, for
  example, "Coyote" or "Acme 1.0". Case is not significant. A plugin
  that requires a particular version number will also accept higher
  version numbers.

  Default features:
  - "PCC 1.99.25" (current PCC2 version, whichever is current)
  - each plugin definition file, say, "myplugin.c2p", provides the
    plugin identifier ("MYPLUGIN") as a feature


Zipped Plugins
---------------

  For simplicity, PCC2 also allows compressing all files of a plugin
  (including the *.c2p file) into a single zip file. To identify these
  files as plugins, we use the file extension .c2z (but normal .zip is
  accepted as well).



cc-res.cfg
===========

  Basically the same as PCC 1.x: a list of data sources to ask for
  stuff, later entries override earlier ones. Unlike PCC 1.x, we
  support different types of resources, specified by listing
  `type:source' in the file. The `type' is

     wp     Winplan `bmp' directory. source is the directory name
            (e.g. `C:\winplan\bmp')
     wpvcr  Winplan `wpvcr.dll' file. source is the complete path
            and file name (e.g. `C:\winplan\wpvcr.dll')
     res    PCC 1.x resource file (e.g. `cc256.res')
     dir    generic directory

  When the type is omitted, it defaults to `res' (like in PCC 1.x)

  A "generic directory" is like an addition to PCC2's "resource"
  directory. When PCC2 needs a resource, it looks into the resource
  directory (and all "dir:" entries) for a file "index.txt". This
  file contains assignments of resource Ids to file names. "s.vcr.beam"
  is defined to "wav/zap.wav", hence we look for a file "wav/zap.wav"
  in the resource directory and all "dir:" entries. See
  resource/index.txt for some more details.


Player Numbers
===============

  game/player.cc: getPlayerId() is the player whose viewpoint we assume.
  It is used
  - to tell who is "we" in VCR
  - from whom messages we write will come
  - whose password we'll change
  - whose ships are green on the map

  game/player.cc: getRealPlayerId() is the player who authenticated
  himself.

  GGameTurn can contain many players' data, so all functions that
  allow a switch to another object should use GGameTurn::isPlaying()
  instead of comparing to ::getPlayerId(). In addition, don't assume
  that every accessible object can interact with every other (like PCC
  1.x assumes).


Character Sets
===============

  PCC2 since beta12 uses Unicode internally. Since games use different
  character sets, it can translate those into Unicode and back. To enable
  this, invoke PCC2 using the option "-charset=XXX", where XXX is the
  character set name. For the command-line tools, the option is "-CXXX".

  Character sets we support as of 05/Jan/2011:
    cp437           MS-DOS codepage 437. Most DOS planeteers use this one.
    cp850           MS-DOS codepage 850 (western Europe).
    cp852           MS-DOS codepage 852 (eastern Europe)
    cp866           MS-DOS codepage 866, the cyrillic character set used
                    in DOS programs (e.g. VPA)
    cp1250          Windows codepage 1250 (eastern Europe)
    cp1251          Windows codepage 1251 (cyrillic)
    cp1252          Windows codepage 1252 (superset of latin1)
    latin1          Latin-1, the standard 8-bit character set used in
                    most Unices, and on the net
    latin2          Latin-2 (eastern Europe)
    koi8-r          Cyrillic character set, used on the net
    pcc1            for practical purposes, the same as cp437, but
                    replaces some of the more obscure characters with
                    additional symbols which are in latin1
  The character set definitions were taken from the mapping tables
  available on <ftp://ftp.unicode.org/Public/MAPPINGS/>.

  Character sets are used as follows:

  File                  Default character set           UTF-8 support
  --------------------  ------------------------------  --------------
  cc-res.cfg            Latin1                          yes
  chartX.cc             Game charset                    -
  cmdX.txt              Game charset                    yes
  fcodes.cc             Latin1                          yes
  hullfunc.cc           Latin1                          yes
  hullfunc.txt          Game charset                    yes
  mission.cc            Latin1                          yes
  mission.ini           Game charset                    yes
  msgX.ini              Game charset                    yes
  pcc2.ini              UTF-8                           -
  pconfig.src           Game charset                    yes
  resdir/index.txt      Latin1                          yes
  score.cc              Game charset                    -
  shiplist.txt          Game charset                    yes
  xtrfcode.txt          UTF-8                           -

  Rules are as follows:
  - files shared with other programs (including, obviously, the standard
    game files like shipX.dat and hullspec.dat, not listed above) use the
    game character set.
  - files that are exclusive to PCC2 use Latin1, or UTF-8 if needed.
  - text files can, regardless of their default encoding, use UTF-8, if
    they start with a UTF-8 byte-order-mark (EF BB BF). This is marked
    with the "UTF-8 support" column above. Note that if PCC2 writes such
    a file, it will always use the game character set.

  PCC2 comes with fonts that support all characters from the above
  code pages. That is, it supports Western European/American, Eastern
  European, and Cyrillic alphabets. If you need more, please tell me.



Special Keystrokes
===================

  Wheel mouse movement is handled as if it were a keystroke. No matter
  how fast you turn the wheel, one step is one step.

  The "close-me" button generates a vk_Quit keystroke. The general action
  is to do the equivalent of a "cancel" action and repost the event. Most
  times you can also press Ctrl-Shift-Q for the same result.

  Ctrl-Shift-S takes a screenshot.

  Finally, some keystrokes for debugging the UI:

  Ctrl-Shift-F draws frames around all widgets. They are color-keyed:
  - white: card groups, i.e. pages of a multi-page dialog
  - red: containers, i.e. widgets containing other widgets
  - green, slashed: spacers
  - yellow: remaining widgets

  Ctrl-Shift-L tries to visualize layout constraints. Press Ctrl-Shift-L,
  then click a widget. This will dim the widget's minimum size, draw a
  dashed line around its preferred size (most often these two are the same),
  and a tiny dotted line around its actual size. Colors are the same as for
  Ctrl-Shift-F, except for spacers, which are not available here at all.

  Ctrl-Shift-R completely redraws the screen.


Differences between PCC 1.x and PCC 2
======================================

  Differences which are not new features:

  PCC2 is not forgiving to Caps Lock. PCC 1.x accepts case-insensitive
  keystrokes, PCC2 does not. When a function is activated with 'u',
  that must be a lower-case 'u' (this is the same as VPA, Winplan, and
  most Unix programs). The button will, however, still be labelled
  with a capital 'U' (much like the key on your keyboard).

  Score statistics are stored in a new file (score.cc). This file
  format allows storage of additional score series, and supports
  32-bit range for all scores. PHost users will appreciate this. If
  score.cc does not exist, PCC2 will look for a stat.cc file from PCC
  1.x and import that; later on, it will no longer look at that file
  even if it's been updated in the meantime.

  Auto tasks are stored in a new file (scriptX.cc) which has the same
  header but totally different content as PCC 1.x's vmX.cc. Old files
  are NOT imported.


General Options
================

### Graphics Options

  Not all of those may work or have an effect on your system,
  depending on your graphics drivers and platform.

  -fullscreen      Request to run full-screen.
  -windowed        Request to run in a window (default).
  -bpp=N           Request color depth. N is 8, 16 or 32 (bits per pixel).
  -hw              Request hardware (unbuffered) canvas, which might
                   be faster.
  -size=WI[xHE]    Request screen resolution. If only WI is given,
                   assumes 4:3 aspect ratio. Default is 640x480.


### UI Options

  -resource=NAME   Add a resource file, as if it had been specified
                   in cc-res.cfg.
  -nomousegrab     Prevent that PCC2 grabs the mouse pointer in the
                   starchart screen. By default, the mouse will be
                   confined within the PCC2 window to support infinite
                   movement. With this option, mouse movement will not
                   have any effect in the starchart, but you'll be able
                   to switch windows etc. Useful for taking screenshots,
                   debugging, etc.


### Unix options

  -display=DPY     Set display to use for X11.


Environment Variables
======================

### SDL Variables

  These variables are implemented by libSDL, not by PCC2. Details may
  differ depending on your version of SDL.

  SDL_VIDEODRIVER
  - "aalib"
  - "dga" (Unix XFree DGA)
  - "directx" (Win32 DirectX)
  - "fbcon" (Unix framebuffer console)
  - "svgalib" (Unix SVGAlib)
  - "windib" (Win32 standard)
  - "x11" (Unix X11)

  SDL_AUDIODRIVER
  - alsa (Unix ALSA)
  - disk (output to disk)
  - dma (Unix OSS DMA)
  - dsound (Win32 DirectX)
  - dsp (Unix OSS standard)
  - esd (Unix Enlightened sound daemon)
  - waveout (Win32 WaveOut)

  SDL_DEBUG
  - if set to any value, error messages generated by SDL ('SDL_SetError')
    are logged to stderr. This includes errors handled and worked around
    by PCC2.

  SDL_AUDIO_PATH or AUDIODEV
  - path to /dev/dsp resp. /dev/sound/dsp, for Unix audio

  SDL_DISKAUDIOFILE
  - path to disk audio file when using SDL_AUDIODRIVER=disk; defaults to
    'sdlaudio.raw'


### PCC2 Variables

  These variables are implemented by PCC2.

  DEBUG_NUM_FRAMES
  - number of stackframes to show in backtrace, defaults to 10.

  LC_ALL, LC_CTYPE, LC_MESSAGES, LANG
  - language code (two letters). Used only under Unix.

  HOME
  - home directory. Used only under Unix.


-eof-
