Director 11 XDK Readme


Introduction

This release of the Xtra Development Kit (XDK) is for use in developing Xtras for Adobe Director 11, as well as earlier versions of Macromedia Director. The Macintosh XDK has been updated to support Mach-O universal binary Xtras and the Xcode development environment. Currently there is not a way to use older CFM xtras with Mach-O executables, or to use the Mach-O xtras with the older CFM executables. Although the XDK has been updated for the latest release of Director, you can still use it to build Xtras that run on Director 7 and later (provided, of course, that your xtra doesn't require any newer features.) A complete list of all additions and changes made since the Director 6 XDK can be found in the XDK updates file. The XDK can be used to develop Xtras for Authorware as well.

This XDK provides resources for developing extensions to Director, including Sprite Xtras, Transition Xtras, Scripting Xtras, and Tool Xtras. Documentation files in HTML format, and a complete list of updates since the previous XDK are provided as part of this release. A descriptive index of the example Xtras is provided in XDK Examples document.

Be sure to see below for special tips about debugging Director MX 2004. Also be sure to check out the notes about cross platform projectors.


Table of folders included in the XDK

Docs Director and Authorware XDK documentation.
Examples Project and source files for several examples; also sample movies and pre-built versions of the example Xtras.
Include Header files required for Xtra development
Lib Additional useful code libraries. These are used in some of the examples.
readme.htm This file.
Runtime Macintosh CFM only. Header files for the runtime library which can be used for Macintosh Xtras. The Mach-O xtras work with the standard Apple headers that come with Xcode.
Utility Some useful tools.

Xtra Development Environments


Windows

The compiler currently supported for developing Xtras for Windows is Microsoft Visual C++ version 6.0 or 7.0 (the .NET version of MSVC). The workspace files are in VC6 format so you will see a conversion dialog when opening in the newer version.

To build an example Xtra, open one of the example .dsw files in Microsoft Visual C++ (e.g. XDK\Examples\Sprite\Oval\WinProj\Oval.dsw). Choose Rebuild All from the Build menu. In Win32, the compiler will create a Oval.x32 shared library in the Oval\WinProj\Release\ directory. If you set the project to make a debug version, a debug version of the compiled Xtra will be put in Oval\WinProj\Debug\.

To make an Xtra that uses MFC you will need to modify the file include\win32\moatyedg.h. Add an #ifndef _USRDLL around the DllMain() function in the _MOA_XCODE_PREFACE section to disable it if _USRDLL is defined (this is a standard MFC #define). So the _MOA_XCODE_PREFACE is reduced to just declaring gXtraFileRef if you're using MFC. MFC developers also need to set the value of gXtraFileRef somewhere else. You may want to do this in an early MoaCreate() call like so:
gXtraFileRef = AfxGetInstanceHandle();

Debugging Windows Xtras

  1. Special information for MX 2004. Due to the activation library used in Director MX 2004, you can't directly target the shipping Director application for debugging your Xtra - the application will quit when you try to use it as your debug target. We suggest the following alternate solutions:
    • debug with a Projector rather than the authoring environment. You can use the "Exclude All Xtras" Publish option, and create an Xtras directory next to your projector.
    • debug with Director MX if you have it available
    • if you have a DebugBreak(); statement you may be able to get the debugger invoked - however this technique doesn't work with code that is run during startup, such as registration methods or the "create method" for an asset xtra
    • Use the special "save-and-publish-disabled" version of Director MX 2004 included with the XDK. Temporarily replace the Director.exe file with the application from the Utility\Win folder. [Hint: you can just rename the original file as RealDirector.exe.]
  2. Open Visual C++ and build the Debug target for the project, as described above (i.e. the Oval project).
  3. Copy a shortcut to the Debug version of the Xtra (i.e. winproj\Debug\OvalSprite.x32) into the Director\Configuration\Xtras\ folder. Note that previous to version MX 2004, this directory was called Director\Xtras\
  4. In Visual C++, click "Project" and then "Settings".
  5. Select the "Debug" tab. Fill in the path to Director (or a projector) in the "Executable for debug session" text field.
  6. Set breakpoint(s) in one of your source files.
  7. Click on the "Build" menu item, select "Start Debug" and then "Go". Or use the F5 shortcut for this.
  8. Click "OK" when you are warned that Director contains no debugging information.

Macintosh

This version of the XDK has been updated to support Xtra development using Apple's Xcode, and the Mach-O object format. The XDK supports Universal Binary format or processor specific xtras. For testing, there is a new Mach-O Shockwave plugin that supports these new format xtras. Since there is not yet a Mach-O version of Director, the XDK includes a projector application called ProjectorDev. This application is a Shockwave Projector, so Shockwave must be installed to run the projector. You can install your xtras in an Xtras folder next to the application. You specify the name of the movie(s) you want to play in the ini file. The ini file must have Macintosh style line-endings rather than unix style line endings, and uses : as the folder separator character. Note that pre-built Macho-O versions of 3 xtras aren't included: Wacky Dialog, BeepTool and Greeting

The new Xtra projects have been setup for development with Xcode version 2.4 and later. So far, all the development has been done assuming a target operating system of 10.4. At this time, the final details for Xtra package creation, downloading and verification have not been settled. Likewise, details about cross platform projector publishing is not yet available.

The Mach-O xtra format is a Bundle. Xtra bundles can still store resources in resource files; all of the Adobe Xtras will be using data fork resource files for this purpose. When porting xtras to the Intel Processor macintosh, the most common area that needed attention was the format of data such as castmember data. Older xtras assumed Windows was the same as__LITTLE_ENDIAN__ and Macintosh was the same as __BIG_ENDIAN__. Since xtra castmember file data needs to be stored in a common format with both bit storage approaches, translation is needed for some cases. Each of the sample xtras in the XDK that write out some castmember data needed to have a small code change to deal with this issue.

When debugging plugins (such as Xtras) with Xcode/GDB, after locating an executable application for your project, I recommend that you type the rest of the path to the executable in Xcode. This helps gdb properly find breakpoints in your plugin when it launches the other app, which may not have any debug information. For example, change /Applications/Adobe Director 11/Director.app to /Applications/Adobe Director 11/Director.app/Contents/MacOS/Director


Older Macintosh Development - Director MX 2004 and earlier

The compiler currently supported for developing Xtras on the Macintosh is Metrowerks CodeWarrior: the projects can be compiled with version 6, 7, 8 or 9 of the compiler. The project files are distributed in version 6 format, if opened with a newer version of CodeWarrior they will be automatically updated. The projects can be used to build Xtras for Macintosh OS 9 or OS X - if you are building projects for OS X, it is recommended that you use version 8.3 or later of CodeWarrior so you can debug your code.

To build a new Xtra from CodeWarrior, open one of the project files (e.g. XDK/Examples/Sprite/Oval/MacProj/OvalSprite.mcp). Select the target you want to build: for example, Classic Debug. Then choose Make from the CodeWarrior Project menu. The compiler will produce a code module (e.g. OvalSprite) in the MacProj/Classic/Debug/ folder.

All of the example projects have Carbon and Classic targets: the Classic targets are for Macintosh OS 8 and OS 9; the Carbon targets are for OS X.

Debugging Macintosh Xtras

This technique will work with OSX and OS9.

  1. Special information for MX 2004. Due to the activation library used in Director MX 2004, you can't directly target the shipping Director application - the application will quit when you try to use it as your debug target. We suggest the following alternate solutions:
    • debug with a Projector rather than the authoring environment. You can use the "Exclude Xtras" option, and create an Xtras directory next to your projector.
    • debug with Director MX if you have it available
    • Use the special "save-and-publish-disabled" version of Director MX 2004 included with the XDK. Temporarily replace the Director file with the application from the /XDK/Utility/MacOSX/ folder. To do this application subsitutuion:
      • control-click on the Director MX 2004 icon and choose the "Show Package Contents" menu item
      • Navigate to the folder /Director MX 2004/Contents/MacOS/
      • Rename the file Director MX to realDirectorMX so you can restore it later
      • Copy the "save-and-publish-disabled" file /XDK/Utility/MacOSX/Director MX to this folder
  2. Open CodeWarrior and build the Debug target for the project, as described above (i.e. the Oval project).
  3. Copy an alias of the Debug version of the Xtra (i.e. macproj/carbon/debug/OvalSprite) into the Director/Configuration/Xtras/ folder. Note that previous to version MX 2004, this directory was called Director/Xtras/
  4. In CodeWarrior, open the "Settings Panel" for the debug target.
  5. Select the ""Runtime Settings" item of the Target section. Use the "Choose..." button to select Director (or a Projector).
  6. Set breakpoint(s) in one of your source files.
  7. Choose the Debug item from the Project menu.

Preparing an Xtra to run under Macintosh OS X

  1. Director for OS X uses a Carbon implementation - not a Cocoa implementation.Turn on the "Carbon" flag for the header files. The simplest way to do this is to use a pre-compiled header for the project and have the following line in it.
    #define TARGET_API_MAC_CARBON 1 Make sure the Carbon target of your project does not link with InterfaceLib or any of the other OS 9 libraries. A Carbon xtra should only link with Carbonlib.
  2. If you are packaging an Xtra for download, you can use the same macintosh kit that for OS 9 and OS X xtras. However, the suffix indicating OS X package files is different - use .carb instead of .ppc for your carbon packages. Older versions of the Xtras Packager movie force macintosh packages to have a .ppc suffix so you may have to rename the file. For example, the following names could be used for a package files supporting Windows, Macintosh Classic and Macintosh OS X.
    • ovalspritepack.w32
    • ovalspritepack.ppc
    • ovalspritepack.carb

Xtra Developers Support

This XDK is provided as is, without support. Adobe does offer a private mailing list monitored by Adobe engineers and extremely helpful developers.

Additional Sources of Information

- General MOA information is in "MOA Development Issues" the MOA Developer's Guide.

- Useful tips are in "Tips, Guidelines, and Gotchas" in the Multimedia Developer's Guide.

- For the latest news, online docs, and FAQs about Xtras, surf to the Xtra Developers Center at http://www.adobe.com/support/xtras.


Copyright © 1999-2008, Adobe Macromedia Software LLC, Inc.