Introduction ============ This program grew, somewhat haphazardly, out of two things: I wanted to learn about GTK+, and I wanted a better GUI for the Unix version of Magnetic. My primary goals with GtkMagnetic is to support all of Magnetic's features (such as music, animations and on-line hints) while staying reasonably portable. Ideally it should work on all the same platforms as GTK+ 2.6, but that remains to be seen. Feature-wise GtkMagnetic is in pretty good shape, but there are still a number of minor cosmetic issues, and quite possibly some outright bugs and/or memory leaks that remain to be fixed. There are already several Magnetic GUIs that will run under Unix, but at the time I began working on mine Jeff Mitchell's XMagnetic was an "alpha alpha alpha release", Dave Lodge's gMagnetic was an "early Beta", and Simon Baldwin's GlkMagnetic hadn't even been released yet. At the time of writing GtkMagnetic probably has the best support for Magnetic 2.x's features, closely following by GlkMagnetic, while gMagnetic is the one with the most modern look-and-feel. I haven't looked at XMagnetic for a long time since it hasn't been updated for Magnetic 2.x yet. While I obviously prefer GtkMagnetic, you really should look at all of them and form your own opinion. Compiling ========= Compiling under Unix should be pretty straightforward, though it will probably require some Makefile editing: SOUND_SYSTEM indicates which backend will be used for playing the title music. The Makefile lists them in my order of preference. MAGNETIC should point to the Generic directory of the original Magnetic source distribution. This is so that the build process will be able to find defs.h and emu.c. From what I understand, there is an ongoing effort to port GTK+ to alternative platforms, e.g. Microsoft Windows. If anyone manages to compile GtkMagnetic for any of those, I'd like to hear about it. Sound backends ============== SMPEG This backend uses Loki Software's SDL MPEG Player Library. SDL_MIXER This backend uses Loki Software's SDL_mixer library. This is slightly silly, because at the time of writing SDL_mixer uses SMPEG for MP3 playback. XMMS This backend uses the X Multimedia System, which is a WinAmp lookalike for Unix. This is very silly. NONE This backend doesn't play sounds at all. For more information about SDL and related libraries, see . For more information about XMMS, see . Performance considerations ========================== On my system, GtkMagnetic typically uses less than 1% of the CPU most of the time. There really isn't any reason for it to use more than that, since it will spend most of the time idling while waiting for user input. Though this didn't stop gMagnetic from gobbling up 90+% CPU just to do nothing, and the GUI is still pretty sluggish! (Though to be fair, this is probably pretty easy to fix. Just turn off the main timer when it's not needed.) The main CPU hog in GtkMagnetic is the animations. This is no problem on my system, but here are a few hints which may improve performance on low-end systems: * Use a cheaper interpolation mode. In particular, stay away from the "Hyperbolic" mode. You probably won't be able to tell its results from "Bilinear" anyway. * Set the image scale factor to 1. That way it won't need to interpolate the picture at all. * Increase the animation delay, or turn off the animations completely. Turning up compiler optimizations may help slightly, but probably not much. Most of the time-consuming stuff probably happens within the bowels of GdkPixbuf, and that should already be optimized. It may be possible to speed up the animation code a bit. Currently it will redraw the entire picture for every animation frame, rather than just the areas that change. It should be easy to fix, but I was afraid that the image scaling and interpolation would create visible artefacts unless the entire image was remade. Since CPU usage rarely exceeds 20-25% on my system, even with a scale factor of 2.0 and Bilinear interpolation, I don't think it's worth the bother. Special commands ================ In addition to the game's own commands, there are a few that are hard-wired into the interpreter: #UNDO Undo the most recent command. This may fail in some places, e.g. at "Are you sure?" prompts. It should, however, work just fine at "You have died." prompts. #SCRIPTING ON Begin a transcript to file. The transcript will #SCRIPT ON contain both the commands you type and the game's response. #SCRIPTING OFF Ends the transcript to file. #SCRIPT OFF #SCRIPT Toggles the transcripting on or off. #RECORDING ON Begins recording your commands to a file. The #RECORD ON recording can be played back later, which may be useful for debugging. With the exception of #SEED, special commands are not recorded. #RECORDING OFF Ends the recording to file. #RECORD OFF #RECORD Toggles the recording on or off. #REPLAYING ON Plays back recorded commands. #REPLAY ON #REPLAYING OFF Stops the playback. Since you won't be able to type #REPLAY OFF any commands during playback, you won't be able to use this command, though it could be inserted into a replay script to terminate it. #REPLAY Toggles the playback on or off. #SEED Seeds the random number generator. This is useful for #SEED number removing randomness when recording. Like the standard commands, all the special commands are case-insensitive. A few words on interpolation modes ================================== GTK+ 2.x uses the gdk-pixbuf library which, to quote from the documentation, provides the following interpolation modes when scaling an image: GDK_INTERP_NEAREST Nearest neighbor sampling; this is the fastest and lowest quality mode. Quality is normally unacceptable when scaling down, but may be OK when scaling up. GDK_INTERP_TILES This is an accurate simulation of the PostScript image operator without any interpolation enabled. Each pixel is rendered as a tiny parallelogram of solid color, the edges of which are implemented with antialiasing. It resembles nearest neighbor for enlargement, and bilinear for reduction. GDK_INTERP_BILINEAR Best quality/speed balance; use this mode by default. Bilinear interpolation. For enlargement, it is equivalent to point-sampling the ideal bilinear-interpolated image. For reduction, it is equivalent to laying down small tiles and integrating over the coverage area. GDK_INTERP_HYPER This is the slowest and highest quality reconstruction function. It is derived from the hyperbolic filters in Wolberg's "Digital Image Warping", and is formally defined as the hyperbolic-filter sampling the ideal hyperbolic-filter interpolated image (the filter is designed to be idempotent for 1:1 pixel mapping). In reality it is unlikely that you will ever want to scale down the images, unless someone ports the interpreter to a hand-held computer, so "Nearest" and "Tiles" can be considered as equivalent. They will both provide a sharp, albeit slightly blocky, image when scaling up. "Bilinear" and "Hyperbolic" will produce a smoother, slightly blurry, image. I can't tell the difference between the two, so they can probably be considered equal as well. I prefer using the "Bilinear" mode, but on slow computers it may be prudent to use "Nearest" or "Tiles" in games with animated pictures. Read the section on performance considerations for some further elaboration on this. Changing colours ================ It is possible to specify the fore- and background colours of the text area and statusline, and the background colour of the picture area. Torbjörn Andersson