OFD : Open Flash Debugger

There is one very useful tool for the Flash developer which is the Flash Debugger. If you have never used it, try pressing the Shift+Ctrl+Enter shortcut from Flash IDE, and you will access it. You can then set breakpoints, where the program will stop, and check the values or the current variables. This is a very powerful tool, but the Flash IDE version is not very handy and have very poor user interface.

Please note that you can also do Remote debugging, and that is very interesting. The SWF can be put on the internet and will prompt to connect on some host when opened. Usually, it will connect to the locally running Flash IDE Debugger, but it could as well connect to OFD : The Open Flash Debugger. Read this document for using Remote Debugging (you need Flash Debug Player installed).

This document is trying to get as much informations as possible about the way the Flash Debugger works and to create an open source version of it, with better user interface, more features if possible, and multiplatform support.

Thank you for any contribution

Important ! It is important to know that in order to do remote debugging you need to run the Debug version of the Flash Player which seems not to be available for Linux and cannot be redistributed (see the Player license FAQ). Note: The debug player can be downloaded from Adobe's website.

When published in Debug Mode (using Ctrl+Shift+Enter) the Flash IDE is also creating a .SWD File that contains very useful informations. In fact, this is the only information that will be loaded on the debugger side, since the SWF is running remotely in the Flash Player.

The SWD File Format makes the Debugger able to display the current place of execution directly in the ActionScript sources, and not in the bytecode. For that, it stores the whole sources that have been compiled as well as some indexes that are matching position in the bytecode and position in the source. Here's a description of the file format (binary) :

Header := 'FWD' + Version
Version := '\007' on Flash 7 IDE
Body := Tag*
Tag := Tag-Identifier + Tag-Data
Tag-Identifier := 32-bit LowEndian integer
Tag-Data := depends on the Tag-Identifier, see Below

Here's a list of tags.

• dw: 16-bit word
• dd: 32-bit dword
• sz: zero-terminated UTF8 string

For each file you have a Tag 0 containing the filename and its corresponding source code, and several Tag 1 (one per line in the soure) that map the line in the source to the offset in the (decompressed) SWF.

When compiled into Debug mode, two tags are added to the SWF:

If at least one of these tags is present, the player will request the browser to download the .swd file. If the .swd file exists, the browser downloads it and the player parses it. Only then, and if a debug password is set, does the player connect to the debugger.

The Flash IDE is opening the port 7935 and listening on it when the “Enable Remote Debugging” option is checked into the Debugger Preferences. The Debug Flash Player connect on that port on the given host (after it pops the host choice).

Protocol

The protocol the Debugger and the Flash Player are talking is pretty easy :

PACKET := LEN + ID + DATA
LEN := 32-bit integer , size of the data
ID := 32-bit integer , id of the packet
DATA := size is LEN, contents depends on the ID

Informations about the formats

• Each .swf that is eligible for being debugged gets assigned a runtime, 0-based index which we will call swfIndex
• The source files contained in the different .swd's (we will call them SWD file entries) are assigned a runtime, 1-based global ID which we will call fileID. This is not one of the file indexes contained in the .swd - those are local ID's (you can request the local ID → global ID mapping by sending a “get swf info” message). The global ID's are commonly used together with line numbers, e.g. for setting breakpoints.
• Each object has a 32-bit ID which is called its ADDRESS

In the tables below, the following types are used:

• db: byte
• dw: word (16-bit), little endian
• dd: dword (32-bit), little endian
• sz: zero-terminated UTF8 string
• amf: just like the AMF used by remoting, but with a few important differences:
  • In remoting, there is a type byte followed by the contents. Here, the type is a 16-bit word and is followed by a 32-bit flags dword; only after that do the contents follow.
  • Strings (type ID 2) are not in the usual 2-bytes length + content format. Instead, they are pure zero-terminated strings. Long strings (type ID 12) are unused.
  • For AMF objects (type ID 3), the content consists solely of the object's ADDRESS. The referenced object may or may not yet have been sent.

Protocol negociation

Upon connection, the Player is sending VERSION and two MOVIEATTR packets (one with key “movie”, one with key “password”), which is enough for the Debugger to display the password dialog. Then several init packets are following (including SWD packets… before password validation).

Objects Data

The Player will send automaticaly some objects values, or can also send when requested by debugger. Objects are referenced by a 32-bit ADDRESS. They is NAMED objects and ANONYMOUS objects. Both have an address, but NAMED objects are _root (NAME = ”/”) and _global for example.

An object is created using CREATEOBJECT or PLACEOBJECT packets. Fields of the objects are then set using SETFIELD or SETFIELD2 packets using AMF format. Objects can then reference each other using their ADDRESS and the whole object graph is sent in several packets. Theses datas can be parsed by the Debugger to display the value of different properties.

Player to debugger messages

Debugger to player messages

Properties List (for packet 0x01 sent by player)

Debugger options

Suspend reasons