Async Background Loading Bug

This article addresses a common background loading bug mentioned in Tutorial Episode 2, where background images don't appear or flicker when scenes load.

The Problem

After adding custom background images to your visual novel, you may notice:

The background doesn't appear when a scene loads
The background flickers briefly then disappears

This is an async vs sync loading issue - your scene tries to display before the background image finishes loading.

The Solution

The new assets that are added to the static-asset-manifest.md (and/or sprite-manifest.md) need to be loaded in synchronously. For most games this can be done at game boot behind a loading screen. The Makko Engine's initEngine() method will handle loading in every asset from all manifests in your game and it will create a loading screen that tracks the progress of those assets being loaded into your game.

After Fix

In your main.js or where your assets are being initialized at game boot:

// Initialize MakkoEngine with progress tracking so it can load the assets synchronously
await MakkoEngine.initEngine({
  // Relative path to the manifest files that have the asset URLs
  manifests: ['/sprites-manifest.json', '/static-asset-manifest.json'],

  // Callback function to keep track of the assets that are being loaded in parallel
  onProgress: (loaded: number, total: number) => {
    const percentage = Math.round((loaded / total) * 100);
    loadingProgress.textContent = `${percentage}%`;
    progressBarFill.style.width = `${percentage}%`;
  },

  // Callback function to signal when the assets are done loading
  onComplete: () => {
    
    // Start main game loop
    const game = new Game();
    game.start();
  },
  onError: (error) => {
    console.error('Failed to load game assets:', error.message);
    loadingProgress.textContent = 'Error loading assets';
  }
});

Why This Happens

Sometimes when you start creating the game with placeholder assets and you add an actual background asset, the AI chat will attempt to load the new asset asynchronously and add fallback logic to display the placeholders if the new asset fails to load. Most of the time the new asset is attempted to be loaded in asynchronously when the asset is needed which does not allow enough time for the asset to load so the code uses the fallback asset which is incorrect.

How to Fix in MakkoAI

If your backgrounds are going back to their original fallback state you can use the following prompt:

Open AI Chat in your project
Describe the symptom with this prompt:

"Remove the background fallback system and create a way to wait for the Makko Engine to initialize"

Makko will analyze your scene loading code and identify the async issue. Then it will ensure the initEngine() method is being called at game load and create a loading screen that synchronously waits for all assets to load.

Verifying the Fix

After implementing the fix:

Rebuild your game
Navigate to a scene with a background
The background should appear immediately and consistently