Memory, Preloading, and Streaming

Cast member loading and unloading, purge priorities, preload APIs, Shockwave streaming order, and network loading semantics.

The loading model#

Cast member metadata loads with the movie; member media loads lazily on first use unless preloaded. Under memory pressure Director evicts media by purge priority. This lazy model is why old CD titles stutter on first display of big art, and why authored code is full of explicit preloads.

member("bigBG").purgePriority = 0
put member("bigBG").loaded          -- TRUE when media is in RAM

Preload and unload APIs#

preLoad 25, 50               -- load media for frames 25-50 (stops when RAM full)
preLoad "menu"               -- through a marker
preLoadMember 10, 50         -- members 10-50
preLoadMember "BigBackground"
preLoadMovie "intro.dir"     -- next movie's first-frame media
unLoad 25, 50                -- release frame-range media
unLoadMember 10, 50
unLoadMovie "intro.dir"

the preLoadMode of castLib   -- 0 when needed / 1 before frame 1 / 2 after frame 1
member(m).preLoad            -- per-member preload flag (3D/video variants differ)
the preLoadRAM               -- cap for video preloading

Memory inspection:

the memorySize        -- total RAM available to Director
freeBytes()           -- free block total
freeBlock()           -- largest contiguous free block
ramNeeded(f1, f2)     -- bytes needed for a frame range
the movieFileSize

Idle-time loading (MX 2004): the idleLoadMode, idleLoadTag, idleLoadPeriod, cancelIdleLoad(), finishIdleLoad(), idleLoadDone() schedule preloads during idle events instead of blocking.

Shockwave streaming#

A .dcr movie streams in a defined order:

1. Score, scripts, and non-media metadata (the movie can start).
2. Media required by the initial frames, in Score order.
3. Remaining media in Score order, in the background.

Consequences that shipped content designs around (and emulators must respect):

• A movie can reach frame N while media for frame N+k is absent. Sprites whose media is missing render as placeholders (nothing or a box) until data arrives; scripts referencing unloaded members by script-only paths can fail.
• the mediaReady of member tests availability; frameReady(n) / frameReady(n1, n2) test whole frames; movies gate navigation on these ("Please wait" loops).
• the streamMode / authored playback options choose whether playback blocks or streams.
• External casts stream separately; preLoadNetThing warms the browser/disk cache for any URL without parsing it.

on exitFrame
  if frameReady(marker("game")) then
    go "game"
  else
    go the frame          -- loading loop
  end if
end

Network operations#

The async network API (browser-provided in Shockwave, Xtra-provided in projectors):

id = getNetText("http://example.com/data.txt")     -- start async fetch
id = postNetText(url, propListOrString)            -- POST
preloadNetThing(url)                                -- cache warm
downloadNetThing(url, localFile)                    -- projector-only file download
gotoNetMovie(url)                                   -- stream-replace the movie
gotoNetPage(url, target)                            -- drive the browser

-- polling pattern (netDone defaults to the LAST started operation)
on exitFrame
  if netDone(id) then
    if netError(id) = "OK" then
      txt = netTextResult(id)
    end if
    ...
  else
    go the frame
  end if
end

• Operations are identified by net IDs (getLatestNetID for legacy code); a small fixed pool of concurrent operations exists (4 in classic players), and further requests queue.
• netError() returns "OK", "" (pending) or an error string/code; netMIME(), netLastModDate() inspect results; netAbort(id) cancels.
• Results must be collected reasonably soon; each completed operation's buffer is released when reused.
• netTextResult is text; binary transport was done via Xtras or downloadNetThing.
• Security: Shockwave restricted URLs to the movie's origin scheme and blocked local file access; the safePlayer reports sandbox state.

Memory behavior worth emulating#

• Loading is synchronous at the point of need: touching an unloaded member's media blocks that frame (the authentic stutter). Preload exists to move that cost.
• Unload calls are hints tied to purge priority, not immediate frees.
• unLoad/preLoad never affect the file; casts are read-only at runtime (except saveMovie/save castLib in projectors, used by authoring tools built in Director).
• Streaming placeholders and mediaReady gating are observable behavior that loading screens depend on; an emulator with everything instantly available should still report frameReady() truthfully (TRUE) so wait-loops exit.