DML v10.0
Warning:
Whenever you import a DIR file, all existing files and subfolders inside a folder
called "assets" next to the DIR file are deleted (before all "externalizable" members of the DIR
file are exported to this folder), so be careful and use the tool on your own risk!
A DML file is a XML file that represents a Director movie (i.e. all persistent
information that is also stored in DIR file). Its document type definition can
be found at http://dasdeck.de/dtd/dml.dtd.
A DMZ file is a ZLIB-compressed DML file. DMZ files, even complete "inline" (see below) versions,
are often much smaller than the original DIR file (see screenshot "inline.png").
A DPL file is a another representation of a DML, it's simply a text file containing a nested property
list, in such a form that it can directly be parsed by using lingo's value() function.
NEW: In addition to DML/DMZ/DPL files, dml.exe can now also export JSON files.
The DML converter "dml.exe" allows to convert director movie files (*.dir, *.cst) into the DML/DMZ/DPL format and
vice versa. Since there are (currently) dml.exe versions for Director 10, 11.5 and 12, one possible use of DML is to
downgrade director movies to a previous file format, or upgrade to a later format (both without requiring a copy of
Director).
The DML format is based on the following simple rules:
- There are no attributes, everything is stored as element nodes, which makes it easy to parse
and represent the complete xml in a simple, nested property-list.
- The "JSON" idea: all data is represented in a way that lingo's value() function directly returns
the correct data type. E.g. a string is therefor not encoded as
<foo><![CDATA[hello!]]></foo>,
but as
<foo><![CDATA["hello!"]]></foo>
(and all quotes inside strings are encoded as '""E&"')
- The top level of a DML file looks like this:
<?xml version='1.0' encoding='iso-8859-1'?>
<!DOCTYPE movie SYSTEM 'http://dasdeck.de/dtd/dml.dtd'>
<movie>
<name><![CDATA["hello.dir"]]></name>
<centerStage>1</centerStage>
<exitLock>0</exitLock>
<editShortCutsEnabled>1</editShortCutsEnabled>
<displayTemplate>...</displayTemplate>
<window>...</window>
<assets>...</assets>
<score>...</score>
</movie>
Check out "hello1.dml" in folder "samples\hello world" for a complete basic sample.
- A DML file can contain "compiler directions" as XML processing instructions.
There are 2 types:
a) Pre-build commands which look like:
<?pre some-lingo-command?>
Those are executed before the DIR file is created.
Examples:
<?pre _player.debugplaybackenabled = 1?>
<?pre _movie.traceLoad = 1?>
<?pre _movie.traceScript = 1?>
b) Post-build commands which look like:
<?post some-lingo-command?>
Those are executed after the DIR file was succesfully compiled.
Examples:
<?post alert("DONE!")?>
<?post put "compilation time in sec.:" && ms/1000.0?>
<!-- uses shell xtra to make new file write-protected -->
<?post shell_cmd("attrib +R ""E&dirFile"E)?>
Notice 1: Compiler instructions are only supported directly under the movie node (=root).
Notice 2: Since those commands are executed in the scope of a local handler (using lingo's
do ... command), they can use local variables of that handlers. The following local variables
might be useful in post commands (like in the 2. example above):
- dmlFile: full path to DML or DMZ file
- dmlFolder: path to directory in which dmlFile resides (includes trailing "\")
- dirFile: full path to created DIR file
- ms: number of milliseconds it took to compile the file
And there are also some methods that might be useful, like:
- me.fileCopy (tFilenameFrom, tFilenameTo)
- me.fileDelete (tFilename)
- me.fileExists (tFilename)
- me.folderCreate (tFolder)
- me.folderDelete (tFolder)
- me.displayOpen (tTitle, tFilterMask, tDefaultFileName) -- display open file dialog
- me.displaySave (tTitle, tFilterMask, tDefaultFileName) -- display save file dialog
Normally the DML contains only all the properties of the castmembers, but their actual "media
data" (if there is any) is stored as external files in subfolders of the folder "assets", where
each subfolder represents a castLib.
But you can also have some or even all members "inline" inside the xml code, either as ASCII
data (e.g. <rtf>, <html>, <vertexList>, <txtfmt>) or as Base64 encoded binary data in a
<data> node.
When a DIR file with internal member data is "imported", dml.exe tries to export the media data
in a "common" file format, if possible/available. if there is none, the binary castmember media
data is exported as *.med file.
The currently available/currently selected export format(s) for each member type are specified in
dml.ini as "exportFormat" entries.
For field (and button) members, for which there is no "common" export format (other like text members
which have RTF), I invented a simple XML-based format called "txtfmt", which contains both the
text contents and the formatting information, but in separate nodes (its very simple type
definition can be found at http://dasdeck.de/dtd/fmt.dtd).
For an example of a simple txtfmt file (that represents a button text) see screenshot
"uedit_txtfmt.png"
dml.exe is a converter that can convert DML/DMZ/DPL <--> DIR in both directions, and in
addition "play" DML/DMZ/DPL files directly (by "compiling" a temporary DIR file and run it).
It can be customized with INI file "dml.ini" (see screenshots "uedit_ini1.png",
"uedit_ini2.png").
In addition to configuration via INI file, dml.exe also supports the following command line parameters (which
overwrite corresponding INI settings):
dml.exe [options] [input file]
Options:
-ddml show open dialog to select a DML file (to "compile" it to a DIR file)
-ddir show open file dialog to select a DIR file (to import it, i.e. save it as DML)
-o <outputfile>
-ds show "save as" dialog for output file
-z save DML as gzip-compressed file (*.DMZ)
-p save DML as lingo property list (*.DPL)
-j save DML as JSON file (*.json) -- NEW!
-x try to dynamically load xtras found in a "xtras" folder next to the DIR/DML/DPL/DMZ file
-r run resulting DIR file after DML file compilation
-i put all media data "inline" in DML
-v verbose mode, put status information to message window
Extract dml<XX>.zip to some permanent location, e.g. C:\dev\dml\DML<XX>
(<XX> = Director version, currently "10", "11" or "12")
Editor integration (optional, using UltraEdit as example)
(There are propably similar options for most other editors/IDEs)
Some sugestions:
1. Add the following 4 custom tools to UltraEdit (tool1...tool4):
a) XML validator (e.g. http://www3.altova.com/download/2007/altovaxml2007.exe)
b) Compile DML
c) Compile+Run DML
d) Import DIR
(for configuration see screenshots "uedit_tool...png", adjust the pathes according to the
path to your dml)
2. Create a new toolbar named "DML" and add those 4 custom tools to it
(see toolbar with tooltips in screenshots "uedit_01_validate.png", "uedit_02_compile.png",
"uedit_03_compile+run.png", "uedit_04_import_dir.png").
3. Add XML to the recognized languages (syntax file), and add the ending DML to the XML file
extensions
4. Add lingo to the sytax file (Notice: you can improve the lingo setting by manually adding the
following line:
/Function String = "%on ^([a-z,A-Z,0-9,_, ,(,)]+^)$"
This will cause that all handlers are displayed in UltraEdit's function list (see
"uedit_lingo_functions.png")
With those settings above all trace output of dml.exe (no matter if the message window is visible
or not) is returned to UltraEdit and displayed in the output window on the bottom (see
screenshots "uedit_message_win.png", "uedit_trace.png").
And you can use the free Altova XML validator to validate any DML and txtfmt files against there DTDs.
It's generally a good idea to do this before compiling a DML file which was manually edited.
Here some more screenshots that demonstrate UltraEdit integration:
"import_dir.png"
"sniffer.png"
"uedit_lingo.png"
"uedit_score.png"
And here some screenshots that show a DML document in "Altova XML Spy":
"xmlspy_text_view.png"
"xmlspy_text_view_all.png"
"xmlspy_grid_view.png"
Explorer integration (optional)
Open "dir.reg" / "dml.reg" / "dmz.reg" / "dpl.reg" in any text editor of your choice and adjust the pathes to the
dml folder (if other than C:\dev\dml\DML<XX>, where <XX> is either 10, 11 or 12). Then import the reg-files to the registry (by double-clicking).
Now you can convert DIR files to DML/DMZ/DPL, "compile" DML/DMZ/DPL to DIR files, or directly "run" them (=compile,
and then run using dml.exe as projector) in explorer by selecting the corresponding context menu item (see
screenshot "explorer_context_menu_dml.png")
You may also adjust the path to your favorite text editor in file "dml_editor.reg" and then import it to the
registry, which adds an "Edit" entry to the Explorer's context menu for DML-files.
Run "remove.reg" to remove all DML-related registry keys again.