[p5.js 2.0] Add documentation / tutorial on how to do parallel loading with Promise.all

[quinton-ashley]

Increasing access

Make it easier for beginners to load multiple assets at once without using Promise.all

Most appropriate sub-area of p5.js?

• Accessibility
• Color
• Core/Environment/Rendering
• Data
• DOM
• Events
• Image
• IO
• Math
• Typography
• Utilities
• WebGL
• Build process
• Unit testing
• Internationalization
• Friendly errors
• Other (specify if possible)

Feature enhancement details

As suggested by @mattdesl , @mvicky2592 , and @nickmcintyre

#6767 (comment)

It'd be great for p5 v2 to have an async load function for loading files of any supported type in parallel.

I've already implemented this in q5.js:

https://q5js.org/learn/#load

If desired, feel free to use q5's source as a reference for implementing it in p5 v2.

https://github.com/q5js/q5.js/blob/bf0eb797111238fbd2e1482370737772de56dbbc/src/q5-util.js#L36

[ksen0]

Thanks @quinton-ashley ! I'm opening it for consideration here.

Status: Discussion is open and input is welcome!

For all those reading and new to this topic: Please read the below and chime in. Please do not make PRs before there is a decision to implement this and before an assignment (read more in the contribution guidelines)

Potential feature for next minor release of p5.js 2.0

Right now, we are close to releasing p5.js 2.0 (see timeline), and no new features can be considered for that initial release.

After this, new features will be considered for p5.js 2.1 (or later minor releases, like 2.2 and 2.3).

Except bugfixes (or similar exceptions), new features will not be considered for p5.js 1.x (even though it will continue to be supported and available until summer 2026).

What potential benefits and drawbacks do you see?

The prioritization of a feature is not based on popularity directly, but if you want to see this implemented, please do comment! Besides popularity: it matters what the benefits/drawbacks of adding the feature, and the benefits/drawbacks of not adding it.

In this particular case, I am not sure I understand why loading multiple files is a big barrier to entry (beginner-friendliness as the main goal here). The drawback of implementation is that adding anything increases the chance of future bugs.

However, if we decide to include this in a later minor release, this could be a Good First Issue for a new contributor, especially as an introduction to writing tests.

The previous discussion linked above could also be valuable to look through: #6767

[quinton-ashley]

Why is loading multiple files is a big barrier to entry?

Loading multiple files in async setup doesn't present a big barrier to entry.

let jump, retro;

async function setup() {
  jump = await loadSound('/assets/jump.wav');
  retro = await loadSound('/assets/retro.flac');
}

In this example the program would wait until the jump sfx is completely loaded before starting to load the retro music.

Users loading files in sequence won't experience longer loading times if they're loading files locally, from their computer. Viewers of a sketch also wouldn't experience longer load times if the sketch doesn't require many files and the files are small.

However, loading in sequence is something that generally shouldn't be done because parallel loading provides a better experience for viewers when they run sketches that load a lot of files, especially for viewers with slow internet speeds, which can effect accessibility.

To summarize the previous discussion, load was suggested to make it easier for beginners to load files in parallel.

Parallel loading in async setup would currently require the use of Promise.all:

let jump, retro;

async function setup() {
  let soundFiles = [
    loadSound('/assets/jump.wav'),
    loadSound('/assets/retro.flac')
  ];

  [jump, retro] = await Promise.all(soundFiles);
}

Parallel loading in async setup with the proposed load function:

let jump, retro;

async function setup() {
  [jump, retro] = await load(
     '/assets/jump.wav',
     '/assets/retro.flac'
  );
}

Or with an array:

let jump, retro;

async function setup() {
  let soundFiles = [
    '/assets/jump.wav',
    '/assets/retro.flac'
  ];

  [jump, retro] = await load(soundFiles);
}

I was actually under the impression that there'd be more of a difference 😅 but now that I've laid it all out in summary I think you're right, as long as there's a tutorial on how to do parallel loading with Promise.all that'd be fine. It's still a cool idea that load could accept any file type though.

I also still personally prefer the approach of having it all be behind the scenes with the Promise.all based preload system you made in the preload.js compat file. Using preload is easier for parallel loading because users would not need to use arrays or array destructuring and they define the variable on the same line that they use a load* function with the file name, which makes it clear which file is being assigned to which variable, even when the variable name is different from the file name.

[ksen0]

Experimenting with the "Task" issue here to reflect that the most immediate conclusion here is to create a new piece of documentation:

as long as there's a tutorial on how to do parallel loading with Promise.all that'd be fine. It's still a cool idea that load could accept any file type though.

If anyone wants to work on such a tutorial, please comment!