Big Picture

Big Picture

Finding your way around the codebase

1. AVM2: is an implementation of the ActionScript3 virtual machine. All of the code for AVM2 is in src/avm2 and only has a dependency on the top level src directory for utilities and options.

2. AS3 Builtin APIs: AS3 bootstraps some of its native objects like Array, Object etc. The source code for these is in avm2/generated/builtin/*.as. These get compiled to avm2/generated/builtin/builtin.abc (3) which is the first abc file that is executed by Shumway at startup. If you make changes to these files you'll need to rebuild the builtin.abc file using the ./generate.py command in the generated directory.

3. The AS3 Builtin APIs are for the most part marked as native which means their implementation is implemented natively in "JavaScript". Most of this implementation is in avm2/native.ts and avm2/natives/*.ts.

4. .swf files (5) are parsed into abc blocks (7) and swf tags (8). abc blocks contain AS3 bytecode are executed by AVM2 (1). During execution, references to flash classes such as flash.display.DisplayObject are detected by AVM2's linker (12) and trigger class loading. The linker knows that flash.display.DisplayObject is defined somewhere in playerGlobals.abc (10) and directs AVM2 to load it. The sources for the player globals (10) are available in src/flash/*.as. The vast majority of player global classes are implemented natively in JavaScript in the same directory src/flash/*.ts (11).

5. Most of the code that deals with Flash APIs is here. If you're looking for something to do here is a great place to start. Simply look for notImplemented function calls and implement them.

6. Most of the Shumway subsystems are designed to work independently. The Player is a place where they are all brought together. This is responsible for loading .swf and processing events and communicating with the rendering engine.

7. Shumway can be used from JavaScript directly, not only through ActionScript3. This makes it easy to write unit tests and even new content that relies on the well known and understood Flash APIs. See, src/test/unit/*.js

8. Shumway is designed to run in a Worker thread so as not to jank the main rendering thread. This means we can't make use of any APIs that are only available on the main thread. The Remoting Player (14) that lives in the worker and the Remoting GFX (15) module communicate via post message, sending across drawing commands and user input. Most of the remoting code is in src/player.

9. Flash uses a retained mode drawing API which manages a display list (a tree of DisplayObjects and DisplayObjectContainers). This display list is synchronized with a Frame Tree (17) that lives on the main thread. The GFX backend (18) src/gfx is responsible for drawing the frame tree whenever it changes. There are currently two rendering backends: a WebGL backend (19) and a Canvas2D backend (20).