Add `randomX` and `randomY` functions

[quinton-ashley]

[ksen0]

Thanks for the idea @quinton-ashley ! I've edited the description slightly to make it more precise, hope that's alright: that the aspect of access being addressed in beginner-friendliness. Other aspects of access include web accessibility and internationalization. I'm not sure if beginner-friendliness for new contributors and for new users should be separately stated, but I think this idea affects both!

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.

For example, for this one, my thoughts are as follows:

🌸 It sounds like the biggest benefit is that it would make picking a random spot in the sketch the same in WEBGL and in Canvas mode, which is a big plus for beginner-friendliness.

🌸 If we agree to include it, it would also be a Good First Issue for new contributors. especially if it includes adding tests and so on.

🐛 As far as I can tell, the only drawback is that in general adding new features creates more chances for bugs in the future, and more maintenance load. This particular feature is super small, and in canvas mode randomX() would be equivalent to random(width)

🌸 The drawback of not adding this feature would be that switching between WEBGL and canvas mode changes random canvas point behavior. Here's a sketch

Do add yours below!

[VANSH3104]

@ksen0 @quinton-ashley
We also need randomZ() in WEBGL mode to make it compatible with 3D rendering. Additionally, we could allow specifying a range like randomX(min, max), since randomX() currently returns a value across the entire canvas width. This change would provide more control and flexibility to users. Is it right

[ksen0]

@VANSH3104 Good point about randomZ()! What do you envision the usage of randomX(min, max) to be? What would the min and max values be, in this case?

[VANSH3104]

@ksen0 For randomX(min, max), the idea is to allow users to specify a custom range within the canvas instead of always using the full width. it become easy if we want to positioning elements within a specific section of the sketch.

[ksen0]

@VANSH3104 with min and max, what are the values, what's the range? If values are in pixels, then the Canvas/WEBGL modes will have different interpretations, because (0,0) means different things there. If values are in proportion (from 0 to 1) then that might itself be a confusion. How do you see the sections of the sketch being reflected in the numbers? Examples would be really helpful here!

[VANSH3104]

@quinton-ashley @ksen0 Thanks for the clarification! I see your point about how Canvas and WEBGL interpret coordinates differently.
@quinton-ashley, yes, I was taking something like randomX(leftMargin, rightMargin). This would allow users to specify a range within the canvas, making it easier to position elements dynamically without needing to manually adjust for different coordinate systems in Canvas and WEBGL modes.

[GregStanton]

It's great to see new ideas, and all this discussion! Since this proposal would extend the API, I think this is a good test case for the six API criteria I proposed previously:

1. Consistency: Provide a similar interface for similar features and different interfaces for different features.
2. Readability: Design features that are easy to read and understand.
3. Writability: Make features easy to use and hard to misuse.
4. Predictability: Respect the principle of least surprise, so that users can guess how features work.
5. Extensibility: Hide implementation details and lay a foundation for add-on libraries.
6. Economy: Limit redundant features, and consider add-on libraries for new features.

The main benefit of the proposed features, to me, is writability (here I'm quoting the proposal):

In WEBGL mode it'd reduce the amount of code... from this random(-width / 2, width / 2) to just randomX().

However, my concern is that this benefit is outweighed by a number of significant costs, which are clearer when we look at the other criteria; @quinton-ashley I'm sorry that this is our first major interaction... I bet you have a ton of other ideas that I'd love! I'm just hesitant about this particular idea. I'll explain why below.

Consistency

Single-argument version

In random(50), the argument is an upper bound, whereas in randomX(50), the argument is a margin that's two sided and represents neither a lower nor an upper bound.

Two-argument version

The issue with random(lowerBound, upperBound) vs. randomX(leftMargin, rightMargin) is similar. I think there'd be a strong tendency to interpret randomX(10, 20) as a random number between 10 and 20. That interpretation is actually the first idea that @VANSH3104 proposed, and users may interpret it the same way, especially since that's how random() works.

Readability, Predictability

Although more concise function calls may seem more readable to those who already understand the functions involved, I think there's an overall loss of readability, since the margin concept is a bit confusing:

1. A negative margin as described on the q5 site seems to correspond to positive padding in CSS. This issue could possibly be addressed by having positive values narrow the range, but the next point suggests it's simply easy to get confused between the two options.
2. According to the main proposal here and the q5 site, a negative margin will "contract" the range. But in the comment above, @quinton-ashley wrote that "Making leftMargin -50 would expand the range." I'm guessing that was an accident, but accidents like this tend to indicate complexity of some kind; if the feature's designer makes this mistake, I think we can expect a significant percentage of users to make incorrect predictions about how this feature works.
3. As proposed, randomX(-50) would generate a number from an interval centered at zero in WebGL mode, but in P2D mode, it'd generate a number from an interval that doesn't contain zero at all. We might be able to overcome that source of confusion, if not for the next issue, relating to extensibility.

Extensibility

There is no canvas boundary in the Z direction, so the concept of margin doesn't seem to apply here. Specifying one of three coordinates in an entirely different way would introduce additional complexity.

Economy

There are always costs whenever we add to the API, so we need to consider whether the benefits outweigh those costs. In addition to technical costs like bug fixing and maintenance, there's a conceptual cost to users.

Imagine a software library with only 10 functions. You might think, I can learn this library in a day! Now imagine a library with 10,000 functions. You might quickly be overwhelmed, assuming it will take years to learn the basics. The cost I'm describing is extra conceptual weight.

To be clear, a tiny feature count isn't necessarily good. That might mean that a lot of functionality is packed into a small number of features, making those features hard to learn. What we want is a good power-to-weight ratio, meaning roughly that we want to empower users to do a lot without requiring them to learn a lot.

Actually, p5's random() is a really helpful example. In principle, it's possible to achieve the same effects with the native Math.random(), so you might say p5's random() doesn't add power... But I'd argue that it significantly empowers users, since beginners may not be able to figure out how to generate a random whole number using Math.random(), or how to pick a random element of an array.

On the other hand, I think that if users can understand a coordinate system, they'd be able to figure out how to get the same effect as randomX() and randomY() using only random(). In that sense, we don't seem to gain any power, but we'd be adding three new functions randomX(), randomY(), and randomZ() and a significant amount of conceptual weight.

[VANSH3104]

@GregStanton I want to clarify that the two-argument version randomX(leftMargin, rightMargin) was my idea. I thought it would help generate random numbers within dynamic margins rather than fixed bounds, making positioning easier in some cases.I agree that it is confusing
I support @quinton-ashley randomX() proposal because:

Simplicity – randomX() is easy to use and adapts to WebGL and canvas modes.
Consistency – It aligns with p5.js functions that simplify common tasks.
Practicality – randomX(margin) allows quick placement without extra calculations.
Minimal Complexity – It’s a small addition with big usability benefits.

I understand @GregStanton concerns about consistency and predictability, and he makes a great point about avoiding confusion. However, I believe that randomX() remains intuitive and useful if kept simple, without the two-argument version.

[ksen0]

I'll try to summarize the current proposed idea, thanks to @VANSH3104 and @quinton-ashley for clarifications, please correct me if I missed something.

• Add 3 functions: randomX(), randomY() for generating a random location. (Not randomZ(), because of the complications @davepagurek mentions below.)
• Each has one optional parameter that is a margin in pixels, and perhaps should be constrained to positive values; but not 2 parameters because it's too confusing with random() usage. It's possible even this could cause a lot of confusion because it still has a totally different behavior than random() with one parameter.

Respectfully, I wouldn't have added these functions to q5.js if they didn't meet the criteria for good API.

@quinton-ashley I think it's really important to be mindful that "criteria for good API" is context specific. @GregStanton's criteria make a lot of sense for p5.js more generally, even if for q5.js a different prioritization makes sense. I really agree with Greg's suggestion to carefully consider adding any functions, even small ones, because it makes the whole library more challenging to maintain with a wide and varied contributor base. This is not to say that the function is not useful - I can see myself using this all the time! - but in the case of p5.js, I think the requirements of economy (in terms of API design) is relatively higher priority than it might be in another situation.

Specifically: "It’s a small addition with big usability benefits" - also with additional implementation/maintenance costs of adding unit tests, and updating FES, tutorials, reference potentially with extra explanations to disambiguate with usage of random depending on whether the optional parameter is confusing. I don't think those are massive costs, but they are also not zero.

I think that if users can understand a coordinate system, they'd be able to figure out how to get the same effect as randomX() and randomY() using only random()

@GregStanton I feel like potentially there is a benefit to being able to more easily switch WEBGL vs Canvas, but maybe that means we should rather think about how other parts of the API could make that switch more straightforward? Or whether this is a common challenge?

Summary

This seems like a useful feature, and it would be relatively straightforward to add (code + tests + FES updates + associated documentation). However, I do think that the potential for confusion about parameters (even with a single margin parameter) is not dismissable. I think it would be useful to get some more voices in this thread on whether the single-parameter use is useful enough to justify risk of confusion.

For those reading: to make this a bit more concrete, here is a sketch that does random placement using random and allows smooth switching between the different renderers for WEGBL and Canvas mode.

[davepagurek]

@ksen0 @quinton-ashley
We also need randomZ() in WEBGL mode to make it compatible with 3D rendering. Additionally, we could allow specifying a range like randomX(min, max), since randomX() currently returns a value across the entire canvas width. This change would provide more control and flexibility to users. Is it right

Good point about z! randomZ is possibly a little different, since there's a clear minimum (has to be in front of the camera!) but the maximum can be quite far away. Is a uniform distribution correct for that? I'm not sure what the answer is there, might take some thought.

One other observation is that if you start adjusting depth, the x/y range that is visible changes (less range closer to the camera, more farther.)

My thought is that if there's not a clear answer, it's ok to just do x and y at first, since the "correct" range for z might vary per sketch, so we can ask users to do their own range manually at first with the usual random().

[quinton-ashley]

@davepagurek I hadn't considered that these functions could take rotation into account.

In case it isn't clear why they shouldn't, for example in WebGL mode users could rotate the y axis such that the canvas contains an x axis that stretches out to infinity, like the z axis does at the default camera position.

My description of the margin parameter "expanding or contracting the range from the canvas edges" is incorrect though if scaling or rotation is applied. Hmm I'll need to think of how to better phrase that.

[davepagurek]

@quinton-ashley good point! in a lot of my own sketches where one might apply rotation, I end up using a depth values based on width/height (maybe a max or min.) In that scenario, we already have x/y versions of this function, so someone could maybe just use those.

[GregStanton]

@ksen0:

I feel like potentially there is a benefit to being able to more easily switch WEBGL vs Canvas, but maybe that means we should rather think about how other parts of the API could make that switch more straightforward? Or whether this is a common challenge?

This is a great point to consider. I think the sketch you shared clearly shows that, when using the proposed features to generate random coordinates within the bounds of the canvas, it's easier to switch between Canvas and WebGL. I'm not sure how common it is to switch a sketch between renderers like that. Do you have any thoughts on this @davepagurek?

If we want to facilitate that kind of switch, I think that considering other parts of the API is a terrific idea, since it opens up many possibilities. As an initial example, the p5.Renderer class might have leftEdgeX and rightEdgeX properties that'd be inherited by the different renderers. Those could be accessed on the renderer instance that's returned by createCanvas(). That might not be a good idea; my intention is just to illustrate the size of the solution space.

Although I'm not sure whether switching a sketch between P2D and WebGL renderers is common, I do think that conceptual compatibility between Canvas (i.e. the P2D renderer) and WebGL features is a common challenge. It seems unavoidable, given the important aim of making both 2D and 3D graphics accessible. This comment has some examples of such issues in the context of 2D primitives. There are also tensions between the shape and geometry interfaces, as well as p5.Graphics and p5.Framebuffer (these pairs of similar features have different interfaces that serve subtly different purposes; the challenge is to clearly communicate or possibly reduce these differences).

So far, @davepagurek and I have discussed conceptual compatibility on a case-by-case basis, and I took a similar approach in the API audit proposal. For now, I set a reminder to myself to consider incorporating a sub-issue or top-level agenda item aimed at identifying and resolving Canvas vs. WebGL tensions more generally (to the extent possible).