Read Me

Pentagram Documentation
last changed: 3 August 2007 (GMT)

The latest version of this document can be found at http://pentagram.sourceforge.net/docs.php


1. Building CVS
1.1. Build dependencies
1.2. Linux/Unix
1.3. Windows
1.4. Mac OS X

2. Configuration
2.1. Quick guide
2.2. Advanced Configuration
2.3. Optional MIDI settings for Linux

3. Movement and Keys
3.1. Movement
3.2. Keyboard commands

4. Other stuff
4.1. Console commands
4.2. Supported games and versions

5. Changes to the Documentation
5.1. - 4 September 2008
5.2. - 3 August 2007
5.3. - 19 February 2006
5.4. - 22 May 2005
5.5. - 21 May 2005
5.6. - 14 October 2004


--------------------------------------------------------------------------------

1. Building CVS
1.1. Build dependencies
Before you build Pentagram, make sure you have the following tools/libraries.
* SDL;
* SDL_ttf;
* zlib;
* libpng;
* for Linux/Unix, you need autoconf and automake.



1.2. Linux/Unix
1. Run the "bootstrap" script to create the "configure" script: ./bootstrap
2. Now run configure: ./configure
3. Finally, start the build as usual: make



1.3. Windows
nothing here yet


1.4. Mac OS X
Under OS X, the dependencies are built into the application bundle as embedded libraries. Pentagram provides makefiles to build the dependencies appropriately. Internally, the OS X specific makefiles use normal unix-style configure & make to build Pentagram and all dependencies.
1. Run the "bootstrap" script to create the "configure" script: ./bootstrap
2. Build all dependencies: make -f Makefile.macosx deps
3. Build Pentagram: make -f Makefile.macosx build
4. Build Pentagram.app: make -f Makefile.macosx bundle
5. Build disk image: make -f Makefile.macosx image
6. The disk image is located in the build directory and contains the universal binary




--------------------------------------------------------------------------------

2. Configuration
2.1. Quick guide
Pentagram needs a pentagram.ini file to point it to the game data files. In Linux, pentagram.ini has to be in the ~/.pentagram directory. In Windows, it has to be in the current directory. In OS X, it has to be in the ~/Library/Application Support/Pentagram directory A sample pentagram.ini is included below (this is all that is needed at the moment to run Pentagram). Comments are marked with # and are above the ini-entries. You can copy/paste these settings with the comments to your ini file as Pentagram will ignore lines beginning with #.

[u8]
# replace 'path to U8 directory' with the directory containing 'u8.exe'
path=path to U8 directory



2.2. Advanced Configuration
Right now Pentagram assumes some default settings that don't need to be set to make Pentagram work. The settings below are these default settings.

[pentagram]
defaultgame=u8
fullscreen=no
# Width of the game resolution.
scalex=320
# height of the game resolution.
scaley=240
# Select the scaler you want to use. Currently you can choose between
# point, bilinear, scale2x, 2xSaI, hq2x.
scaler=point
# The game resolution is scaled to this width.
width=640
# The game resolution is scaled to this height.
height=480
bpp=32
# Enable this to use the BitStream Vera font for conversations and object descriptions.
ttf=no
# If you don't specify midi_driver, Pentagram will automatically select one,
# based on your platform.
# (Note: Windows will only work on Windows. CoreAudio only on Mac OS X.
# Alsa is Linux-only and UnixSeq will only work on Unix variants.)
# See further down for more options on Linux.
midi_driver=disabled/windows/fmopl/timidity/alsa/unixseq/coreaudio
# Enable this to skip the intro of U8 and initial conversation with Devon.
skipstart=no
# Conversation speed. Higher is slower.
textdelay=8
[u8]
# replace 'path to U8 directory' with the directory containing 'u8.exe'
path=path to U8 directory
# replace with the directory you want Pentagram to save games to.
# (no, loading of the original's savegames is not supported)
save=path to U8 savegames directory

You may also override most settings under [pentagram] by writing them under [u8]. Except for defaultgame all can be overriden. Right now this is not necessary as we only support U8 but if we start to support other games it might come in handy.


2.3. Optional MIDI settings for Linux
MIDI used on Linux might need some fine tuning in pentagram.ini to work correctly. Below are the settings you can configure.

[pentagram]
# If you don't specify midi_driver, Pentagram will automatically select one,
# based on your platform.
#(Note: Windows will only work on Windows. CoreAudio only on MacOSX.)
midi_driver=disabled/windows/fmopl/timidity/alsa/unixseq/coreaudio
# You may need to set timiditycfg if you choose midi_driver=timidity.
timiditycfg=path to timidity.cfg
# You may need to set alsa_port if you choose midi_driver=alsa.
alsa_port=alsa:port
# You may need to set unixseqdevice if you choose midi_driver=unixseq.
unixseqdevice=/dev/sequencer




--------------------------------------------------------------------------------

3. Movement and Keys
3.1. Movement
* Double-click with the right mouse button will make the Avatar find a path to the selected spot.
* Left-click on NPCs or objects to identify them.
* Double-left-click on NPCs or objects to initiate conversations or use the item.
* On pressing the right mouse button down the Avatar walks or runs (depending on distance between cursor and Avatar).
* Pressing right and left mouse button, makes the Avatar jump or while running a running jump.
* You can also move the Avatar with the keypad. Details are in the keycommands table below.

Note that on Mac OS you have to hold down the 'Cmd' key and the mouse button to have the functionality of a right mouse button.


3.2. Keyboard commands
All key commands of Pentagram can be changed by editing u8bindings.ini or via the options menu in the game. 'KP' means keypad.

Default keyboard commands
~ : hides/restores console
arrow keys : moves Avatar around the map (no walking)
home,end : moves Avatar vertically 
KP : Avatar walks (one animation cycle)
Shift+KP : Avatar runs (one animation cycle)
Ctrl+KP : Avatar makes a little step (one animation cycle)
Alt+KP : Avatar jumps long (one animation cycle)
s : toggles "avatarInStasis"
t : outputs kernel/usecode/world/location stats to the console
e : toggles editor items
h : highlights any item you are "hitting", colliding with
i : open backpack
z : open paperdoll/status
r : recall
c : switches combat mode on/off
ESC : main menu
alt+x : quit
ctrl+q : quits without confirmation 
backspace : close all open containers
F7 : Quicksave (savegames are not yet stable!)
F8 : Quickload
F11 : Shapeviewer
F12 : toggles frame by frame
shift : quarter speed mode. needs to be held down
[ : clears the screen, multiple presses show the paint order
] : above backwards



--------------------------------------------------------------------------------

4. Other stuff
4.1. Console commands
Pentagram has a debugging console with various useful commands. A selection is listed below.

Console commands
GUIApp::quit : quit
ConsoleGump::toggle : open/close console
Cheat::heal : heal the avatar
Cheat::equip : equip the avatar with magic armour
Cheat::maxstats : set str/dex/int to 25
Cheat::toggleInvincibility : toggle avatar invincibility
MainActor::name <name> : set avatar name
MainActor::teleport <map> <x> <y> <z> : teleport to coordinates
MiniMapGump::toggle : show/hide minimap


4.2. Supported games and versions
At the moment we only support the English versions of Ultima 8, both pre-patch and post-patch. The German, French, Spanish versions should also work, but are less well-tested. The Japanese version has a chance of working, but has hardly been tested at all.



--------------------------------------------------------------------------------

5. Changes to the Documentation
5.1. - 4 September 2008
1.4. Mac OS X: replaced old build instructions.


5.2. - 3 August 2007
4.1. Console commands: added (short) list of console commands.


5.3. - 19 February 2006
4.2. Supported games and versions: updated status of non-English U8.


5.4. - 22 May 2005
2.2. Advanced Configuration some more configurations added. 2.3. Optional MIDI settings for Linux added.


5.5. - 21 May 2005
cleaned up outdated sections


5.6. - 14 October 2004
2.2. Advanced Configuration enable font replacement.