tulrich.com

home
me on G+
rants & musings
  current atom
  2011
  2009
  2008
  2007
  2006
  2005
  2004
  2003
  2002
misc creative
  movie reviews atom
  fonts
  gameography
  geekstuff
  sinkhole
  Botswana writing
  audio clips
  cartoons
photos
  more recent
  safari
  Botswana
  Namibia
  older Africa pics
corporate
  Oddworld
  Soul Ride
  Ringing Ear
  xootr & voloci
  Tectrix VR





"Powered" by Textweb

geekstuff | gameswf | Textweb | Chunked LOD | dumbuild

Cheat sheets: CVS | cygwin | Debian | Emacs | MythTV

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.


Screenshots

The most important part of any open-source project page.

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.


Status

gameswf is pre-alpha code. It can load and render the most common SWF tags, including shapes, text, dynamic text, bitmapped fills, linear and radial gradients, buttons, sprites and some simple actions. It supports the SWF file format through version 6. ActionScript support is spotty, but usable if you're adventurous.

The shape tesselator is not the fastest, but the renderer caches the tesselations, and the library uses 3D hardware, so on average the rendering speed is extremely fast, with a few spikes.

Text below a certain size (around 64 pixels in height, configurable) is rendered using cached texture bitmaps, which makes text rendering very fast compared to ordinary Flash. Text antialiasing uses alpha blending and mip-mapping, so it is very smooth, but slightly blurrier than Flash's software renderer. Text above a certain size is rendered as tesselated bezier shapes, and the edges are not antialiased.

Shapes are rendered as tesselated bezier shapes, and the edges are not antialiased.

There is basic sound support, but streaming is not implemented. Optional MP3 support requires an external library.

gameswf has bugs and quirks, and is not a complete implementation of Flash. The library as a whole is not highly optimized for memory use or speed. However, the text renderer is pretty decent, and the library is currently probably about as well implemented as the GUI library in the average commercial game. It has been used in many real projects but has a lot of rough edges.

Users, and especially contributors, are very welcome.


Plans

Major remaining items on the agenda:

  • Improve ActionScript features and compatibility.

  • Provide ability to store SWF data in a flattened format that can be loaded directly into RAM and used without preprocessing.


News

15 Apr 2007 -- Vitaly has done a lot of work lately, including video support, and has posted a new snapshot. See the downloads section below.

19 Dec 2006 -- The project is not dead, but it's a distant background task for me. I also still receive occasional patches from users and integrate them as I see fit and as I get around to it.

During the summer I wrote a new tesselator that is very fast on medium to large shapes, and produces minimal triangulations. It doesn't produce nice output given garbagy self-intersecting input, though the old tesselator didn't either.

gameswf has been used in a number of other projects since I last wrote, including:

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.


Downloads

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.

SourceForge Logo

Authors

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.


License

All the source code for this project has been placed in the public domain. Do whatever you want with it; no copyright, no restrictions whatsoever. The code comes with ABSOLUTELY NO WARRANTY.


Documentation

There's no nice documentation yet, and maybe there never will be. In the meantime, these are probably the two most interesting things to look at:

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

Q. Should I use it in my project?

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.

Q. What are some reasons TO use it?

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.

Q. Can *gameswf* be used to browse Flash movies off the web, and/or play random Flash games?

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

Q. What version of Flash are you targeting?

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

Q. How is the flash <-> c++ implemented?

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.

Q. What parts are missing in the action script support of gameswf?

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.

Q. Is there any great problems involved in adding the parts that are missing?

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.

Q. Are you going to integrate the ECMAScript JIT that Adobe

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.

Q. Apart from the action script, is there anything else that is not supported to 100%?

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.

Q. Isn't there a more complete, less buggy library I can use for

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.

Q. What projects have used 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.)

Q. How can I help?

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.

tu@tulrich.com |