This document has been written in an attempt to help new developers to the world of Director Xtras. This guide is focused purely for the PC using MSVC++.
Although I would not classify myself as an Xtra guru, I think everything included in this document should be correct. If you find any errors, omissions, or poor xtra coding practice please email me at
noise [{at}] noisecrime.com
First you’ll need the Director XDK 8.5 from MM website. Download it from ?
Of course you’ll also need a compiler ideally for PC’s that would be MSVC++ v6 as this has been used to create and compile all the examples that come with the XDK.
One final item is a GUID generator. This will generate a unique ID everytime its used, and is required for every Xtra . If any two xtras have the same GUID, Director will complain about duplicate xtras.
Its best to be organised from the beginning so create a new directory on your hard drive to keep all your xtra development work in. For example in this Doc will call it “Xtra_development”. Unzip the D8.5 XDK into this folder, making sure the contents of the XDK are a level down (xtra_ development /xdk85_win/contents).
Keeping things tidy, create another directory within ‘Xtra_development called ‘Xtras’, this is where you can keep all the xtras that you are working on.
The main reason I’m stating this is that you have to add an include path to MSVC to the XDK include folder. With an outline of the directory structure above, it should be clearer to describe.
Finally make a copy of the Skeleton scripting Xtra from Xtra_development/xdk85_win/examples/script/ to Xtra_development/Xtra/Skeleton
Make sure you use skeleton, not skeleton 2. The only difference is that in skeleton2 the registration and xtrascript sections have been combined into one, and whilst this is better, its not so easy to learn from.
When I open a MSVC workspace on a project that has been copied or moved to another folder I find all the links to the files retain their original directory path. So if I was to edit script.cpp in my copied skeleton xtra folder, the original file not the copied one would get updated. In addition I found other similar little problems with MSVC, so I have developed my own practice when starting a new xtra. Because the skeleton xtra is already set up for MSVC I don’t want to lose its project settings, but basically I clear out everything else and start from scratch.
Changing names 1 Select the ‘Skeleton’ folder, and change its name to ‘myFirstXtra’
7 Bring up the Add files to project browse box again, change the type to any (*.*), go into the winproj folder and select myFirstXtra.def. Once imported, double click myFirstXtra.def and change the LIBRARY name from SCRIPT to MYFIRSTXTRA – keep the CAPS! Once changed save it.
static char msgTable[] = {
"xtra myFirstXtra\n" \ "new object me\n" /* standard first handler entry in all message tables */
"-- Template handlers --\n" "* mfx_globalHandler -- prints Hello message\n" "+ mfx_parentHandler object xtraRef -- prints parent handler message\n" "mfx_childHandler object me -- prints child handler message\n" };
The addition of ‘mfx_’ (My First Xtra) is just to ensure that the globalhandler call doesn’t conflict with any other xtras, as its unlikely anyone else would have used this naming convention. In the future you should come up with your own naming convention, for example I use NCP_handlername.
11. Open cregister.h, scroll down to find the line #error PLEASE DEFINE A NEW CLSID Comment this line out, open the GUID generator and get a new GUID. Copy this to below the commented line.
// {4CA5E661-A9F9-11d6-BFFC-000102F413ED} DEFINE_GUID(<<name>>, 0x4ca5e661, 0xa9f9, 0x11d6, 0xbf, 0xfc, 0x0, 0x1, 0x2, 0xf4, 0x13, 0xed);
This is what I get from Guidgen.exe,but we don’t need all of it. Delete the first line, then replace <<name>> with the Class ID of this class. In this case its CLSID(CRegister) so it now reads
// #error PLEASE DEFINE A NEW CLSID DEFINE_GUID(CLSID(CRegister),0x4ca5e661, 0xa9f9, 0x11d6, 0xbf, 0xfc, 0x0, 0x1, 0x2, 0xf4, 0x13, 0xed);
12. Open cscript.h. scroll down and repeat step 11 for defining the GUID. Remember you need to create another new GUID for this class, don’t use the same one! Howver Note that the class name is now Cscript
// #error PLEASE DEFINE A NEW CLSID DEFINE_GUID(CLSID(CScript),0x4ca5e662, 0xa9f9, 0x11d6, 0xbf, 0xfc, 0x0, 0x1, 0x2, 0xf4, 0x13, 0xed);
Then scroll down to the very end of the file, where it says ‘enum’ and replace the names with the updates you made to the message table in cregister.cpp, so it reads.
enum { m_new = 0, /* standard */
m_mfx_globalHandler, m_mfx_parentHandler, m_mfx_childHandler,
m_XXXX };
1 Minimise MSVC and locate the myFirstXtra.x32 file in Xtra_development/Xtra/Skeleton/winproj/debug or release depending on your compile setting.
Don’t have Director open when you build a new version of an xtra. MSVC will complain because the file is already in use, and can’t be overwritten.
Have you placed it, or a shortcut in the Director/xtra folder? Does it appear in the ‘put the xtralist’ list?
Check you’re messageTable – THOUROUGHLY. Its amazing how little errors such as a missing comma between handler arguments can creep in when witing it. Doing so will cause the xtra to fail.
Be sure you’reusing the correct version of the xtra, and the right build, its easy to get mixed up between Debug and Release builds.