search

litchie / exult-ios

Exult ( http://exult.sourceforge.net/ )
GNU General Public License v2.0
42 stars 8 forks source link

readme

Exult Documentation last changed: 8 December 2018(GMT)

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

  1. Introduction 1.1. Exult Version 1.2. What is Exult? 1.3. Terms we use in regard to Exult and Ultima 7

  2. Configurations 2.1. Installation 2.2. Location of exult.cfg 2.3. Settings in exult.cfg 2.4. Path-Settings 2.5. Path-Settings for Windows 2.6. Path-Settings for Mac OS X 2.7. Path-Settings for *nix based systems 2.8. Advanced Configuration: Using both the original and the Add-Ons 2.9. Command line options 2.10. Error Log

  3. Audio 3.1. Music 3.2. MIDI Music 3.3. Abilities and limitations of the MIDI music engine 3.4. Windows MIDI Mapper 3.5. OS X CoreMidi device ID 3.6. Digital Music 3.7. Digital Wave Sound Effects 3.8. All-in-One Audio Data pack and installers 3.9. Installation of the digital music packs 3.10. Installation of the digital wave sound effects 3.11. Speech 3.12. Turn off Audio 3.13. Linux and Audio

  4. Video 4.1. Resolution 4.2. Fill modes 4.3. Higher resolution is cheating 4.4. Scaler

  5. Movement and Keys 5.1. Movement 5.2. Keyboard commands 5.3. Cheat keys 5.4. Map Editing keys

  6. ShortcutBar, Notebook and Screenshots 6.1. ShortcutBar for one or double click actions 6.2. Using the Notebook 6.3. The automatic Notebook 6.4. Screenshots

  7. Exult Setup and Game Menu 7.1. Access to the Exult Setup and Game menu 7.2. Load/Save Game 7.3. Video Options 7.4. Audio Options 7.5. Gameplay Options 7.6. Misc Options 7.7. Quit

  8. Mods and Patches 8.1. Introduction to Mods and Patches 8.2. Installing Mods 8.3. Installing Patches 8.4. Adapting the location of Mods and Patches 8.5. Where to find the savegames of modded games 8.6. Exchanging Savegames between original games and Mods

  9. iOS Guide 9.1. The port to iOS 9.2. Installing Exult on your iPhone/iPad 9.3. Installing the games on your iPhone/iPad 9.4. Installing sfx and digital music 9.5. iOS controls 9.6. Additional iOS settings

  10. Installing the original Ultima VII games for use with Exult 10.1. Installing the floppy disks of BG/SI on Windows 10.2. Installing the floppy disks of the Add-Ons FoV/SS on Windows 10.3. Installing the floppy disks of BG/SI using DOSBox 10.4. Installing the floppy disks of the Add-Ons FoV/SS using DOSBox 10.5. Manual installation of the BG floppy disks 10.6. Manual installation of the SI floppy disks 10.7. Installing the CD-ROM versions of Ultima VII 10.8. Fixing permissions of Ultima Collection on *nix systems 10.9. Using the version for Windows from GOG.com 10.10. Using the version for OS X from GOG.com

  11. Credits and Contact 11.1. Thanks 11.2. Contacting us

  12. Changes to the Documentation 12.1. - 08 December 2018 12.2. - 14 April 2016 12.3. - 17 March 2016 12.4. - 13 March 2016 12.5. - 19 March 2015 12.6. - 09 May 2014 12.7. - 19 December 2013 12.8. - 21 November 2013 12.9. - 11 February 2013 12.10. - 15 January 2013 12.11. - 01 January 2013 12.12. - 16 December 2012 12.13. - 14 November 2012 12.14. - 28 October 2012 12.15. - 01 December 2011 12.16. - 16 March 2011 12.17. - 19 February 2011 12.18. - 24 January 2011 12.19. - 23 January 2011 12.20. - 13 October 2010 12.21. - 30 August 2010 12.22. - 25 August 2010 12.23. - 15 August 2010 12.24. - 28 April 2010 12.25. - 11 March 2010 12.26. - 10 March 2010 12.27. - 08 March 2010 12.28. - 16 July 2009 12.29. - 03 June 2009 12.30. - 20 May 2009 12.31. - 19 May 2009 12.32. - 18 May 2009 12.33. - 28 April 2009 12.34. - 21 October 2007 12.35. - 08 April 2006 12.36. - 14 March 2005 12.37. - 14 August 2004 12.38. - 23 May 2004 12.39. - 11 February 2004 12.40. - 12 December 2003

  1. Introduction 1.1. Exult Version

This documentation is for the 1.5.0 Git version of Exult. If you have another Exult version, its documentation can be found where you installed the release.

1.2. What is Exult?

Ultima 7, an RPG from the early 1990's, still has a huge following. But, being a DOS game with a very nonstandard memory manager, it is difficult to run it on the latest computers. Exult is a project to create an Ultima 7 game engine that runs on modern operating systems, capable of using the data and graphics files that come with the game. Exult is written in C++ and runs on, at least, Linux, Mac OS X and Windows using the SDL library to make porting to other platforms relatively easy. The current version supports all of "Ultima 7: The Black Gate" and "Ultima 7 part 2: The Serpent Isle", allowing you to finish both games. This is only possible due to the work done by other fans who have decoded the various Ultima 7 data files, especially Gary Thompson, Maxim Shatskih, Jakob Schonberg, and Wouter Dijkslag. Exult aims to let those people who own Ultima 7 (copyright 1993) play the game on modern hardware, in as close to (or perhaps even surpassing) its original splendor as is possible. You need to own "Ultima 7: The Black Gate" and/or "Ultima 7: Serpent Isle" and optionally the add-ons (not required to run) in order to use Exult, and we encourage you to buy a legal copy.

1.3. Terms we use in regard to Exult and Ultima 7

We are using many terms in this documentation, the FAQ and other documentation files that people may have difficulties to understand. Here we will try to give some explanations.

  1. Configurations 2.1. Installation

Word of advice: Don't mix the files from BG and SI. Note: If you run Exult on an original Ultima7 game which you're actually in the middle of playing, your game will be overwritten. Since Exult's files have a different format, there is no way to convert those original save games.

2.2. Location of exult.cfg

Exult stores its setting in the file exult.cfg. The location of the file varies depending on the Operating System and in the case of Windows OS it also depends on the version of Windows.

2.3. Settings in exult.cfg

Most of the options in Exult can be changed from the Setup menu when you run Exult or via the Game Options menu. Exult stores these changes in a configuration file. Except for changing paths to the games you shouldn't need to edit the file. Very few options need manual editing. Note: the settings in exult.cfg are the same on all operating systems (except when explicitly stated below). The file uses a simple hierarchical XML-like syntax, which should be simple to understand and modify. Take care though. Handling of syntax errors in this file is not well tested. The file looks like this (do not copy the **and following - these are my remarks), options you can only change manually are colored in purple. Note: yes means enabled, no means disabled

1 **save games are now compressed as zip files. 0 disables compression, 1 enables it, 2 compresses even a bit better. Default is 1. data **this is where Exult stores its data files that are needed to run (e.g. exult???.flx files) data/music **optional. Location of digital music. See also 3.6. path_to/blackgate **path to the BG game. See 2.4. before changing it. optional_path **optional. Default is the same as , change to whatever you like. Also see 2.4. before changing it. path_to/blackgate/static **optional. See 2.4. before changing it. optional_path/gamedat **optional. See 2.4. before changing it. (default) **configure custom key bindings or leave the (default) - see 5.2. (default) **set path to a custom autonotes file or leave the (default) - see 6.3. jmsfx.flx **optional setting see 3.7. for configuration optional_path/mods **optional. See 8.4. optional_path/patch **optional. See 8.4. path_to/serpentisle **path to the SI game. See 2.4. before changing it. optional_path **optional. Default is the same as , change to whatever you like. Also see 2.4. before changing it. path_to/serpentisle/static **optional. See 2.4. before changing it. optional_path/gamedat **optional. See 2.4. before changing it. (default) **configure custom key bindings or leave the (default) - see 5.2. (default) **set path to a custom autonotes file or leave the (default) - see 6.3. jmsisfx.flx **optional setting see 3.7. for configuration optional_path/mods **optional. See 8.4. optional_path/patch **optional. See 8.4. -1 **activates the status faces and the position on the screen. -1 disable,0 left, 1 middle, 2 right. -1 **with this enabled all the text in the games have a colored background to improve readability. 0 gives a solid light gray, 1 dark purple, 2 bright yellow, 3 light blue, 4 dark green, 5 dark red, 6 purple, 7 orange, 8 light gray, 9 green, 10 yellow, 11 pale blue, 12 dark green, 13 red, 14 bright white, 15 dark gray, 16 white. -1 disables this. no **enables faster cursor movement in full screen mode. yes **enables using of the middle mouse button. no no double **right-clicking lets the Avatar walk automatically to where you clicked. it defaults to double click but you can opt for a single click or disable it. no **when in cheat mode allow to scroll the gameview with the mouse- yes **yes doesn't pause the game when gumps are shown. yes **enable/disable cheats no **yes enables SI style paperdolls in BG. 0 **0/25/50/75/100 percentage of how smooth the game scrolls when the avatar moves. 0 disables smooth scrolling and uses the "jerky" scrolling of the original game. no **this skips the scripted first scene in BG and SI during which you can't move. no **this skips the splash screen, the intro before you get to the game menu. Disabling it brings you straight to the game menu. yes **yes forces the party to walk in a formation similar to the original game. See FAQ.txt in the FAQ. 8 **Controls how far the Avatar will move before Exult recalculates the Avatar's and the party's movement. Bigger # avoids jerkiness, but may cause other problems. no **Dropping stacks of items will drop the whole stack without asking how many when enabled. Hold 'Ctrl' while dropping to split the stack. no **Automatically fill the notebook with entries when game flags are set. See 6.3. 0 **0 is default, negative values make combat easier, positive makes it harder. It affects the chance of a hit, and the HP's lost if a hit occurs. Ranges from -3 to 3 (easiest to hardest). original **original or keypause. On keypause the game pauses when you hit space so you can make changes in combat. no **no is default. With yes you see the hit points of NPCs in brackets after their name. normal **with normal the Avatar behaves as in the original game. When he is charmed he will be highlighted as charmed and the status icon will show but you can control him as usual. "hard" will neither allow the player to control the Avatar nor access his inventory. no **options are yes/translucent (will not be translucent if not on map, default on iOS) black **outline around shortcutbar buttons only if the bar is on the map. Options are: no, green, white, yellow, blue, red, purple, black (default). yes **hides ShortcutBar buttons the party doesn't have. no shows those buttons greyed out. no **options are yes/no/verbose. This is used to trace the executed Usecode. (You shouldn't need this unless you are a programmer.) no **options are yes/no. Used to trace intrinsics. (You shouldn't need this unless you are a programmer.) no **options are yes/no. If enabled, show combat messages.

2.4. Path-Settings

The way Exult generates default paths (for gamedat, savegames, mods, patches) has changed since Version 1.2. It will not write these paths to exult.cfg but use them automatically. The location where Exult expects those, and if needed, will create those folders is similarly depending on the Operating System as the location of exult.cfg (see 2.2. Location of exult.cfg ). If you were to override these paths you would need to change the following tags (you can substitute gamename with the "known games" - see 1.3.):

data path_to/gamename path_to/gamename/static optional_path optional_path/gamedat path_to/gamename/mods path_to/gamename/patch But normally you don't need to. On starting up, Exult will first read which games are available as configured in exult.cfg. Then it will use the setting and assume that is /static. For , , and Exult will assume Operating System specific paths. These folders are used for: * the most important folder. In this folder are the files Exult absolutely needs to run. We also check the checksums of these files to make sure that Exult uses the correct ones. * the second most important folder. In there you have the data files from the original game. You should never touch these files. * this is where Exult stores your savegames. * contains the (dynamic) data for the game you're currently playing. It's where the "journey onward" and "quicksave" 'savegame' is stored. * here mods for games are saved to. More information on this at 8.1. Introduction to Mods and Patches * Patches for games are saved here. More information on this at 8.1. Introduction to Mods and Patches Some notes for all Operating Systems: * On Windows all of these settings, except for the setting, are optional and not required, Exult will sort this out on its own. * On *nix and OS X you might even not need to touch the setting, if you stick to our standard gamenames. * You can either use the relative (e.g. ./ultima7) or absolute (e.g. c:\exult\ultima7) path to point to the correct folder. The relative path uses the exult.exe, exult binary or Exult.app as base. * Better don't use spaces in the path (e.g. c:\exult\the black gate\). Some people seem to have reported problems with that. * Path settings in exult.cfg are the same on all operating systems. Of course you need to make adjustments on *nix based systems when you enter the absolute path. * Exult and Exult Studio don't trust the exult.cfg 100% and will recognize which games you entered the path for. This means, that if you entered the path to SI in the Exult and Exult Studio will not be fooled. * Don't ever point and to the same folder. 2.5. Path-Settings for Windows On Windows XP, Vista, 7 and 10, Exult uses the special system folder LOCAL_APPDATA: data path_to\gamename path_to/gamename/static LOCAL_APPDATA\Exult\gamename LOCAL_APPDATA\Exult\gamename\gamedat path_to\gamename\mods path_to\gamename\patch Note that on Windows 2000 and XP LOCAL_APPDATA\Exult translates to "C:\Documents and Settings\YourUsername\Local Settings\Application Data\Exult" and on newer Windows (Vista, 7, 10) to "C:\Users\YourUsername\AppData\Local\Exult". Also not that you can quickly access this folder by executing "shell:Local AppData\Exult" in the "Run" entry of the Startmenu (or the "Run or Search" entry of the newer Windows Startmenu). For now Exult's data folder is always installed into the same folder where you installed Exult to (default is C:\Program Files\Exult). Also not that in contrast to Mac OS X and *nix systems there is no default path, where Exult looks for the games. You have to choose that folder yourself, but the installer will ask you for the BG and SI folder to set your paths up. Example: User named FooBar on Windows XP. BG is installed to C:\Ultima7\blackgate and SI is installed to C:\Ultima7\serpentisle. The installer of Exult asks for the location of these two games and automatically saves that to exult.cfg. The installer saves exult.cfg to C:\Documents and Settings\FooBar\Local Settings\Application Data\Exult\exult.cfg. Exult gets installed to C:\Program Files\Exult. When you save a game in BG the savegame will be saved to C:\Documents and Settings\FooBar\Local Settings\Application Data\Exult\blackgate\exult00bg.sav, for SI to C:\Documents and Settings\FooBar\Local Settings\Application Data\Exult\serpentisle\exult00si.sav. If you install for example the keyring mod, you copy the contents of the Keyring.zip to C:\Ultima7\blackgate\mods. When you save a game with the Keyring mod, this savegame will be found in C:\Documents and Settings\FooBar\Local Settings\Application Data\Exult\blackgate\mods\keyring\exult00bg.sav Example: User named FooBar on Windows 10 64bit. BG is installed to C:\Ultima7\blackgate and SI is installed to C:\Ultima7\serpentisle. The installer of Exult asks for the location of these two games and automatically saves that to exult.cfg. The installer saves exult.cfg to C:\Users\FooBar\AppData\Local\Exult\exult.cfg. Exult gets installed to C:\Program Files (x86)\Exult. When you save a game in BG the savegame will be saved to C:\Users\FooBar\AppData\Local\Exult\blackgate\exult00bg.sav, for SI to C:\Users\FooBar\AppData\Local\Exult\serpentisle\exult00si.sav. If you install for example the keyring mod, you copy the contents of the Keyring.zip to C:\Ultima7\blackgate\mods. When you save a game with the Keyring mod, this savegame will be found in C:\Users\FooBar\AppData\Local\Exult\blackgate\mods\keyring\exult00bg.sav 2.6. Path-Settings for Mac OS X On Mac OS X Exult uses a couple of different folders to follow Apple's guidelines: /Library/Application Support/Exult/data /Library/Application Support/Exult/gamename /Library/Application Support/Exult/gamename/static ~/Library/Application Support/exult/gamename ~/Library/Application Support/exult/gamename/gamedat /Library/Application Support/exult/gamename/mods /Library/Application Support/exult/gamename/patch Note that on OS X Exult also has a default folder (/Library/Application Support/Exult/) for Exult's data and the files of the games. On purpose this folder is not in the User-only space, so other users on the same mac can play the games and use the Exult.app. But you will need to follow our gamename standard when you name the game folders, see 1.3. Terms we use in regard to Exult and Ultima 7 , otherwise Exult will not find them there. Another specialty on OS X is that the Exult.app comes bundled with the Exult data, so Exult will first use the data in the Exult.app and then use the data in the default location (/Library/Application Support/Exult/data) or the location written down in exult.cfg's . This means that you can copy the sfx files and the digital music folder into the app bundle (Exult.app/Contents/Resources/data) and Exult will automatically use these. Example: User named FooBar on Mac OS X 10.6. BG is installed to /Library/Application Support/Exult/blackgate and SI is installed to /Library/Application Support/Exult/serpentisle. The app Exult.app is saved to /Applications. When you run Exult it will automatically recognize that BG and SI are installed. You do not need to edit exult.cfg, which is saved to /Users/FooBar/Library/Preferences/exult.cfg. When you save a game in BG the savegame will be saved to /Users/FooBar/Library/Application Support/exult/blackgate/exult00bg.sav, for SI to Users/FooBar/Library/Application Support/exult/serpentisle/exult00si.sav. If you install for example the keyring mod, you copy the contents of the Keyring.zip to /Library/Application Support/Exult/blackgate/mods. When you save a game with the Keyring mod, this savegame will be found in /Users/FooBar/Library/Application Support/exult/blackgate/mods/keyring/exult00bg.sav. Please be aware of the difference between /Library/... and ~/Library/... In the root of your OS X system hard drive is the folder /Library. The folder ~/Library is a sub folder of your homefolder. If your username is foobar then the folder ~/Library is located at /Users/foobar/Library on your hard drive. On OS X 10.7 (Lion) and newer the folder ~/Library is hidden by default. To access it anyway open Finder, click on the menu item "Go" while pressing 'Option/Alt' and "Library" will be an option to click on. If you followed all the instructions and Exult still won't recognize the games, you can try deleting exult.cfg in ~/Library/Preferences and then start Exult. 2.7. Path-Settings for *nix based systems On *nix based systems Exult uses: /usr/local/share/exult /usr/local/share/exult/gamename /usr/local/share/exult/gamename/static $HOME/.exult/gamename $HOME/.exult/gamename/gamedat /usr/local/share/exult/gamename/mods /usr/local/share/exult/gamename/patch As on OS X, Exult uses on *nix systems a default path for its data folder and the game files. Unless you use a different path in exult.cfg, Exult will look for these in /usr/local/share/exult. But you will need to follow our gamename standard when you name the game folders, see 1.3. Terms we use in regard to Exult and Ultima 7 , otherwise Exult will not find them there. Example: User named FooBar on Ubuntu. BG is installed to /usr/local/share/exult/blackgate and SI is installed to /usr/local/share/exult/serpentisle. When you run Exult it will automatically recognize that BG and SI are installed. You do not need to edit exult.cfg, which is saved to $HOME/.exult.cfg. When you save a game in BG the savegame will be saved to $HOME/.exult/blackgate/exult00bg.sav, for SI to $HOME/.exult/serpentisle/exult00si.sav. If you install for example the keyring mod, you copy the contents of the Keyring.zip to /usr/local/share/Exult/blackgate/mods. When you save a game with the Keyring mod, this savegame will be found in $HOME/.exult/blackgate/mods/keyring/exult00bg.sav. 2.8. Advanced Configuration: Using both the original and the Add-Ons If you own both BG or SI without the add-ons FoV and SS and also the versions that has the add-ons you can now have them both shown in the Exult menu. Before you had to edit the exult.cfg when you wanted to switch the games. You now just have to add the tags for the two games. path_to/blackgate path_to/forgeofvirtue path_to/serpentisle path_to/silverseed If you only own one version of the game, you don't have to worry about this advanced configuration, just follow the instructions at 2.1.. You only have to do this extra work if you want to differentiate between original game with and without the add-on. Note: You cannot interchange savegames of games started with or without the add-ons. And again, Exult and Exult Studio will not be fooled by false games under . 2.9. Command line options Exult offers some "hidden" command line options: * -h or --help Shows all the command line parameters in stderr (stderr.txt on Windows systems). * -v or --version Shows version information in stderr. * -c configfile Specify alternate config file (relative or absolute paths work). * -p Portable option for Windows only. Exult will read cfg file from the folder it got installed to (or make one) and will also save to gamename folders in the Exult install folder. For example if Exult got installed to E:\Exult, a BG game will be saved to E:\Exult\blackgate. Be careful that you have actually writing permissions in the Exult folder or this will fail. * --bg Starts the game with the Black Gate menu (prefers original game). * --fov Starts the game with the menu of the Black Gate with Forge of Virtue expansion. Only useful if you have FoV added as described at 2.8., otherwise it will just work like the command '--bg'. * --si Starts the game with the Serpent Isle menu (prefers original game). * --ss Starts the game with the menu of the Serpent Isle with Silver Seed expansion. Only useful if you have SS added as described at 2.8., otherwise it will just work like the command '--si'. * --nomenu Skips game menu. * --game gamename Loads a game specified in exult.cfg when there are other games made with Exult Studio. * --mod modname Must be used together with '--bg', '--si' or '--game gamename'; runs the specified game using the mod with title equal to 'modname'. 'modname' is the name of the mod cfg file (e.g. keyring.cfg means 'modname' 'keyring'. * --buildmap x x = 0 shows all roofs, x = 2 pops them all. Builds the map of the game specified. The map is huge and in pcx format, you will need a lot of ram to even look at this map once it is build (and even that requires a lot of patience) Exult is required to be run in windowed mode and you get the best map if you started a new game before you build the map. You need to specify a game, either by '--bg' (or '--si', '--fov', '--ss') or with the '--game'/'--mod' option. * --mapnum This must be used with '--buildmap'. Selects which map (for multimap games or mods) whose map is desired. * --nocrc Recently we added a crc check that Exult doesn't start when the exult*.flx files in the data folder aren't the same it got compiled with. This parameter lets the game start nevertheless. Don't try this if you don't know what you are doing. * --edit Start in map-edit mode. This will also load Exult Studio when the game is started. * --write-xml Write 'patch/exultgame.xml'. Only useful for game editing. * --reset-video resets Exult's video settings to the default values. Very helpful when Exult isn't playable anymore because of wrong settings. 2.10. Error Log * Windows: Exult generates the files 'stdout.txt' and 'stderr.txt'. These may give you some idea of what is going on under the hood. When Exult suddenly quits, sometimes these files can help. You can find these files in the folder where exult.cfg is located (see 2.2.) * UNIX/UNIX clones: the above mentioned logs are shown in the console from which Exult is started. ./exult >&log will send both stderr and stdout to the file named "log". * Mac OS X: When you are running the app bundle Exult.app then the error log will be shown in the OS X Application Console (/Applications/Utilities/Console.app). -------------------------------------------------------------------------------- 3. Audio 3.1. Music There are three general ways that music is played in Exult. One is using MIDI, which plays the music through any MIDI device, or software synthesizers like TiMidity and FluidSynth. Another way is Digital Music encoded into OGG (similar to MP3) which was recorded directly from a Roland MT-32. The third option is FMOpl which emulates Opl2/Adlib. The MIDI files are converted on-the-fly from the original Ultima 7 MT-32 files to General MIDI format so that they will be playable on modern General MIDI and General MIDI/GS supporting sound cards. The Music driver options can be changed in the in-game menu that you open by hitting 'ESC'. There you can enable Digital Music and change the MIDI driver, through which you can also select the FMOpl emulation. When you enable Digital Music, it takes precedence over the MIDI driver. 3.2. MIDI Music The MIDI driver can be changed to: * Default This setting utilizes the default MIDI driver of your system. * FMOPL This is a Software FM Synthesizer (also known as a emulated Opl2/Adlib). * TiMidity is a software synthesizer that can play MIDI files without a hardware synthesizer. You can install TiMidity on all major Operating systems. You need to place tmidity.cfg into the same folder where the Exult executable is installed to, otherwise TiMidity will not work. On linux systems it needs to be in ~/.exult. * FluidSynth is another software synthesizer, which uses SoundFont 2 technology without need for a SoundFont-compatible sound card. It is available for many Operating Systems and opposed to TiMidity still actively developed. Since Fluidsynth pulls in many dependencies it is not compiled into Exult at the moment. If you compiled Exult ourself and you enabled Fluidsynth you just need to edit exult.cfg and point