{"id":114,"date":"2026-07-28T15:32:05","date_gmt":"2026-07-28T15:32:05","guid":{"rendered":"https:\/\/blogs.scummvm.org\/ramyak\/?p=114"},"modified":"2026-07-28T15:32:05","modified_gmt":"2026-07-28T15:32:05","slug":"you-are-here","status":"publish","type":"post","link":"https:\/\/blogs.scummvm.org\/ramyak\/2026\/07\/28\/you-are-here\/","title":{"rendered":"You are here"},"content":{"rendered":"

Most of a Director game is one movie playing at a time. You leave one, you enter the next, and the engine only ever has a single score ticking over. But Director also lets a cast member be<\/em> another whole movie (a \u201cmovie cast member\u201d, #movie<\/code> in Lingo) that runs in parallel, inside a sprite, while the host movie keeps going around it. This week I made ScummVM actually do that.<\/p>\n

Director’s vocabulary, quickly: a movie<\/strong> is a timeline (its score<\/strong>) of frames<\/strong>. Each frame has numbered channels<\/strong>, and a sprite<\/strong> sitting in a channel is one on-screen instance of a cast member<\/strong>, an asset from the movie’s library. The stage<\/strong> is the window everything draws into, and Lingo<\/strong> is Director’s scripting language.<\/p>\n

The thing that forced the issue is the mini-map in Star Trek: TNG Interactive Technical Manual<\/em>. You walk the decks of the Enterprise-D in a QuickTime VR panorama, and in the corner there\u2019s a little schematic of the deck with a marker showing where you are. That mini-map isn\u2019t a picture the host draws: it\u2019s a separate Director movie<\/strong>, linked in as a cast member, running its own scripts, watching a shared global to know where the marker goes, and setting another global to send you somewhere when you click it. Get movie cast members working and the mini-map comes alive. That was the goal.<\/p>\n

By the time the mini-map worked I had three problems on my list that looked entirely unrelated, to each other and to it: the host’s caption text had stopped drawing, the input queue was growing without bound, and DT, the debugger, was flickering between two movies\u2019 scores several times a second. I assumed three bugs. Underneath, they were one.<\/p>\n

A cast member that drew nothing<\/h5>\n

Movie cast members and film loops share the exact same layout on disk. The only real difference is a single flag: a film loop is a canned animation, a movie cast member runs its own Lingo (scriptsEnabled<\/code>). Because of that shared format, ScummVM already modelled MovieCastMember<\/code> as a subclass of FilmLoopCastMember<\/code>, and inherited the film loop\u2019s loader, which looks for an embedded SCVW<\/code> resource. A movie cast member doesn\u2019t have one. Its content lives in a separate movie file<\/em>, named in the cast info. So the loader found nothing, and the cast member drew nothing at all<\/strong>.<\/p>\n

The first job, then, was a real load()<\/code>: take the linked path out of the cast info, resolve it with findMoviePath<\/code>, open the archive, and build a proper Movie<\/code> out of it that the cast member owns. Point the inherited _score<\/code> at that movie\u2019s score and suddenly there are frames to draw.<\/p>\n

There was also a bug. The moment the linked movie loaded, the whole stage resized itself to the mini-map\u2019s dimensions and the panorama vanished. A movie, when it loads, assumes it owns the stage: it resizes the window, recentres it, repaints the background colour. That\u2019s correct for a movie you open normally, and completely wrong for one living inside a sprite on someone else\u2019s stage.<\/p>\n

The fix is a flag, Movie::_isEmbedded<\/code>, set on the linked movie. Anywhere loadArchive()<\/code> reaches for the stage, it now checks that flag first and leaves it alone. An embedded movie borrows the host\u2019s window; it never gets to own it<\/strong>. That flag turns out to be load-bearing: it comes back to guard rendering twice more before this is over.<\/p>\n

\"Class
Where a movie cast member sits: it subclasses the film-loop cast member and owns a linked Movie, which points back at the host through _parentMovie.<\/figcaption><\/figure>\n
Running in parallel<\/h5>\n

Here is the idea that organizes everything below, and it isn’t mine, sev handed it to me at the start: a movie cast member is a Window<\/code> that doesn’t own a window.<\/strong> A real ScummVM Window<\/code> has its own current movie, its own execution state, and its own step. A movie cast member needs all three, but it has to borrow them from the host, use them for exactly one step, and give them back. Every fix in this post is a consequence of getting that borrow-and-return right.<\/p>\n

Start with the step. Loading a movie is not the same as running one. A film loop is a flipbook: you just ask it for the sprites at frame N<\/em>. A movie cast member has to step<\/em>: run its frame scripts, honour go<\/code>, fire its events, advance. So update()<\/code> now steps the linked movie\u2019s score exactly like a real movie does.<\/p>\n

The word \u201cexactly\u201d hides a decision: how fast does it step? A movie has its own tempo channel, so should the mini-map run at its own tempo, independent of the host? Rather than guess, I built a test movie in Director 4: a host at one tempo with an embedded movie authored at a different one, each incrementing a visible counter, and watched what the original engine did. The counters stayed locked together. Under D4, a movie cast member ignores its own tempo channel entirely and advances once per host frame<\/strong>, no independent clock, no drift. I’ve only verified this for D4; if D5 or D6 differ, that’s the first thing I’d re-check.<\/p>\n

Then there\u2019s the question of whose<\/em> movie is \u201ccurrent\u201d. Almost everything in Lingo resolves against the current movie: go<\/code>, handler lookup, cast lookup, the clickOn<\/code>. If the mini-map\u2019s go<\/code> is going to move the mini-map and not the panorama, the linked movie has to be the current movie while it steps. So update()<\/code> swaps the window\u2019s current movie to the linked one, steps, and swaps it back. For the duration of one step, the embedded movie is the current movie, and everything in Lingo resolves against it.<\/p>\n

Reaching out, and getting on screen<\/h5>\n

Two things fell out of the borrow that I hadn\u2019t planned for. First, the mini-map\u2019s scripts call handlers that don\u2019t exist in the mini-map: levelblinker<\/code> lives in the host<\/em>. And they read cast members that also live in the host. The linked movie isn\u2019t self-contained; it\u2019s written assuming it can reach up into whatever movie loaded it. That gave Movie<\/code> a second new member, _parentMovie<\/code>, and handler and cast lookups now fall back to it when the embedded movie comes up empty. The mini-map simply doesn\u2019t run without it.<\/p>\n

This fallback makes this<\/em> title work, and it might be the wrong general answer: Director also has shared and external cast libraries, and a message hierarchy with a specified order, and it’s possible the “authentic” fix for another game is one of those rather than “fall back to whoever loaded me.” I verified that the mini-map needs the parent for levelblinker<\/code> and its cast lookups; I have not<\/em> verified that “fall back to the parent” is what Director itself does in general.<\/p>\n

\"Per-frame
One host frame: the host steps the linked movie, which refreshes its own channels; the host then pulls those channels into the sprite through getSubChannels().<\/figcaption><\/figure>\n

Second, getting the embedded movie\u2019s pixels onto the screen. Rendering in ScummVM’s Director engine is pull-based<\/em>: a window renders the channels of its current movie and nothing else. The embedded movie is never the window\u2019s real current movie (only for that flicker of a step), so it can\u2019t push itself onto the stage. Instead the host pulls<\/em>: the embedded movie\u2019s own renderFrame()<\/code> refreshes its channels but, seeing _isEmbedded<\/code>, stops short of drawing them anywhere, and then getSubChannels()<\/code> takes those live channels, scales them into the sprite\u2019s bounding box, and composites them. \u201cLive\u201d is the important word<\/strong>: it\u2019s the actual running channels, so anything the mini-map\u2019s scripts change shows up immediately.<\/p>\n

Ghost in the corner<\/h5>\n

With all that in place the mini-map appeared, animated, and tracked my position. And it also drew a second copy of itself, small and wrong, jammed into the top-left corner of the stage.<\/p>\n

My first guess was a highlight artifact, something about the sprite\u2019s hilite flag drawing where it shouldn\u2019t, so I tried guarding that. It didn\u2019t help, and I dropped it.<\/p>\n

The real cause was the pull-based rule again, from the other side. When the embedded movie stepped and called something that triggered updateStage<\/code>, it went all the way into Window::render()<\/code> and rendered its own<\/em> channels onto the shared window, at the embedded movie\u2019s native origin, which is the top-left of the stage. The composite path was doing its job in the sprite; this was a second, illegitimate path drawing the same content in the wrong place.<\/p>\n

The guard I added is at the top of Window::render()<\/code>: if the current movie is embedded, return immediately. It’s a guard; I’m discarding a render request that should never have travelled this far, rather than modelling what updateStage<\/code> “should” do for an embedded movie in real Director. For this engine the invariant I want holds either way, an embedded movie reaches the stage through exactly one door, getSubChannels()<\/code>, and no other<\/strong>. Ghost gone.<\/p>\n

Two other things were wrong by this point, and I was ignoring both. Mouse events were piling up in the queue instead of draining. DT was flickering between two scores. Neither seemed connected to anything I’d just done, so I wrote them down and kept going.<\/p>\n

Text that wouldn’t draw<\/h5>\n

The mini-map worked, but a piece of the host<\/em> broke: the panorama\u2019s description text (the caption that tells you what you\u2019re looking at) stopped drawing. It rendered fine on master<\/code>. Something in my branch had killed it.<\/p>\n

I couldn\u2019t see it by reading, so I bisected (kind of). First across the commit series: build each commit, run it, look for the text. One commit was fine, the next was broken, which pinned it to “run the movie cast member as a parallel movie”. That’s a big commit, so I bisected within<\/em> it, as a designed ladder of four builds, each enabling one more thing than the last:<\/p>\n