The Director Object Model

The runtime hierarchy - Player, Movies, Casts, Score, Stage, sprites - and the global scripting facades that expose it.

The hierarchy#

Director Player (_player)
  Window(s): the Stage window + MIAWs
    Movie (_movie)
      Cast libraries (castLib)
        Cast members (member): media + scripts
      Score
        Frames (timeline)
        Channels: sprite channels + tempo/palette/transition/sound/script
      Stage: composited output of the current frame's sprites
  Global services: _mouse, _key, _sound, _system, _global

Everything a script touches hangs off this tree. A movie owns casts and a score; sprites exist only as score/runtime state; the stage is the render target; the player owns movies and windows.

The scripting facades (MX 2004)#

Every facade property has a verbose the ... equivalent, and shipped code overwhelmingly uses the verbose forms. Both must resolve to the same state.

Top-level constructor/lookup functions complete the model: member(), sprite(), castLib(), window(), xtra(), script(), sound(), channel(), plus value constructors list(), propList(), point(), rect(), rgb(), paletteIndex(), symbol(), image(), date(), timeout(), vector(), transform().

Movie properties worth knowing#

_movie.frame                -- current frame number (the frame)
_movie.frameLabel           -- marker name at current frame
_movie.lastFrame            -- highest authored frame
_movie.name / .path         -- file identity
_movie.stage                -- the stage window object
_movie.actorList            -- stepFrame subscribers
_movie.timeoutList          -- active timeout objects
_movie.updateStage()        -- immediate redraw
_movie.go(x) / goLoop() / goNext() / goPrevious()
_movie.puppetTempo(fps)
_movie.stopEvent() / sendSprite() / sendAllSprites()

Windows and MIAWs#

A movie plays in a window; the main one is the Stage (_movie.stage / (the stage)). Additional movies can run simultaneously in their own windows (Movies In A Window):

w = window().new("tool palette")
w.fileName = "palette.dir"
w.rect = rect(100, 100, 420, 340)
w.titlebarOptions.visible = TRUE
w.open()
...
w.close()
w.forget()

• Each MIAW is a full movie with its own score, casts, and event flow; tell window "x" to ... (classic) or direct object calls cross the boundary. Globals are shared across all movies in the player.
• Window events: openWindow, closeWindow, activateWindow, deactivateWindow, moveWindow, resizeWindow, zoomWindow.
• Window types/appearance: windowType (classic) and MX 2004 appearanceOptions/titlebarOptions; layering via moveToFront/moveToBack, modality via window.modal.
• The stage itself is a window object: (the stage).image reads back the composited frame (see Native rendering for how that buffer behaves), (the stage).rect moves/resizes the playback window.

For preservation, MIAWs matter mostly for authoring tools and multi-window desktop titles; web-era Shockwave games rarely used them (the browser plugin ran one movie), but (the stage) tricks are everywhere.

Coordinate spaces#

• Stage coordinates: pixels, origin at the stage's top-left, y down. Sprite loc, the mouseLoc, the clickLoc all live here.
• Screen coordinates: window rect and the deskTopRectList are desktop-relative; (the stage).rect gives the stage's screen placement.
• Member coordinates: a member's rect is its intrinsic pixel size at regPoint-relative origin; mapStageToMember() and mapMemberToStage() convert between spaces (essential for imaging and hit logic).

The native runtime keeps a separate presentation record (window/client rect) distinct from logical stage coordinates; resizable projectors recompute it rather than rescaling sprite coordinates. Details in Native stage and presentation.

Authority: who owns sprite state#

The score authors sprite state per frame; Lingo can override it. The rules:

• Without puppeting, score data reasserts channel state at each frame boundary (a runtime locH change lasts until the next frame's score sync, except where the sprite is tweened/keyframed identically).
• puppetSprite n, TRUE hands the whole channel to Lingo until puppeting ends; the score stops updating it.
• MX 2004 "auto-puppeting": setting sprite properties from a behavior on that sprite persists for the span without explicit puppeting.
• Score synchronization happens at frame entry, before beginSprite/prepareFrame/enterFrame of the new frame, so handler writes in those events land after the sync and are visible during that frame's render.

This ordering is one of the most compatibility-sensitive contracts in the runtime; emulators that re-apply score state late (during render) break every game that animates in prepareFrame.