gameswf

gameswf (pronounced "game swiff") is an open source Public Domain library for parsing and rendering SWF movies, using 3D hardware APIs for rendering. It is designed to be used as a UI library for computer and console games.

It is written in C++, and compiles under Windows, Mac OSX and Linux, using GCC and MSVC. It includes code for rendering with OpenGL. The rendering module is factored out so that you can port to other APIs.

It is currently being maintained as a semi-autonomous part of my personal tu-testbed project on SourceForge.

The biggest benefit of using SWF as a file format for game UIs is the availability of high quality authoring tools (like Macromedia Flash MX) and the large number of talented designers who have expertise with these tools. The SWF format is not perfectly suited for game UIs, but it's not bad, and my hope is that gameswf will help improve the quality of game UIs while reducing the effort that goes into making them.

gameswf demo player showing a frame from a ninjai movie

an (ugly) test movie showing (nice) text rendering

See http://www.ninjai.com for some excellent Flash storytelling.

• Scaleform GFx

• gnash

• training software from Engineering and Computer Simulations

10 May 2004 -- The project has been under slow but active development since the last update. A subset of ActionScript functionality is in, along with various bug fixes, leak fixes, and small optimizations.

7 July 2003 -- Posted a snapshot. The major difficult features, not including ActionScript, are in pretty good shape now.

23 May 2003 -- Editable text works a little, and has a host interface. You can load a movie from your C++ code, play the movie, and dynamically change the text in a defined field by doing:

 movie->set_edit_text("text_field_name", "New text here...");

7 Jan 2003 -- Using new name, "gameswf". Moved the files around in CVS, and changed the C++ namespace name. Created web page.

Snapshot releases include source and sample Windows .exe's. Should build on Linux (and possibly OSX) with little fuss. If you want to build under Windows, there's a win32_dependencies zip for convenience; it includes several of the open-source libraries that the gameswf demo depends on.

The current bleeding-edge code is always in SVN on SourceForge, and a working player can be compiled on Linux or Win32. You can also browse the code via the web if you're just curious about what it looks like.

So far, gameswf has been implemented by Thatcher Ulrich, Ignacio Castaño, Willem Kokke, Mike Shaver, Thierry Berger-Perrin, Vitaly Alexeev, Alexander Streit, Rob Savoye, Paul Kelly, Bob Ives and Thomas Vissieres with additional testing & small patches from others as well. See the AUTHORS file for details.

• the gameswf.h interface header for use by host apps

• the TODO file

  ---

Links

Thanks to OpenSWF.org, whose specs made it possible to embark on making gameswf.

Thanks to Alexis Wilke for the very best public SWF file format reference: Alexis' SWF Reference.

Thanks to Macromedia for fostering the SWF format and making excellent authoring tools.

Mailing List

The best place to send queries, bug reports and other comments is the tu-testbed mailing list

FAQ

A. Here are some reasons NOT to use gameswf:

• You need timely support.

• You are not comfortable fixing my bugs.

• You need super-tight optimized code & data. SWF imposes some overhead that's hard to avoid. Furthermore, gameswf has some crufty bits in it, and does a lot of little heap allocations.

• You need good ActionScript compatibility. The ActionScript support is usable, if you are willing to do your own testing to figure out which parts work and which don't.

A. Hm. How about:

• A good designer who has some experience with Flash can do some great-looking UI.

• You were thinking about writing something like this yourself. It's a lot easier to start with gameswf. Send me patches.

• Rendering is very fast compared to the Macromedia player, because gameswf uses 3D hardware.

A. While gameswf is able to run a lot of straightforward SWF animations, most ActionScript-intensive files don't work correctly yet.

A. For now, 6.0. gameswf can load 7.0 files, but there are some basic problems with ActionScript.

A. The gory interface details are in gameswf.h

C++ holds a movie_interface*, which has a few useful methods on it for play control etc. In addition to that, you can talk to ActionScript with these methods:

void set_variable(const char* path_to_var, const char* new_value);
const char* get_variable(const char* path_to_var) const;
const char* call_method(const char* method_name, const char* arg_fmt, ...);

Also, the library lets you register a callback function, so that when ActionScript calls fscommand(), your code gets notified:

typedef void (*fscommand_callback)
  (movie_interface* movie, const char* command, const char* arg);
void register_fscommand_callback(fscommand_callback handler);

Many more details and features in gameswf.h. Unfortunately the fscommand() thing is a little awkward, since in ActionScript, fscommand doesn't return a value, and it always takes exactly two args. So you can fake a call from AS to C++, using a global variable to hold the return value, but it's kind of ugly. I'll have to look into the new things in mx2004.

A. It's pretty hard to define exactly what is supported and what isn't, because there is no definitive reference (that I know of) to the features of ActionScript. Alexi's SWF Reference is the best reference for the workings of the VM opcodes, but it does not attempt to describe all the library API's. The Flash MX help files are pretty good for the authoring side but not complete or detailed enough to fully define the implementation, and the docs don't cover everything that is used by existing Flash programs. Also, there are lots of API's. So far, I have been implementing just the ones that I need for my own work.

I have had to do a lot of black-box testing to figure out how to implement some things, and the stuff that is implemented is definitely not 100% compatible.

A. Mainly it's an issue of figuring out how to implement a feature correctly. Often that involves cooking up some test movies to try against the Macromedia player, so it can be slow going. If there were a really tight spec for ActionScript & libraries, it would be much easier to finish, but as far as I know, no such spec exists. Macromedia's source code would be helpful, but I think that looking at it would create copyright problems for gameswf, so that's out of the question.

open-sourced?

A. I'm definitely too lazy to do it myself, but if you want to contribute a port, I'll give pointers and put it in the repository if it doesn't regress anything important.

A. The basic rendering and animation features work, including gradient and bitmap fills, shape/fill morphing, text, shape/fill transforms, sprites and buttons.

I'm pretty sure there are lots of little compatibility problems in corner cases. There is a sorting-order problem with lines and shapes in the same layer; sometimes lines draw on top of shapes when they shouldn't.

Line drawing is not supported very well (doesn't handle thickness). Flash MX has a feature to convert lines into shapes, to solve this in specific problem cases, so it's not high on my priority list.

Sound support is kind of hacky and probably has bugs, since I don't use it seriously; recommended practice for game UI's is to play sound through your game engine, via FSCommand callbacks.

Text does not currently support embedded HTML markup.

Streaming is not implemented at all.

Flash support in my game? I can afford to spend some money if it saves time & effort.

A. Yes -- see Scaleform GFx, a commercial fork of gameswf, with a bunch of engineering poured into compatibility, performance, support, etc. I'm not affiliated with them in any way, but I'm friendly with them and familiar with the broad outlines of what they've done, and I definitely recommend taking a look if you're building a commercial game. This is the library I would have licensed, if it had been available at the time I started gameswf.

A. (This list is incomplete, since users are under no obligation to publicize their use of gameswf. Send me an email if you want your project added to / removed from the list.)

• From Engineering and Computer Simulations:

  - Civil Support Team Trainer (CSTT) - a training application for the National Guard on hazardous material sample collection

  - Tactical Combat Casualty Care (TC3) - a training application for Army Combat Medics

  - Capitol Hill Police - a training application for the US Capitol Building South Gate guards

  - UAV (unmanned aerial vehicle) trainer - a training application that teaches the launching of military UAVs

• gnash -- a GPL'd fork of gameswf aimed at providing a Flash browser plugin alternative.

• Torque GameSWF component This is a packaging of gameswf for use with the Torque engine.

• Oddworld: Stranger's Wrath

  I wrote up a mini postmortem on the use of gameswf

• The Nebula Device 2 has a gameswf module. If anyone knows of specific Nebula-based titles using the gameswf module, send me an email.

• Zany Blocks ( developer site | garagegames page ) Uses gameswf as a SWF parser for all in-game graphics. Actual rendering is done using the Cairo library

A. These are all helpful:

Use gameswf in a real project, and report bugs, problems, feature requests and also successes.

When reporting bugs, it's extra helpful if you have a small .fla and .swf that illustrates the problem, that we can put in our SVN for reference. If you can't easily extract a sample out of what you're working on, that's OK, a description of the bug is still helpful.

Patches to fix bugs are very welcome.

We're interested in larger code contributions as well (i.e. large enough to be copyrightable, not just one-liner bug fixes), but only under the following conditions:

• You have not looked at the Macromedia SWF File Format documentation. This spec comes with a restrictive license that does not allow it to be used to make player software. I am not aware of any legal theory that makes that type of license in any way enforcable; nevertheless using this spec to build gameswf is clearly contrary to Macromedia's wishes. I am not a lawyer and would prefer to steer well clear of any legal gray areas, and also avoid stepping on Macromedia's toes if it's not necessary.

• You are willing and able to donate your contribution in the Public Domain. All the code so far in the gameswf project has been donated to the Public Domain. Public Domain means that the author relinquishes all copyright over the work. The work can be reused, modified (and even relicensed and sold) in any way by anyone else without restriction. It is likely that in the future your work will be incorporated into other open-source as well as closed-source projects without credit, so make sure you can live with that. (In the gameswf project itself, we try to give proper credit where credit is due, but we don't pass that burden on to our users.)

  In order to be able to give up your copyright, you must own the copyright in the first place (i.e. your employer doesn't own the rights to the work), or whoever does own it (e.g. your employer) must donate the work.

• The project maintainer decides what goes in, and will edit for style, consistency, maintainability, conformance to project goals, etc.