ShapeFusion 0.5
http://shapefusion.sourceforge.net

An editor for Marathon II, Marathon Infinity and AlephOne scenarios

Copyright 2000-2008 Tito Dal Canton and Etienne Samson


What is ShapeFusion?
--------------------
ShapeFusion is a scenario editor for the AlephOne game engine, also
compatible with Bungie's original Marathon II and Marathon Infinity engines.
An AlephOne scenario is made of several files; ShapeFusion is devoted to
editing the "Shapes" file, which stores most of the scenario graphics and
animation data. It's *not* a tool for editing maps. In case you ever used
Bungie tools for editing Marathon scenarios, it's enough to say that
ShapeFusion is meant as a replacement for Anvil, or better for its Shapes
editor. Such a replacement is mainly needed because Anvil is proprietary,
non-free and Mac-only software, which makes it very difficult to use on
modern platforms. Thanks to Etienne Samson, since version 0.4 ShapeFusion
can open Sounds files too; the Sounds editor is in progress and I hope it will
reach the level of the Shapes counterpart soon.

As for the license, ShapeFusion is free software, released under the terms of
the GNU General Public License. For more information see the COPYING file
that comes with ShapeFusion.

Supported platforms
-------------------
ShapeFusion is being developed on Linux and continuously tested on Linux,
MacOS X and Windows. Thanks to wxWidgets it should compile and work on other
systems too, but I've never tried it. ShapeFusion could *in theory* compile
and work also on MacOS Classic, but I have no plans on this side. If you build
ShapeFusion on systems different from Linux, MacOS X and Windows, please let
me know (screenshots and binary builds are appreciated!).

Building
--------
You'll need wxWidgets (at least version 2.8.x) to compile ShapeFusion.

On Linux systems you can test the presence of wxWidgets by running the command
'wx-config --version'. If that command is available and gives you the right
version, everything should work; otherwise install wxWidgets following your
Linux distribution rules. To compile ShapeFusion, just run the following inside
the source directory:

  ./configure
  make

When compilation is complete, simply run the 'shapefusion'
executable (you can put it anywhere in your PATH). I finally suggest you place
the attached DefaultNames.txt file in the /usr/local/share/shapefusion
directory, so that collections and sounds will get Infinity-like names.

On MacOS X you should be able to use the provided Xcode project
(ShapeFusion.xcodeproj). You'll need both the MacOS X developer tools and
wxWidgets (which will take some time to build). Once in the ShapeFusion
Xcode project, before building you must change the WX_SRC_ROOT variable to
point to your wxWidgets source directory. Note that MacOS X binary builds are
released together with each source release: they should work out-of-the-box
without the need to install anything else. In case you're wondering why they
are so large in size, it is because they carry the whole wxWidgets library
together with ShapeFusion itself.

Overview of the Shapes editor window
------------------------------------
When you open a Shapes file, the window shows its collection slots on the left.
In standard Marathon Shapes there are always 32 of them; however, ShapeFusion
tries to be flexible and can open "extended" Shapes files with more collections,
like Damage Inc ones. Collection names are read from the DefaultNames.txt file
if it is available, otherwise they are set to simple numbers. Each collection
slot can be opened revealing two sub-slots, the 8 bit and true color versions.
They represent two independent versions of the same collection: the first will
be used if the game is played on low-color displays, the second is for modern
high-color displays (including the OpenGL mode in AlephOne). Each sub-slot can
finally be opened to reveal its real content: bitmaps, color tables, frames and
sequences. The contrast with Anvil is clear. Anvil tries to obfuscate some
aspects of the Shapes file organization, but I feel that this creates a lot of
confusion in the user. In my opinion, it makes more sense to treat Shapes files
as they really are: archives of collections. The ShapeFusion window tries to
reflect this idea.

Bitmaps, color tables and frames are displayed as lists of preview thumbnails.
Selecting one of them will pop up an edit panel for that item. Sequences are
listed by their name since they can't be easily represented with thumbnails;
however, selecting a sequence will pop up an edit panel like for other items.

The logic behind ShapeFusion is that each collection is made of four sets of
entities: color tables, bitmaps, frames and sequences. If you follow this
order, entities coming after reference entities coming before: a sequence
references a set of frames, a frame references a bitmap, a bitmap naturally
references a color table since it's indexed. So editing a sequence involves
picking frames from the collection frame set, and editing a frame involves
selecting a bitmap from the collection bitmap set. Get it? ;-) Of course you
don't have to follow this flow, especially if you are only adjusting some
settings.

The View menu contains display settings such as thumbnail size. Nothing here
affects what's inside the Shapes file.

You may edit the DefaultNames.txt file at your will to provide collection and
sound names that are more suited to your scenario. The syntax should be pretty
self-explanatory. Under Linux/Unix this file should go into
/usr/local/share/shapefusion; under MacOS X it should be embedded into the
application package (Contents/Resources); under Windows it should sit next to
the ShapeFusion executable.

Overview of the Sounds editor window
------------------------------------
TODO

Notes
-----
Please be careful when editing your scenario with ShapeFusion. We had no big
problems so far, but it's still under development and it may corrupt your
files, so be sure to keep backup copies. You should not use versions before
0.3, as they are affected by a bug regarding frames minimum light intensity
value. If you think your files got corrupted by ShapeFusion, please let us
know what happened.

Object indexes start from 0, not 1. So if you have 12 bitmaps, the first is
bitmap 0 (not 1) and the last is bitmap 11 (not 12).

Bitmaps are exported as 8-bit Windows bitmap (.bmp) files. They get the color
table that is currently used for viewing, as selected in the View menu.

When you import a bitmap, ShapeFusion tries to map its colors to the collection
color table as best as it can. Although the algorithm often yields good results,
you can help it a lot by converting the bitmap to indexed before (using
PhotoShop or Gimp, for example) so that it contains just colors belonging to
the collection color table.

In ShapeFusion, a frame can be referenced by many sequences. This may sound
strange at first, but in Shapes file format logic it's perfectly legal and I
think it makes sense too. However it can create a bit of confusion if you
forget it. Keep in mind that a famous Anvil bug is based on this very
confusion. But in Anvil it's a bug, in ShapeFusion it's a feature ;-)

If you open an "original" Shapes file (e.g. from Marathon II) and then save it
without touching anything, it won't probably have exactly the same size. In
other words, it won't be exactly the same file. However I've never been able
to tell the difference, apart from looking at the size. The original engines,
AlephOne and ShapeFusion itself seem to behave perfectly with both files. The
size mismatch has probably to do with data structure alignments: ShapeFusion
ignores alignments when writing files, it just packs structure after structure
and so produces generally smaller files.

Shapes files are known to rarely contain strange data, like negative sequence
ticks_per_frame. Maybe this comes from some broken Shapes editor, but it could
be just Anvil. ShapeFusion doesn't handle this invalid data very well, but I
plan to implement some consistency checks in the future.

Feedback
--------
You can send screenshots, bug reports and any comment to tito(at)dalcanton.it.
Better yet, you can join the ShapeFusion development mailing list
(see http://www.sourceforge.net/projects/shapefusion for details) and report
things there.

History
-------
ShapeFusion was born in 2000 as a MacOS Classic application. Working releases
were produced, but then I moved to other projects and the development ended
while ShapeFusion was still far from being a complete editor.

With the death of the Classic platform and the spread of AlephOne on different
operating systems I became more and more attracted by the idea of porting
ShapeFusion to other systems too. This couldn't be done easily with the
original MacOS code, so eventually I started to rewrite everything using the
portable wxWidgets toolkit. I also had the opportunity to rework the user
interface, since I never liked the Anvil approach that I was trying to follow
in the original ShapeFusion. Etienne joined the project at this stage.

The new editor is not yet complete, but it's a great improvement at least on
the technical side (stability, code organization, portability). Adding new
features and fixing existing ones will be much easier with respect to the old
version.

Changelog
---------
0.5
	Collection and sound names are now read from a simple external text file.
	First release supporting Windows officially.
	ShapeFusion now requires at least wxWidgets 2.8.x.
	Fixed a bug that prevented opening shapes files on Windows.
	Fixed a file I/O bug that prevented BMP exporting on Windows.
	Code cleanup and minor fixes.

0.4
	Switched to multidocument wxWidgets framework (major code rewrite).
	Implemented a preliminary Sounds editor.
	Implemented the color table editor.
	Improved the color quantization algorithm used when importing bitmaps.
	Bitmap masks can be exported to separate bmp files.
	Bitmaps are now exported to 8-bit bmp files.
	Lots of small changes and fixes.

0.3
	Improved functionality of the sequence editor.
	Implemented bitmap and frame deletion.
	Frame and sequence user interface cleanup.
	One can now edit frame scale factors.
	Fixed a serious bug regarding frames minimum light intensity value.
	Assorted changes and fixes.

0.2
	Work done on the color table section and on color table exporting features.
	Improved color reduction when importing RGB bitmaps.
	Implemented "Save all bitmaps".
	Implemented preliminary version of a true sequence editor.
	Implemented sequence deleting.
	Fixed sequence name charset issue that prevented some names from being displayed.
	BitmapBrowser and FrameBrowser speed optimizations.
	Assorted changes and fixes.

0.1
	First release of the new version using wxWidgets.