Function revert

src/engine/lifecycle.ts:191–328

(engine: VisualNovelEngine, statement: unknown = null, shouldAdvance = true, shouldStepBack = true)

 * @returns {Promise} - Whether the game was able to go back or not
 */
export async function revert (engine: VisualNovelEngine, statement: unknown = null, shouldAdvance = true, shouldStepBack = true): Promise<{ advance: boolean; step: boolean } | void> {
	const actions = engine.actions ();
	const before: Promise<void>[] = actions.map (action => action.beforeRevert ({ advance: shouldAdvance, step: shouldStepBack }));

	await Promise.all (before);

	// Check if we have steps behind us to revert to. If there aren't, then
	// we can't revert since we are already at the first statement.
	let actionToRevert: unknown = null;
	const currentStep = engine.state ('step') as number;
	const currentLabel = engine.state ('label') as string;
	const label = engine.label () as unknown[];

	if (statement !== null) {
		actionToRevert = statement;
	} else if (currentStep >= 1) {
		actionToRevert = label[currentStep - 1];
	} else {
		const jumpHistory = engine.history ('jump') as Array<{ destination: { label: string; step: number }; source: { label: string; step: number } }>;
		const jump = [...jumpHistory].reverse ().find (o => {
			return o.destination.label === currentLabel && o.destination.step === 0;
		});

		if (typeof jump !== 'undefined') {
			engine.state ({
				label: jump.source.label,
				step: jump.source.step
			});
			const newLabel = engine.label () as unknown[];
			const newStep = engine.state ('step') as number;
			actionToRevert = newLabel[newStep];
			engine.debug.debug ('Will revert to previous label.');
		} else {
			engine.debug.debug ('Will not revert since this is the beginning of the game.');
		}
	}

	// Don't allow null as a valid statement
	if (actionToRevert === null || typeof actionToRevert === 'undefined') {
		// Clear the Stack using a Time Out instead of calling
		// the function directly, preventing an Overflow
		const labelArray = engine.label () as unknown[];
		const step = engine.state ('step') as number;

		setTimeout (() => {
			engine.run (labelArray[step]);
		}, 0);

		engine.debug.groupEnd ();

		return Promise.resolve ();
	}

	// If the statement is a pure js function, it won't be reverted since we don't
	// know what to do to revert it.
	if (typeof actionToRevert === 'function') {
		return Promise.reject ();
	}