@swf2es/player-hosts 0.0.0-stage → 0.1.0

package/dist/thread/player/scripting/lifecycle.js

@@ -0,0 +1,272 @@
+// What happens to a display object with an AS3 object as it comes and
+// goes: ADDED and ADDED_TO_STAGE as it is put on the display list, REMOVED
+// and REMOVED_FROM_STAGE as it is taken off, and, off it, its life as an
+// orphan, which plays on as Flash's does, for a while (docs/architecture/player.md,
+// "Orphans").
+import { avm2 } from "../../runtime/index.js";
+import { Container, MovieClip, scriptWork } from "../display/display.js";
+import { stopTimelineSoundsUnder } from "../media/sounds.js";
+import { dispatchEvent, heard } from "./events.js";
+export class Lifecycle {
+    s;
+    /**
+     * Clips taken off the display list, which play on as Flash's do: held
+     * weakly, as Ruffle holds them, so one nothing refers to stops as Flash's
+     * does once collected, and for ORPHAN_FRAMES at most. One the timeline
+     * took is kept for its frame only.
+     */
+    orphans = new Map();
+    madeThisFrame = [];
+    /**
+     * The children whose removal is being told of, by the error Flash throws
+     * at a script that removes one again from a listener meanwhile: #2094
+     * while a script's removal tells of it, #2025 while the timeline's does.
+     */
+    leaving = new Map();
+    constructor(s) {
+        this.s = s;
+    }
+    /** Display objects scripts made with `new` this frame: their first frame's script runs after everything else's, and they are orphans after. */
+    get fresh() {
+        return this.madeThisFrame;
+    }
+    /** Whether `d` is on the display list: under the stage. */
+    onStage(d) {
+        for (let o = d; o; o = o.parent) {
+            if (o === this.s.stage) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * `display` has a parent now: ADDED to it, bubbling, and, if it is on
+     * the display list, ADDED_TO_STAGE to it and each descendant, in tree
+     * order, as Flash dispatches them.
+     */
+    added(display) {
+        this.orphans.delete(display.serial);
+        this.dispatch(display.object, "added", true);
+        if (this.onStage(display)) {
+            this.eachObject(display, (o) => this.dispatch(o, "addedToStage", false));
+        }
+    }
+    /**
+     * The main SWF's root, on the stage before its constructor ran, once
+     * that has returned: ADDED and ADDED_TO_STAGE to it alone, as Flash and
+     * AIR tell it (measured in adl); what its constructor added to it was
+     * told as it was added. ADDED comes even to a root that its constructor
+     * took off the stage, ADDED_TO_STAGE only to one still on it after that.
+     */
+    rootConstructed(root) {
+        this.dispatch(root.object, "added", true);
+        if (this.onStage(root)) {
+            this.dispatch(root.object, "addedToStage", false);
+        }
+    }
+    /**
+     * `display` is about to lose its parent: REMOVED, bubbling, and
+     * REMOVED_FROM_STAGE through the subtree if it was on the display list.
+     * It then plays on as an orphan; the timeline's removal has it play its
+     * removal frame only, and takes the parent's property of its name away;
+     * a script that removes it meanwhile throws #2025, as Flash's does.
+     */
+    removing(display, byTimeline = false) {
+        // Before the listeners, which may move it: the property to clear is the one of the parent
+        // that loses it, and one they put back on a list is no orphan (`added`).
+        const parent = display.parent?.object;
+        this.orphan(display, !byTimeline);
+        if (byTimeline) {
+            this.telling(display, 2025);
+        }
+        else {
+            this.tell(display);
+        }
+        if (byTimeline && parent && display.timelineNamed) {
+            const name = avm2.qname(avm2.publicNs, display.name);
+            if (this.s.rt.getProperty(parent, name) === display.object) {
+                this.s.rt.setProperty(parent, name, null);
+            }
+        }
+    }
+    /**
+     * A script removes `display` from its parent: told of as `removing` does,
+     * and then taken from wherever a listener put it meanwhile, as Flash
+     * does. One whose removal is being told of already is not removed again:
+     * Flash throws, and the first removal goes on.
+     */
+    remove(display) {
+        const error = this.leaving.get(display);
+        if (error !== undefined) {
+            throw this.s.rt.error(error === 2025 ? "ArgumentError" : "Error", error);
+        }
+        this.telling(display, 2094);
+        this.orphan(display);
+        display.parent?.removeChild(display);
+    }
+    /**
+     * REMOVED and REMOVED_FROM_STAGE told of `display`; a script that
+     * removes it meanwhile is thrown `error`.
+     */
+    telling(display, error) {
+        // Told of again inside its own telling: the outer one's error holds until it ends.
+        if (this.leaving.has(display)) {
+            this.tell(display);
+            return;
+        }
+        this.leaving.set(display, error);
+        try {
+            this.tell(display);
+        }
+        finally {
+            this.leaving.delete(display);
+        }
+    }
+    tell(display) {
+        this.dispatch(display.object, "removed", true);
+        if (this.onStage(display)) {
+            this.eachObject(display, (o) => this.dispatch(o, "removedFromStage", false));
+        }
+    }
+    /**
+     * `display` is off the display list with an AS3 object that may play
+     * it, taken off by a script, or by the timeline, which keeps it for its
+     * frame only, not `keep`.
+     */
+    orphan(display, keep = true) {
+        if (display.object && !this.orphans.has(display.serial)) {
+            this.orphans.set(display.serial, { ref: display.ref, keep, since: this.s.frames });
+            scriptWork.changes++;
+        }
+    }
+    /**
+     * A script made `display` with `new`. Flash runs its first frame's
+     * script at the end of this frame's, in the order made, has it sit out
+     * the next frame's advance, and plays it on from there, on the display
+     * list or as an orphan.
+     */
+    made(display) {
+        this.madeThisFrame.push(display);
+        scriptWork.changes++;
+        if (display instanceof MovieClip) {
+            display.fresh = true;
+        }
+    }
+    /** The orphans still there, newest first, as Flash runs their frames. */
+    orphanRoots() {
+        const roots = [];
+        for (const [serial, orphan] of this.orphans) {
+            const display = orphan.ref.deref();
+            if (!display) {
+                this.orphans.delete(serial);
+                continue;
+            }
+            roots.push(display);
+        }
+        return roots.sort((a, b) => b.serial - a.serial);
+    }
+    /** Whether `display` or anything under it listens for a frame's broadcast events. */
+    hearsFrames(display) {
+        if (display.object) {
+            for (const targets of this.s.broadcasts.values()) {
+                if (targets.has(display.object)) {
+                    return true;
+                }
+            }
+        }
+        const children = display.frameChildren;
+        for (let i = 0; i < children.length; i++) {
+            if (this.hearsFrames(children[i])) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Stop `display` and everything under it for good, as unloadAndStop
+     * does: timelines stopped, frame broadcasts no longer heard, no orphan.
+     */
+    stopAll(display) {
+        this.orphans.delete(display.serial);
+        stopTimelineSoundsUnder(this.s, display);
+        const stop = (o) => {
+            if (o instanceof MovieClip) {
+                o.playing = false;
+            }
+            if (o.object) {
+                for (const targets of this.s.broadcasts.values()) {
+                    targets.delete(o.object);
+                }
+            }
+            if (o instanceof Container) {
+                for (const child of o.children) {
+                    stop(child);
+                }
+            }
+        };
+        stop(display);
+    }
+    /** An event of `type` from `target`, if it has one and anything hears it there. */
+    dispatch(target, type, bubbles) {
+        if (target && heard(target, type)) {
+            dispatchEvent(this.s, target, this.s.event(type, bubbles));
+        }
+    }
+    eachObject(display, f) {
+        if (display.object) {
+            f(display.object);
+        }
+        if (display instanceof Container) {
+            for (const child of [...display.children]) {
+                this.eachObject(child, f);
+            }
+        }
+    }
+    /**
+     * The frame's scripts have run: the orphans whose time is up stop, and
+     * what scripts made and left off the display list is an orphan now.
+     */
+    afterScripts() {
+        // What the timeline took off this frame has had its frame; it stops here. So
+        // does one that has played ORPHAN_FRAMES off the list, but for one that
+        // listens for a frame's events, which hold it in Flash too.
+        for (const [serial, orphan] of this.orphans) {
+            if (!orphan.keep) {
+                this.orphans.delete(serial);
+                continue;
+            }
+            if (this.s.frames - orphan.since < ORPHAN_FRAMES) {
+                continue;
+            }
+            const display = orphan.ref.deref();
+            if (display && this.hearsFrames(display)) {
+                orphan.since = this.s.frames;
+                continue;
+            }
+            this.orphans.delete(serial);
+            if (display) {
+                stopTimelineSoundsUnder(this.s, display);
+            }
+        }
+        // What scripts made this frame and left off the display list plays on as an orphan.
+        const made = this.madeThisFrame.splice(0);
+        if (made.length > 0) {
+            scriptWork.changes++;
+        }
+        for (const display of made) {
+            if (!display.parent) {
+                this.orphan(display);
+            }
+        }
+    }
+}
+/**
+ * How many frames an orphan plays before it stops. Flash frees one nothing
+ * refers to almost at once, by reference counting; the browser's collector
+ * may take minutes, through which a game's removed characters would play
+ * on by the thousand, their scripts throwing for a stage they lack. The
+ * player cannot see what a script holds, so one held stops too, unlike
+ * Flash's, and plays on from there if put back; one that listens for a
+ * frame's events, which hold it in Flash as well, plays on.
+ */
+const ORPHAN_FRAMES = 120;