[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!

[Mamatha1718]

Hi @ksen0 @quinton-ashley , I would like to work on this issue, I've gone through the issue, and I think a good approach for the tutorial would be to explain async programming in simple terms, then show how to use Promise.all for parallel loading of assets. An example like this would help:

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

This method is great for beginners as it simplifies loading multiple assets and speeds up the process. Adding this would make the tutorial more beginner-friendly, and correct me if anything wrong in this.
If this ok will you please let me know which files need changes.

Thank You in Advance!

[ksen0]

Hi @Mamatha1718 thanks for volunteering! I've assigned you.

Before you get started, can you confirm if you'd like to write a tutorial or an example please?

You can check tutorials to see the level of detail, and compare that to examples. The tutorials tend to be quite long and step by step, with illustrations and lots of links. The examples are shorter and use one sketch to illustrate (for example this one). The tutorials are under the MIT license and have individual attribution ("by Author Name") and examples are more like reference and are under CC-BY-BC-SA 4.0 with collective authorship by p5.js all-contributors list (info here). In this case, a tutorial would be longer and would need to have a more in-depth explanation of async; I think what you're describing sounds more like an example, but please let me know what you think.

In either case, the place to add this documentation as a new .mdx file in p5.js-website repo, in the 2.0 branch.

• examples are here
• tutorials are here

And please let me know if you have any questions or issues!

[Mamatha1718]

Hi @ksen0 ,
Thanks for assigning! After checking both the tutorial and example sections, I agree that an example would be more suitable here. I’ll proceed with creating a simple example showing parallel loading with Promise.all. Please let me know if you have any specific suggestions before I start!
Thanks in Advance!

[ksen0]

@Mamatha1718 That sounds good, thank you for working on it!

[Mamatha1718]

Hi @ksen0 , @quinton-ashley , I raise a PR
825
Will you please let me know the changes required.
Thank You in Advance.