Function run

src/engine/lifecycle.ts:342–488

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

 * if it couldn't be run correctly.
 */
export async function run (engine: VisualNovelEngine, statement: unknown, shouldAdvance = true): Promise<{ advance: boolean }> {
	// Capture current position at the start to detect if another advance happened
	// during async operations (e.g., user click during Notification's willApply)
	const initialStep = engine.state ('step') as number;
	const initialLabel = engine.state ('label') as string;

	const actions = engine.actions ();
	const before: Promise<void>[] = actions.map (action => action.beforeRun ({ advance: shouldAdvance }));

	await Promise.all (before);

	// Don't allow null as a valid statement
	if (statement === null) {
		engine.debug.trace ();
		engine.debug.groupEnd ();
		throw new Error ('Statement was null.');
	}

	engine.debug.debug ('Preparing Action', statement);

	if (typeof statement === 'function') {
		engine.debug.groupCollapsed (`Run Cycle [JS Function]`);

		// Block the game while the function is being run
		engine.global ('block', true);

		// Run the function asynchronously and after it has run, unblock
		// the game so it can continue.
		try {
			const returnValue = await  Util.callAsync (statement as (...args: unknown[]) => unknown, engine);

			engine.global ('block', false);

			engine.debug.groupEnd ();

			if (shouldAdvance && returnValue !== false) {
				// Only advance if we're still on the same step - another action might have
				// already advanced the game (e.g., user clicked during async function)
				const currentStep = engine.state ('step') as number;
				const currentLabel = engine.state ('label') as string;
				if (currentStep === initialStep && currentLabel === initialLabel) {
					// TODO: Do we need to return here? We don't do it in the other run methods.
					return engine.next ().then (() => ({ advance: true }));
				} else {
					engine.debug.debug ('Skipping auto-advance: game already advanced by another action');
				}
			}

			return Promise.resolve ({ advance: false });
		} catch (e: unknown) {
			const error: FancyErrorProps = {
				'Label': String(engine.state ('label')),
				'Step': Number(engine.state ('step')),
				'Help': {
					'_': 'Check the code for your function, there may be additional information in the console.',
				}
			};