Difference between revisions of "Director"

From ScummVM :: Wiki
Jump to navigation Jump to search
(Add additional games and their versions.)
(Make the heading for the new graphical debugger better. The other debugger was already interactive by nature.)
 
(42 intermediate revisions by 13 users not shown)
Line 1: Line 1:
{{EngineDescription|
{{EngineDescription|
name=director|
name=director|
         developer=[[User:iskrich|iskrich, GSoC student]]|
         developer=[[User:sev|sev]], [[User:iskrich|iskrich]], [[User:djsrv|djsrv]], [[User:npjg|npjg]], [[User:Mstea|mstea]], [[User:moralrecordings|moralrecordings]]|
companies=[[Macromedia]]|
companies=[[Macromedia]]|
usedBy=hundreds of games|
usedBy=[[Director/Games|hundreds of games]]|
dateAdded=Not Added |
dateAdded=August 4, 2016 |
release=None|
release=2.5.0|
        status=Not (yet) part of ScummVM|
}}
}}
The Macromedia Director engine was partially implemented by [[User:iskrich|iskrich]] for the [[Summer of Code|Google Summer of Code]] in [[Summer of Code/GSoC2016|2016]] and was further implemented by the Google Summer of Code students [[User:djsrv|djsrv]] and [[User:npjg|npjg]] in [[Summer of Code/GSoC2020|2020]] and the Google Summer of Code students djsrv and [[User:sheep|sheep]] in [[Summer of Code/GSoC2021|2021]].


== Introduction ==
== Introduction ==
Started out as MacroMind VideoWorks. MacroMind was founded by Marc Canter. The name VideoWorks was changed to Director in 1987.
Director underwent huge number of versions.
Director underwent huge number of versions.


== Games and software ==
[http://lingoworkshop.com/articles/history History of the engine].
 
[[Director/Codenames|A bit more history of the engine codenames]]
 
==Games and software targeted by the engine==
This engine potentially targets a very large amount of games:
 
See [[Director/Games|Director Games]] for a list of known games and software, and their current state of support in the engine.
 
== Versions ==
See [[Director/Versions]]
 
== File Format ==
=== Archive Team's documentation ===
* [http://fileformats.archiveteam.org/wiki/Shockwave_(Director) Shockwave (Director)]
* [http://fileformats.archiveteam.org/wiki/Lingo_bytecode Lingo bytecode]
 
=== Team Earthquake's documentation ===
* [https://medium.com/@nosamu/a-tour-of-the-adobe-director-file-format-e375d1e063c0 A Tour of the Adobe Director File Format]
* [https://docs.google.com/document/d/18FMRZ0EvR2uF9rKTtvt-TXyIMFIBVg13bUhmV3_iHD0/edit Team Earthquake Shockwave Unofficial Documentation]
* [https://docs.google.com/document/d/1jDBXE4Wv1AEga-o1Wi8xtlNZY4K2fHxW2Xs8RgARrqk/edit More Director Movie File Unofficial Documentation] (has in-depth documentation of structs)
* [https://github.com/Brian151/OpenShockwave OpenShockwave repo] (rather unorganized documentation and tools including a Lingo decompiler)
* [https://github.com/Earthquake-Project Earthquake Project repos] (newer versions of the above)
 
== Development and Running ==
=== Running any D3 or D4 mac target ===
Besides adding specific md5s, there is a shortcut for forcing a directory to be detected as a director game.
 
Create an empty file named "D3-mac" or "D4-mac" in the game directory, and it will be detected as the respective Director version
 
=== Starting from an arbitrary movie file ===
Assuming, that you added game named 'workshop' with the method above.
 
./scummvm --start-movie=HandV workshop
Here HandV is the name of a movie in the directory. A frame number to start execution
can also be added:
 
./scummvm --start-movie=HandV@2 workshop
 
=== Executing lingo tests ===
Point ScummVM to engines/director/lingo/tests, that will create target 'directortest'. Launching it will try to compile and execute all *.lingo files in that directory. The tests can also be run from the command line with:
./scummvm -d11 -p engines/director/lingo/tests/ directortest
 
The option <tt>--start-movie=<script_name></tt> is also available to run a specific .lingo file.
 
=== Executing all director movies in a directory ===
Assuming you want to run all director movies in a given director. Create an empty file called 'lingotests-all' in that directory. Point ScummVM to that directory and add it as a game. That will run all director files in that directory. This can also be run from the commandline with:
./scummvm directortest-all-mac
 
=== Debug flags ===
There is a number of debugflags which could be turned on. The up-to-date list could be found in director.cpp in the DirectorEngine class constructor. You turn the flags with <tt>--debugflags=<flag>,<flag></tt>. Please, denote, that messages are often stored at several levels, so add with something like debug level 5, e.g. <tt>-d5</tt>. Example:
 
  ./scummvm --debugflags=lingoexec,lingocompile,slow -d6 --start-movie=TABLE.DIR chopsuey
 
The useful ones are:
 
* lingoexec -- tracing Lingo execution. There are varying levels of verbosity, --debuglevel=5 is probably the best for showing every instruction as it is executed.
* lingocompile -- details about Lingo script compilation
* lingoparse -- turns on Bison grammar trace. Verbose. You should know what you're doing
*lingostrict -- drop to the debugger if we hit a Lingo exception. This is a condition which would cause an interrupting error in the Macromedia Director editor; the player will just abort the script.
* compileonly -- useful with test targets when we load all files in the directory. This is how we created that status table of Lingo Workshop movies
* slow -- add 2s delay between every frame. Useful at higher debug levels, so you could see what is going on instead of munching megabytes of logs
* fast -- removes delay between frames
* bytecode -- execute precompiled bytecode instead of compiling Lingo. Lingo Workshop movies have both bytecode and script texts
* loading -- produces tons of deciphered data from movie files.
*sound -- log engine calls related to sound
*xobj -- log engine calls to third-party XLibs
 
=== Compilation ===
We aim for 0 memory leaks in the director engine. The automated tests will error when it detects a memory leak. To enable memory leak checks run `./configure` with `--enable-asan`.
 
=== Automated Tests ===
There is a CI (continuous integration) server running for Director.
* [https://john.scummvm.org Buildbot server]
* [https://github.com/rvanlaar/director-buildbot Buildbot server sourcecode]
 
=== Is my game a Director Game and which version is it? ===
 
Run the following command in the directory of your installed gamedata:
 
  grep --text -ir director|strings |egrep 'Macromedia Director [0-9]'
 
This will show which version of Macromedia Director was used. If this yields nothing, it probably isn't a Macromedia director game.
 
== Debugger Commands ==
To open the [[Debugging ScummVM|interactive debugger console]] press the key combination that is set for "Open Debugger" in the "Keymaps" tab from ScummVM options (default should be Ctrl+Alt+d).<syntaxhighlight lang="text">
Debug flags
-----------
debugflag_list - Lists the available debug flags and their status
debugflag_enable - Enables a debug flag
debugflag_disable - Disables a debug flag
debuglevel - Shows or sets debug level
 
Commands
--------
Player:
version - Shows the Director version
info - Shows information about the current movie
movie / m [moviePath] - Get or sets the current movie
frame / f [frameNum] - Gets or sets the current score frame
channels / chan [frameNum] - Shows channel information for a score frame
cast [castNum] - Shows the cast list or castNum for the current movie
nextframe / nf [n] - Steps forward one or more score frames
nextmovie / nm - Steps forward until the next change of movie
 
Lingo execution:
print / p [statement] - Evaluates a single Lingo statement
repl - Switches to a REPL interface for evaluating Lingo statements
backtrace / bt - Prints a backtrace of all stack frames
disasm / da [scriptId:funcName] - Lists the bytecode disassembly for a script function
disasm / da all - Lists the bytecode disassembly for all available script functions
stack / st - Lists the elements on the stack
scriptframe / sf - Prints the current script frame
funcs - Lists all of the functions available in the current script frame
var / v - Lists all of the variables available in the current script frame
markers / mk - Lists all of the frame markers in the current score
step / s [n] - Steps forward one or more operations
next / n [n] - Steps forward one or more operations, skips over calls
finish / fin - Steps until the current stack frame returns
continue / c - Continues execution
 
Breakpoints:
bpset / b - Creates a breakpoint at the current Lingo function and offset
bpset / b [funcName] - Creates a breakpoint on a Lingo function matching a name
bpset / b [offset] - Creates a breakpoint on the current Lingo function matching an offset
bpset / b [funcName] [offset] - Creates a breakpoint on a Lingo function matching a name and offset
bpset / b [scriptId:funcName] - Creates a breakpoint on a Lingo function matching a script ID and name
bpset / b [scriptId:funcName] [offset] - Creates a breakpoint on a Lingo function matching a script ID, name and offset
bpmovie / bm [moviePath] - Create a breakpoint on a switch to a movie
bpframe / bf [frameId] - Create a breakpoint on a frame in the score
bpframe / bf [moviePath] [frameId] - Create a breakpoint on a frame in the score of a specific movie
bpentity / be [entityName] - Create a breakpoint on a Lingo "the" entity being read or modified
bpentity / be [entityName] [r/w/rw] - Create a breakpoint on a Lingo "the" entity being accessed in a specific way
bpentity / be [entityName:fieldName] - Create a breakpoint on a Lingo "the" field being read or modified
bpentity / be [entityName:fieldName] [r/w/rw] - Create a breakpoint on a Lingo "the" field being accessed in a specific way
bpvar / bv [varName] - Create a breakpoint on a Lingo variable being read or modified
bpvar / bv [varName] [r/w/rw] - Create a breakpoint on a Lingo variable being accessed in a specific way
bpevent / bn [eventName] - Create a breakpoint on a Lingo event
bpdel [n] - Deletes a specific breakpoint
bpenable [n] - Enables a specific breakpoint
bpdisable [n] - Disables a specific breakpoint
bplist - Lists all breakpoints
 
GFX:
draw [cast|frame|off] - Draws debug outlines for cast or frame number
</syntaxhighlight>
 
=== lingo ===
Opens a lingo language shell.
) lingo on
lingo) set a to "Hello ScummVM"
lingo) put a
-- "Hello ScummVM
lingo) lingo off
)
 
Arguments:
* lingo on - Start the interactive lingo shell
* lingo off - Stop the interactive lingo shell
 
When the shell is on when the line starts with `lingo) `.


{| border="1"  cellspacing="0" cellpadding="4" width=75% class="sortable"
== Graphical Debugger ==
|- style="background:#efefef"
To enable the interactive debugger enable opengl graphics mode. In the gui: Global Options -> Graphics -> Graphics mode and select OpenGL. Run scummvm as follows:
|Product||Platform||Version||Notes
./scummvm --debugflags=imgui
|-
|Encarta 95||Mac||3.1||
|-
|Bookshelf 94||Win||?||it's 2.0 or so, good for simple animations
|-
|Win3.0 Multimedia Extensions||Win||2||
|-
|Encarta 95||Win||?||
|-
|Microsoft Dinosaurs||Win||2||
|-
|Who killed Sam Rupert?||Win||3.1||
|-
|Encarta 94||Win||2||
|-
|Explorer of the New World||Win||4.0.4||
|-
|Spy Club||Win||3.1||
|-
|The Book of the Dragon by Ciruelo||Win||7.0.2||
|-
|Spaceship Warlock||Mac|| 2 (?)||
|-
|The Journeyman Project Turbo!||Mac||4.0.3||
|-
|The Journeyman Project||Win/Mac||?||it's 3.0 or so
|-
|The Journeyman Project 2: Buried in Time||Mac||4||
|-
|AMBER: Journeys Beyond||Win/Mac||5||
|-
|Gundam 0079: The War for Earth||Win/Mac||5||
|-
|Majestic||Win/Mac||4.0b1||
|-
|Jewels of the Oracle||Win/Mac||4.0b1, 7||
|-
|Escape from Planet Arizona||Win||4.0.4||
|-
|Pyst||Win||?||Strangerke has this?
|-
|Nine||Win||5.0.1 r26||
|-
|The Dark Eye||Win/Mac||4.x||
|-
|Who killed Brett Penance? (murder mystery case 3)||Win||3.1.3?||
|-
|Gadget: Past as Future||Win||5||there's some discussion in scummvm forums
|-
|Voyeur 2||Win||6||
|-
|Stay Tooned!||Win/Mac||5||
|-
|Victor Vector & Yondo: The Dinosaur Egg||Win/Mac||3 (?)||
|-
|Victor Vector & Yondo: The Vampire's Coffin||Win/Mac||3 (?)||
|}


==External Links==
==External Links==
Line 80: Line 187:
* [https://github.com/scummvm-director/scummvm/tree/director another clone of it]
* [https://github.com/scummvm-director/scummvm/tree/director another clone of it]
* [https://en.wikipedia.org/wiki/Adobe_Director Wikipedia article on the topic]
* [https://en.wikipedia.org/wiki/Adobe_Director Wikipedia article on the topic]
* [https://www.mistys-internet.website/blog/blog/2022/01/06/do-you-speak-the-lingo/ Do You Speak the Lingo?] - blog post by Misty De Meo about the ScummVM engine's development


[[Category:Engines]]
[[Category:Engines]]

Latest revision as of 11:17, 24 May 2024

director
Engine developer sev, iskrich, djsrv, npjg, mstea, moralrecordings
Companies that used it Macromedia
Games that use it hundreds of games
Date added to ScummVM 2016-08-04
First release containing it 2.5.0

The Macromedia Director engine was partially implemented by iskrich for the Google Summer of Code in 2016 and was further implemented by the Google Summer of Code students djsrv and npjg in 2020 and the Google Summer of Code students djsrv and sheep in 2021.

Introduction

Started out as MacroMind VideoWorks. MacroMind was founded by Marc Canter. The name VideoWorks was changed to Director in 1987.

Director underwent huge number of versions.

History of the engine.

A bit more history of the engine codenames

Games and software targeted by the engine

This engine potentially targets a very large amount of games:

See Director Games for a list of known games and software, and their current state of support in the engine.

Versions

See Director/Versions

File Format

Archive Team's documentation

Team Earthquake's documentation

Development and Running

Running any D3 or D4 mac target

Besides adding specific md5s, there is a shortcut for forcing a directory to be detected as a director game.

Create an empty file named "D3-mac" or "D4-mac" in the game directory, and it will be detected as the respective Director version

Starting from an arbitrary movie file

Assuming, that you added game named 'workshop' with the method above.

./scummvm --start-movie=HandV workshop

Here HandV is the name of a movie in the directory. A frame number to start execution can also be added:

./scummvm --start-movie=HandV@2 workshop

Executing lingo tests

Point ScummVM to engines/director/lingo/tests, that will create target 'directortest'. Launching it will try to compile and execute all *.lingo files in that directory. The tests can also be run from the command line with:

./scummvm -d11 -p engines/director/lingo/tests/ directortest

The option --start-movie=<script_name> is also available to run a specific .lingo file.

Executing all director movies in a directory

Assuming you want to run all director movies in a given director. Create an empty file called 'lingotests-all' in that directory. Point ScummVM to that directory and add it as a game. That will run all director files in that directory. This can also be run from the commandline with:

./scummvm directortest-all-mac

Debug flags

There is a number of debugflags which could be turned on. The up-to-date list could be found in director.cpp in the DirectorEngine class constructor. You turn the flags with --debugflags=<flag>,<flag>. Please, denote, that messages are often stored at several levels, so add with something like debug level 5, e.g. -d5. Example:

 ./scummvm --debugflags=lingoexec,lingocompile,slow -d6 --start-movie=TABLE.DIR chopsuey

The useful ones are:

  • lingoexec -- tracing Lingo execution. There are varying levels of verbosity, --debuglevel=5 is probably the best for showing every instruction as it is executed.
  • lingocompile -- details about Lingo script compilation
  • lingoparse -- turns on Bison grammar trace. Verbose. You should know what you're doing
  • lingostrict -- drop to the debugger if we hit a Lingo exception. This is a condition which would cause an interrupting error in the Macromedia Director editor; the player will just abort the script.
  • compileonly -- useful with test targets when we load all files in the directory. This is how we created that status table of Lingo Workshop movies
  • slow -- add 2s delay between every frame. Useful at higher debug levels, so you could see what is going on instead of munching megabytes of logs
  • fast -- removes delay between frames
  • bytecode -- execute precompiled bytecode instead of compiling Lingo. Lingo Workshop movies have both bytecode and script texts
  • loading -- produces tons of deciphered data from movie files.
  • sound -- log engine calls related to sound
  • xobj -- log engine calls to third-party XLibs

Compilation

We aim for 0 memory leaks in the director engine. The automated tests will error when it detects a memory leak. To enable memory leak checks run `./configure` with `--enable-asan`.

Automated Tests

There is a CI (continuous integration) server running for Director.

Is my game a Director Game and which version is it?

Run the following command in the directory of your installed gamedata:

 grep --text -ir director|strings |egrep 'Macromedia Director [0-9]'

This will show which version of Macromedia Director was used. If this yields nothing, it probably isn't a Macromedia director game.

Debugger Commands

To open the interactive debugger console press the key combination that is set for "Open Debugger" in the "Keymaps" tab from ScummVM options (default should be Ctrl+Alt+d).

Debug flags
-----------
debugflag_list - Lists the available debug flags and their status
debugflag_enable - Enables a debug flag
debugflag_disable - Disables a debug flag
debuglevel - Shows or sets debug level

Commands
--------
Player:
 version - Shows the Director version
 info - Shows information about the current movie
 movie / m [moviePath] - Get or sets the current movie
 frame / f [frameNum] - Gets or sets the current score frame
 channels / chan [frameNum] - Shows channel information for a score frame
 cast [castNum] - Shows the cast list or castNum for the current movie
 nextframe / nf [n] - Steps forward one or more score frames
 nextmovie / nm - Steps forward until the next change of movie

Lingo execution:
 print / p [statement] - Evaluates a single Lingo statement
 repl - Switches to a REPL interface for evaluating Lingo statements
 backtrace / bt - Prints a backtrace of all stack frames
 disasm / da [scriptId:funcName] - Lists the bytecode disassembly for a script function
 disasm / da all - Lists the bytecode disassembly for all available script functions
 stack / st - Lists the elements on the stack
 scriptframe / sf - Prints the current script frame
 funcs - Lists all of the functions available in the current script frame
 var / v - Lists all of the variables available in the current script frame
 markers / mk - Lists all of the frame markers in the current score
 step / s [n] - Steps forward one or more operations
 next / n [n] - Steps forward one or more operations, skips over calls
 finish / fin - Steps until the current stack frame returns
 continue / c - Continues execution

Breakpoints:
 bpset / b - Creates a breakpoint at the current Lingo function and offset
 bpset / b [funcName] - Creates a breakpoint on a Lingo function matching a name
 bpset / b [offset] - Creates a breakpoint on the current Lingo function matching an offset
 bpset / b [funcName] [offset] - Creates a breakpoint on a Lingo function matching a name and offset
 bpset / b [scriptId:funcName] - Creates a breakpoint on a Lingo function matching a script ID and name
 bpset / b [scriptId:funcName] [offset] - Creates a breakpoint on a Lingo function matching a script ID, name and offset
 bpmovie / bm [moviePath] - Create a breakpoint on a switch to a movie
 bpframe / bf [frameId] - Create a breakpoint on a frame in the score
 bpframe / bf [moviePath] [frameId] - Create a breakpoint on a frame in the score of a specific movie
 bpentity / be [entityName] - Create a breakpoint on a Lingo "the" entity being read or modified
 bpentity / be [entityName] [r/w/rw] - Create a breakpoint on a Lingo "the" entity being accessed in a specific way
 bpentity / be [entityName:fieldName] - Create a breakpoint on a Lingo "the" field being read or modified
 bpentity / be [entityName:fieldName] [r/w/rw] - Create a breakpoint on a Lingo "the" field being accessed in a specific way
 bpvar / bv [varName] - Create a breakpoint on a Lingo variable being read or modified
 bpvar / bv [varName] [r/w/rw] - Create a breakpoint on a Lingo variable being accessed in a specific way
 bpevent / bn [eventName] - Create a breakpoint on a Lingo event
 bpdel [n] - Deletes a specific breakpoint
 bpenable [n] - Enables a specific breakpoint
 bpdisable [n] - Disables a specific breakpoint
 bplist - Lists all breakpoints

GFX:
 draw [cast|frame|off] - Draws debug outlines for cast or frame number

lingo

Opens a lingo language shell.

) lingo on
lingo) set a to "Hello ScummVM"
lingo) put a
-- "Hello ScummVM
lingo) lingo off
)

Arguments:

  • lingo on - Start the interactive lingo shell
  • lingo off - Stop the interactive lingo shell

When the shell is on when the line starts with `lingo) `.

Graphical Debugger

To enable the interactive debugger enable opengl graphics mode. In the gui: Global Options -> Graphics -> Graphics mode and select OpenGL. Run scummvm as follows:

./scummvm --debugflags=imgui

External Links