README.txt

   1 ShapeFusion 0.5
   2 http://shapefusion.sourceforge.net
   3
   4 An editor for Marathon II, Marathon Infinity and AlephOne scenarios
   5
   6 Copyright 2000-2008 Tito Dal Canton and Etienne Samson
   7
   8
   9 What is ShapeFusion?
  10 --------------------
  11 ShapeFusion is a scenario editor for the AlephOne game engine, also
  12 compatible with Bungie's original Marathon II and Marathon Infinity engines.
  13 An AlephOne scenario is made of several files; ShapeFusion is devoted to
  14 editing the "Shapes" file, which stores most of the scenario graphics and
  15 animation data. It's *not* a tool for editing maps. In case you ever used
  16 Bungie tools for editing Marathon scenarios, it's enough to say that
  17 ShapeFusion is meant as a replacement for Anvil, or better for its Shapes
  18 editor. Such a replacement is mainly needed because Anvil is proprietary,
  19 non-free and Mac-only software, which makes it very difficult to use on
  20 modern platforms. Thanks to Etienne Samson, since version 0.4 ShapeFusion
  21 can open Sounds files too; the Sounds editor is in progress and I hope it will
  22 reach the level of the Shapes counterpart soon.
  23
  24 As for the license, ShapeFusion is free software, released under the terms of
  25 the GNU General Public License. For more information see the COPYING file
  26 that comes with ShapeFusion.
  27
  28 Supported platforms
  29 -------------------
  30 ShapeFusion is being developed on Linux and continuously tested on Linux,
  31 MacOS X and Windows. Thanks to wxWidgets it should compile and work on other
  32 systems too, but I've never tried it. ShapeFusion could *in theory* compile
  33 and work also on MacOS Classic, but I have no plans on this side. If you build
  34 ShapeFusion on systems different from Linux, MacOS X and Windows, please let
  35 me know (screenshots and binary builds are appreciated!).
  36
  37 Building
  38 --------
  39 You'll need wxWidgets (at least version 2.8.x) to compile ShapeFusion.
  40
  41 On Linux systems you can test the presence of wxWidgets by running the command
  42 'wx-config --version'. If that command is available and gives you the right
  43 version, everything should work; otherwise install wxWidgets following your
  44 Linux distribution rules. To compile ShapeFusion, just run the following inside
  45 the source directory:
  46
  47   ./configure
  48   make
  49
  50 When compilation is complete, simply run the 'shapefusion'
  51 executable (you can put it anywhere in your PATH). I finally suggest you place
  52 the attached DefaultNames.txt file in the /usr/local/share/shapefusion
  53 directory, so that collections and sounds will get Infinity-like names.
  54
  55 On MacOS X you should be able to use the provided Xcode project
  56 (ShapeFusion.xcodeproj). You'll need both the MacOS X developer tools and
  57 wxWidgets (which will take some time to build). Once in the ShapeFusion
  58 Xcode project, before building you must change the WX_SRC_ROOT variable to
  59 point to your wxWidgets source directory. Note that MacOS X binary builds are
  60 released together with each source release: they should work out-of-the-box
  61 without the need to install anything else. In case you're wondering why they
  62 are so large in size, it is because they carry the whole wxWidgets library
  63 together with ShapeFusion itself.
  64
  65 Overview of the Shapes editor window
  66 ------------------------------------
  67 When you open a Shapes file, the window shows its collection slots on the left.
  68 In standard Marathon Shapes there are always 32 of them; however, ShapeFusion
  69 tries to be flexible and can open "extended" Shapes files with more collections,
  70 like Damage Inc ones. Collection names are read from the DefaultNames.txt file
  71 if it is available, otherwise they are set to simple numbers. Each collection
  72 slot can be opened revealing two sub-slots, the 8 bit and true color versions.
  73 They represent two independent versions of the same collection: the first will
  74 be used if the game is played on low-color displays, the second is for modern
  75 high-color displays (including the OpenGL mode in AlephOne). Each sub-slot can
  76 finally be opened to reveal its real content: bitmaps, color tables, frames and
  77 sequences. The contrast with Anvil is clear. Anvil tries to obfuscate some
  78 aspects of the Shapes file organization, but I feel that this creates a lot of
  79 confusion in the user. In my opinion, it makes more sense to treat Shapes files
  80 as they really are: archives of collections. The ShapeFusion window tries to
  81 reflect this idea.
  82
  83 Bitmaps, color tables and frames are displayed as lists of preview thumbnails.
  84 Selecting one of them will pop up an edit panel for that item. Sequences are
  85 listed by their name since they can't be easily represented with thumbnails;
  86 however, selecting a sequence will pop up an edit panel like for other items.
  87
  88 The logic behind ShapeFusion is that each collection is made of four sets of
  89 entities: color tables, bitmaps, frames and sequences. If you follow this
  90 order, entities coming after reference entities coming before: a sequence
  91 references a set of frames, a frame references a bitmap, a bitmap naturally
  92 references a color table since it's indexed. So editing a sequence involves
  93 picking frames from the collection frame set, and editing a frame involves
  94 selecting a bitmap from the collection bitmap set. Get it? ;-) Of course you
  95 don't have to follow this flow, especially if you are only adjusting some
  96 settings.
  97
  98 The View menu contains display settings such as thumbnail size. Nothing here
  99 affects what's inside the Shapes file.
 100
 101 You may edit the DefaultNames.txt file at your will to provide collection and
 102 sound names that are more suited to your scenario. The syntax should be pretty
 103 self-explanatory. Under Linux/Unix this file should go into
 104 /usr/local/share/shapefusion; under MacOS X it should be embedded into the
 105 application package (Contents/Resources); under Windows it should sit next to
 106 the ShapeFusion executable.
 107
 108 Overview of the Sounds editor window
 109 ------------------------------------
 110 TODO
 111
 112 Notes
 113 -----
 114 Please be careful when editing your scenario with ShapeFusion. We had no big
 115 problems so far, but it's still under development and it may corrupt your
 116 files, so be sure to keep backup copies. You should not use versions before
 117 0.3, as they are affected by a bug regarding frames minimum light intensity
 118 value. If you think your files got corrupted by ShapeFusion, please let us
 119 know what happened.
 120
 121 Object indexes start from 0, not 1. So if you have 12 bitmaps, the first is
 122 bitmap 0 (not 1) and the last is bitmap 11 (not 12).
 123
 124 Bitmaps are exported as 8-bit Windows bitmap (.bmp) files. They get the color
 125 table that is currently used for viewing, as selected in the View menu.
 126
 127 When you import a bitmap, ShapeFusion tries to map its colors to the collection
 128 color table as best as it can. Although the algorithm often yields good results,
 129 you can help it a lot by converting the bitmap to indexed before (using
 130 PhotoShop or Gimp, for example) so that it contains just colors belonging to
 131 the collection color table.
 132
 133 In ShapeFusion, a frame can be referenced by many sequences. This may sound
 134 strange at first, but in Shapes file format logic it's perfectly legal and I
 135 think it makes sense too. However it can create a bit of confusion if you
 136 forget it. Keep in mind that a famous Anvil bug is based on this very
 137 confusion. But in Anvil it's a bug, in ShapeFusion it's a feature ;-)
 138
 139 If you open an "original" Shapes file (e.g. from Marathon II) and then save it
 140 without touching anything, it won't probably have exactly the same size. In
 141 other words, it won't be exactly the same file. However I've never been able
 142 to tell the difference, apart from looking at the size. The original engines,
 143 AlephOne and ShapeFusion itself seem to behave perfectly with both files. The
 144 size mismatch has probably to do with data structure alignments: ShapeFusion
 145 ignores alignments when writing files, it just packs structure after structure
 146 and so produces generally smaller files.
 147
 148 Shapes files are known to rarely contain strange data, like negative sequence
 149 ticks_per_frame. Maybe this comes from some broken Shapes editor, but it could
 150 be just Anvil. ShapeFusion doesn't handle this invalid data very well, but I
 151 plan to implement some consistency checks in the future.
 152
 153 Feedback
 154 --------
 155 You can send screenshots, bug reports and any comment to tito(at)dalcanton.it.
 156 Better yet, you can join the ShapeFusion development mailing list
 157 (see http://www.sourceforge.net/projects/shapefusion for details) and report
 158 things there.
 159
 160 History
 161 -------
 162 ShapeFusion was born in 2000 as a MacOS Classic application. Working releases
 163 were produced, but then I moved to other projects and the development ended
 164 while ShapeFusion was still far from being a complete editor.
 165
 166 With the death of the Classic platform and the spread of AlephOne on different
 167 operating systems I became more and more attracted by the idea of porting
 168 ShapeFusion to other systems too. This couldn't be done easily with the
 169 original MacOS code, so eventually I started to rewrite everything using the
 170 portable wxWidgets toolkit. I also had the opportunity to rework the user
 171 interface, since I never liked the Anvil approach that I was trying to follow
 172 in the original ShapeFusion. Etienne joined the project at this stage.
 173
 174 The new editor is not yet complete, but it's a great improvement at least on
 175 the technical side (stability, code organization, portability). Adding new
 176 features and fixing existing ones will be much easier with respect to the old
 177 version.
 178
 179 Changelog
 180 ---------
 181 0.5
 182         Collection and sound names are now read from a simple external text file.
 183         First release supporting Windows officially.
 184         ShapeFusion now requires at least wxWidgets 2.8.x.
 185         Fixed a bug that prevented opening shapes files on Windows.
 186         Fixed a file I/O bug that prevented BMP exporting on Windows.
 187         Code cleanup and minor fixes.
 188
 189 0.4
 190         Switched to multidocument wxWidgets framework (major code rewrite).
 191         Implemented a preliminary Sounds editor.
 192         Implemented the color table editor.
 193         Improved the color quantization algorithm used when importing bitmaps.
 194         Bitmap masks can be exported to separate bmp files.
 195         Bitmaps are now exported to 8-bit bmp files.
 196         Lots of small changes and fixes.
 197
 198 0.3
 199         Improved functionality of the sequence editor.
 200         Implemented bitmap and frame deletion.
 201         Frame and sequence user interface cleanup.
 202         One can now edit frame scale factors.
 203         Fixed a serious bug regarding frames minimum light intensity value.
 204         Assorted changes and fixes.
 205
 206 0.2
 207         Work done on the color table section and on color table exporting features.
 208         Improved color reduction when importing RGB bitmaps.
 209         Implemented "Save all bitmaps".
 210         Implemented preliminary version of a true sequence editor.
 211         Implemented sequence deleting.
 212         Fixed sequence name charset issue that prevented some names from being displayed.
 213         BitmapBrowser and FrameBrowser speed optimizations.
 214         Assorted changes and fixes.
 215
 216 0.1
 217         First release of the new version using wxWidgets.
 218