14
edits
Difference between revisions of "Director"
Jump to navigation
Jump to search
Updated engine authors, added debugger commands
(Add howto check if a game is made with Director) |
(Updated engine authors, added debugger commands) |
||
| (19 intermediate revisions by 10 users not shown) | |||
| Line 1: | Line 1: | ||
{{EngineDescription| | {{EngineDescription| | ||
name=director| | name=director| | ||
developer=[[User:sev|sev]], [[User:iskrich|iskrich]]| | 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=August 4, 2016 | | dateAdded=August 4, 2016 | | ||
release=| | release=2.5.0| | ||
}} | }} | ||
The Macromedia Director engine was partially implemented by [[User:iskrich|iskrich]] for the [[Summer of Code|Google Summer of Code]] in 2016. | 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. | ||
[http://lingoworkshop.com/articles/history History of the engine]. | [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== | ==Games and software targeted by the engine== | ||
| Line 21: | Line 25: | ||
== Versions == | == 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 == | == Development and Running == | ||
| Line 34: | Line 50: | ||
./scummvm --start-movie=HandV workshop | ./scummvm --start-movie=HandV workshop | ||
Here HandV is the name of a movie in the directory | 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 === | === Executing lingo tests === | ||
| Line 53: | Line 72: | ||
The useful ones are: | The useful ones are: | ||
* lingoexec -- tracing Lingo execution | * 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 | * lingocompile -- details about Lingo script compilation | ||
* lingoparse -- turns on Bison grammar trace. Verbose. You should know what you're doing | * 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 | * 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 | * 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 | ||
| Line 61: | Line 81: | ||
* bytecode -- execute precompiled bytecode instead of compiling Lingo. Lingo Workshop movies have both bytecode and script texts | * 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. | * 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 === | === Automated Tests === | ||
There is a CI (continuous integration) server running for Director. | There is a CI (continuous integration) server running for Director. | ||
* [https:// | * [https://john.scummvm.org Buildbot server] | ||
* [https://github.com/rvanlaar/director-buildbot Buildbot server sourcecode] | * [https://github.com/rvanlaar/director-buildbot Buildbot server sourcecode] | ||
=== Is my game a Director Game and which version is it? === | === Is my game a Director Game and which version is it? === | ||
Run the following command in the | Run the following command in the directory of your installed gamedata: | ||
grep --text -ir director|strings |egrep 'Macromedia Director [0-9]' | 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. | 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) `. | |||
| Line 81: | Line 184: | ||
* [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]] | ||