Source: scene/Scenes.js

//------------------------------------------------------------------------------
// Constructor scope
//------------------------------------------------------------------------------

/** 
 * Creates a new instance of the class.
 * 
 * @constructor
 * 
 * @class
 * @classdesc
 * 
 * Represents a scene manager. Multiple scenes can exist simultaneously, but 
 * only one scene can be selected at a time. Rendering is limited to the 
 * selected scene. All scenes in the current batch are initialized and kept in 
 * memory until a new batch is loaded.
 */
rune.scene.Scenes = function() {

    //--------------------------------------------------------------------------
    // PUBLIC PROPERTIES
    //--------------------------------------------------------------------------

    /**
     * Pauses updates for all scenes, including persistent scenes. Rendering and
     * lifecycle callbacks continue. Input and screen objects remain active, so
     * pause controls must run outside the paused scene updates.
     *
     * @type {boolean}
     * @default false
     */
    this.paused = false;
    
    //--------------------------------------------------------------------------
    // Private properties
    //--------------------------------------------------------------------------

    /**
     * Current batch.
     *
     * @type {Array.<rune.scene.Scene>}
     * @private
     */
    this.m_cb = [];
    
    /**
     * Requested batch.
     *
     * @type {Array.<rune.scene.Scene>}
     * @private
     */
    this.m_rb = null;
    
    /**
     * Prevents recursive cleanup when a scene's dispose callback calls dispose().
     *
     * @type {boolean}
     * @private
     */
    this.m_disposing = false;

    /**
     * Selected scene index.
     *
     * @type {number}
     * @private
     */
    this.m_cs = 0;
    
    /**
     * Requested scene index.
     *
     * @type {number}
     * @private
     */
    this.m_rs = 0;
};

//------------------------------------------------------------------------------
// Public prototype getter and setter methods
//------------------------------------------------------------------------------

/**
 * The number of scenes that exist within the current batch, i.e. how many 
 * Scene objects currently exist in memory. Note that a batch can contain 
 * multiple scenes, but only one scene can be selected at a time.
 *
 * @member {number} batchSize
 * @memberof rune.scene.Scenes
 * @instance
 * @readonly
 */
Object.defineProperty(rune.scene.Scenes.prototype, "batchSize", {
    /**
     * @this rune.scene.Scenes
     * @ignore
     */
    get : function() {
        return this.m_cb.length;
    },
});

/**
 * The currently selected scene.
 *
 * @member {rune.scene.Scene} selected
 * @memberof rune.scene.Scenes
 * @instance
 * @readonly
 */
Object.defineProperty(rune.scene.Scenes.prototype, "selected", {
    /**
     * @this rune.scene.Scenes
     * @ignore
     */
    get : function() {
        return this.m_cb[this.m_cs];
    },
});

/**
 * Whether a requested batch or selection still awaits lifecycle processing.
 *
 * @member {boolean} pending
 * @memberof rune.scene.Scenes
 * @instance
 * @readonly
 */
Object.defineProperty(rune.scene.Scenes.prototype, "pending", {
    /**
     * @this rune.scene.Scenes
     * @ignore
     */
    get : function() {
        return this.m_rb != null || this.m_cs !== this.m_rs;
    }
});

//------------------------------------------------------------------------------
// Public prototype methods (API)
//------------------------------------------------------------------------------

/**
 * Searches for a specific scene in the current batch of scene objects. The 
 * search is based on scene name.
 *
 * @param {string} name The name of the searched scene.
 *
 * @returns {rune.scene.Scene}
 */
rune.scene.Scenes.prototype.find = function(name) {
    for (var i = 0; i < this.m_cb.length; i++) {
        if (this.m_cb[i]['name'] === name) {
            return this.m_cb[i];
        }
    }
    
    return null;
};

/**
 * Requests selection by name in the pending batch, or the current batch if
 * no load is pending. Uses the same batch as select(); activation is deferred
 * until update(). A missing name returns false without changing the request.
 * Unlike find(), this searches the pending batch when one exists.
 *
 * @param {string} name The name of the searched scene.
 *
 * @returns {boolean}
 */
rune.scene.Scenes.prototype.findAndSelect = function(name) {
    var batch = this.m_rb || this.m_cb;
    for (var i = 0; i < batch.length; i++) {
        if (batch[i]['name'] === name) {
            this.select(i);
            return true;
        }
    }
    
    return false;
};

/**
 * Activates a batch of scenes. This process removes any previous scenes and 
 * frees up allocated memory, hence the process can not be undone. All scenes 
 * in the batch are initialized on the next update tick. A load requested
 * during init() or old-batch dispose() remains pending until the following
 * update. If several loads are requested before then, the latest request
 * replaces the pending batch.
 * Replacing a pending batch disposes its abandoned scenes immediately; scenes
 * still in the current or new pending batch are retained.
 * The array is copied; later array edits do not affect the manager. Scene
 * objects are retained by reference and disposed when removed by the manager.
 * Every scene must provide callable init, update, render, dispose, onSelect
 * and onDeselect methods. A scene object may occur only once per batch;
 * distinct objects may share a name. Objects in the current batch cannot be
 * loaded again: use select() to switch scenes, or create a new instance to
 * restart one. Invalid input leaves current and pending batches unchanged.
 *
 * @param {Array.<rune.scene.Scene>} batch Scene list to copy into the manager.
 *
 * @throws {Error} If the batch is empty, is not an array or contains invalid, duplicate or current scenes.
 *
 * @returns {undefined}
 */
rune.scene.Scenes.prototype.load = function(batch) {
    if (!Array.isArray(batch) || batch.length === 0) {
        throw new Error("Invalid scene batch");
    }
    var scenes = batch.slice();
    for (var i = 0; i < scenes.length; i++) {
        var scene = scenes[i];
        if (scene == null || typeof scene !== "object" ||
            typeof scene.init !== "function" || typeof scene.update !== "function" ||
            typeof scene.render !== "function" || typeof scene.dispose !== "function" ||
            typeof scene.onSelect !== "function" || typeof scene.onDeselect !== "function") {
            throw new Error("Invalid scene at index " + i);
        }
        if (scenes.indexOf(scene) !== i) {
            throw new Error("Duplicate scene at index " + i);
        }
        if (this.m_cb.indexOf(scenes[i]) >= 0) {
            throw new Error("Scene at index " + i + " already belongs to the current batch");
        }
    }
    var previous = this.m_rb;
    this.m_rb = scenes;
    this.m_rs = 0;
    this.m_disposeAbandonedScenes(previous);
};

/**
 * Select a scene from the current batch. Note that only the selected scene is 
 * rendered. Inactive scenes remain unchanged during their time as inactive.
 *
 * @param {number} index Zero-based integer index in the pending or current batch.
 *
 * @throws {RangeError} If index is not an integer number within the batch bounds.
 *
 * @returns {undefined}
 */
rune.scene.Scenes.prototype.select = function(index) {
    var batch = (this.m_rb) ? this.m_rb : this.m_cb;
    if (typeof index === "number" && index === Math.floor(index) &&
        index >= 0 && index < batch.length) {
        if (this.m_rs != index) {
            this.m_rs  = index;
        }
    } else throw new RangeError("Invalid scene index");
};

//------------------------------------------------------------------------------
// Public prototype methods (ENGINE)
//------------------------------------------------------------------------------

/**
 * Processes requested lifecycle changes and optionally updates scene logic.
 * Pausing skips scene updates entirely; it does not pass a zero time step.
 *
 * @param {number} step Current time step.
 * @param {boolean} [active=true] Whether scene updates should run after lifecycle processing.
 *
 * @returns {undefined}
 * @ignore
 */
rune.scene.Scenes.prototype.update = function(step, active) {
    this.m_updateBatch(step);
    this.m_updateSelection(step);
    if (active !== false && this.paused !== true) {
        this.m_updateScenes(step);
    }
};

/**
 * Renders the selected scene.
 *
 * @returns {undefined}
 * @ignore
 */
rune.scene.Scenes.prototype.render = function() {
    this.m_renderScenes();
};

/**
 * Cancels pending loads and disposes current and pending scenes once each.
 * Requests made by disposal callbacks are also canceled and cleaned up.
 * Cleanup continues after callback failures, then rethrows the first error.
 * A later explicit load() may reuse this manager.
 *
 * @returns {undefined}
 * @ignore
 */
rune.scene.Scenes.prototype.dispose = function() {
    if (this.m_disposing) return;

    this.m_disposing = true;
    var disposed = [];
    var failure = null;
    try {
        do {
            var batch = this.m_cb.concat(this.m_rb || []);
            this.m_rb = null;
            this.m_cb = [];
            this.m_cs = this.m_rs = 0;
            var scenes = [];
            for (var i = 0; i < batch.length; i++) {
                var scene = batch[i];
                if (scene != null && disposed.indexOf(scene) < 0) {
                    disposed.push(scene);
                    scenes.push(scene);
                }
            }
            try {
                this.m_disposeBatch(scenes);
            } catch (error) {
                if (failure == null) failure = {error: error};
            }
        } while (this.m_hasPendingBatch());
    } finally {
        this.m_disposing = false;
    }
    
    if (failure != null) throw failure.error;
};

//------------------------------------------------------------------------------
// Private prototype methods
//------------------------------------------------------------------------------

/**
 * Cancels a failed transition and attempts cleanup of all owned scenes.
 * Cleanup failures must not hide the original lifecycle error.
 *
 * @param {*} error Original initialization or selection error.
 *
 * @throws {*} The original error after cleanup attempts finish.
 * @returns {undefined}
 * @private
 */
rune.scene.Scenes.prototype.m_abortTransition = function(error) {
    try {
        this.dispose();
    } catch (cleanupError) {
        // Preserve the transition error; dispose() has attempted every scene.
    }
    throw error;
};

/**
 * Checks pending state after lifecycle callbacks, which may request a new load.
 *
 * @returns {boolean}
 * @private
 */
rune.scene.Scenes.prototype.m_hasPendingBatch = function() {
    return this.m_rb != null;
};

/**
 * Replaces the current batch with a new one. A lifecycle failure aborts the
 * transition, clears owned scenes and propagates the original error.
 *
 * @throws {Error} Unless there is a new batch of scenes.
 *
 * @returns {undefined}
 * @private
 */
rune.scene.Scenes.prototype.m_iniScenes = function() {
    if (this.m_rb == null || this.m_rb.length === 0) {
        throw new Error("No pending scene batch");
    }
    var previous = this.m_cb;
    var batch = this.m_rb;
    var selection = this.m_rs;

    this.m_cb = batch;
    this.m_rb = null;
    this.m_cs = (selection > -1 && selection < batch.length) ? selection : 0;
    this.m_rs = this.m_cs;

    try {
        this.m_disposeBatch(previous);
        if (this.m_cb !== batch) return;

        for (var i = 0; i < batch.length; i++) {
            batch[i].init();
            if (this.m_cb !== batch) return;
        }
        
        this.m_selectInitialScene();
    } catch (error) {
        this.m_abortTransition(error);
    }
};

/**
 * Activates the initial scene after all init callbacks have run. If a callback
 * requested another batch, its requested index must not select a current scene.
 *
 * @returns {undefined}
 * @private
 */
rune.scene.Scenes.prototype.m_selectInitialScene = function() {
    if (!this.m_hasPendingBatch()) {
        this.m_cs = this.m_rs;
    }
    this.m_cb[this.m_cs].onSelect(null);
};

/**
 * If there is a requested batch, it should replace the existing one.
 *
 * @param {number} step Current time step.
 *
 * @returns {undefined}
 * @private
 */
rune.scene.Scenes.prototype.m_updateBatch = function(step) {
    if (this.m_hasPendingBatch()) {
        this.m_iniScenes();
    }
};

/**
 * Updates selection within the current batch. If another batch is pending,
 * the requested index belongs to that batch and must not select an old scene.
 * Stops the transition if onDeselect() disposes or replaces the current batch.
 *
 * @param {number} step Current time step.
 *
 * @returns {undefined}
 * @private
 */
rune.scene.Scenes.prototype.m_updateSelection = function(step) {
    if (!this.m_hasPendingBatch() && this.m_cb != null &&
        this.m_rs > -1 && this.m_rs < this.m_cb.length && this.m_cs != this.m_rs) {
        
        var batch = this.m_cb;
        var o = batch[this.m_cs];
        var n = batch[this.m_rs];
        
        this.m_cs = this.m_rs;
        
        try {
            o['onDeselect'](n);
            if (this.m_cb !== batch) return;
            n['onSelect'](o);
        } catch (error) {
            this.m_abortTransition(error);
        }
    }
};

/**
 * Updates active scenes while the same batch remains current.
 * Stops if a scene callback pauses the manager, disposes or replaces the batch.
 *
 * @param {number} step Current time step.
 *
 * @returns {undefined}
 * @private
 */
rune.scene.Scenes.prototype.m_updateScenes = function(step) {
    var batch = this.m_cb;
    if (batch == null) return;

    for (var i = 0; this.m_cb === batch && this.paused !== true && i < batch.length; i++) {
        var scene = batch[i];
        if (i == this.m_cs || scene.persistent == true) {
            scene.update(step);
        }
    }
};

/**
 * Renders the selected scene.
 *
 * @returns {undefined}
 * @private
 */
rune.scene.Scenes.prototype.m_renderScenes = function() {
    if (this.m_cb != null && this.m_cb.length > this.m_cs) {
        this.m_cb[this.m_cs].render();
    }
};

/**
 * Disposes scenes abandoned by a replacement request. Check live ownership
 * before each callback because dispose() may request another batch. Attempts
 * every abandoned scene before rethrowing the first cleanup error.
 *
 * @param {?Array.<rune.scene.Scene>} batch Previous pending batch.
 *
 * @returns {undefined}
 * @private
 */
rune.scene.Scenes.prototype.m_disposeAbandonedScenes = function(batch) {
    if (batch == null) return;

    var disposed = [];
    var failure = null;
    for (var i = batch.length - 1; i >= 0; i--) {
        var scene = batch[i];
        if (this.m_cb.indexOf(scene) < 0 &&
            (this.m_rb == null || this.m_rb.indexOf(scene) < 0) && disposed.indexOf(scene) < 0) {
            disposed.push(scene);
            try {
                scene.dispose();
            } catch (error) {
                if (failure == null) failure = {error: error};
            }
        }
    }
    if (failure != null) throw failure.error;
};

/**
 * Attempts cleanup of a detached batch without changing current or pending
 * ownership. Callback load requests belong to the next update. Throws the
 * first error only after all remaining scenes have been attempted.
 *
 * @param {Array.<rune.scene.Scene>} batch Scenes to dispose.
 *
 * @returns {undefined}
 * @private
 */
rune.scene.Scenes.prototype.m_disposeBatch = function(batch) {
    var failure = null;
    try {
        if (rune.system.Application['instance'] != null && rune.system.Application['instance']['sounds'] != null) {
            rune.system.Application['instance']['sounds'].clear();
        }
    } catch (error) {
        failure = {error: error};
    }

    if (batch != null) {
        for (var i = batch.length - 1; i >= 0; i--) {
            if (batch[i] != null) {
                try {
                    batch[i].dispose();
                } catch (error) {
                    if (failure == null) failure = {error: error};
                }
            }
        }
    }
    if (failure != null) throw failure.error;
};