Add `randomX` and `randomY` functions

[quinton-ashley]

Increasing access

This feature could increase beginner-friendliness by making it a bit easier to generate such values as well increase interoperability between P2D and WEBGL mode.

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 request details

I'd like to make a suggestion to add two new functions to p5: randomX and randomY, which would get random values relative to the dimensions of the canvas and the coordinate system origin (which differs between P2D and WEBGL mode).

A margin could be passed as an optional parameter, the distance to extend (positive) or contract (negative) the range from the edges of the canvas.

In WEBGL mode it'd reduce the amount of code needed to do so from this random(-width / 2, width / 2) to just randomX() which in a large file where this is done many times would make user's code smaller and easier to read imo since the function is intuitively named.

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

[quinton-ashley]

instead of always using the full width

@VANSH3104 Did you see in the feature request details section that the functions could accept a margin?

See example use of randomY(-60) here:

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

Are you suggesting randomX(leftMargin, rightMargin)?

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

[quinton-ashley]

So an alternate use when two number parameters are provided?

randomX(-50, 80)

Making leftMargin -50 would expand the range from the left edge to the left by 50 and making rightMargin 80 would expand from the right edge to the right.

EDIT: The problem is that users might confuse it with min and max bounds given the similarity to random.

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

[quinton-ashley]

@GregStanton I agree with your assessment of the two argument use, which I didn't propose and I don't think it should be included. I was struggling to articulate that point more clearly and thankfully you've laid it out nicely.

I didn't make a mistake in my explanation though, because range extension from the left margin would require subtraction from the left margin position. Whether -50 or positive 50 would cause expansion from the left margin would be a point of confusion with how it works in CSS. I've since edited the comment to make it clearer that I was merely trying to flesh out that idea, you seem to be under the assumption that I wanted to add that onto the proposal which I don't. You're making a strawman argument.

You also didn't sufficiently address 0 argument use, which I'm sure you'd agree is very readable and intuitive: randomX().

Also with single arg use, such as randomX(50), at first glance it's reasonable to assume that the 50 represents something other than just an upper bound extension (not surprising). The margin concept of expanding or contracting from the edges is conceptually straightforward.

There's significantly less conceptual weight to what I'm proposing compared to most of the existing math related functions in p5. There are also plenty of functions in p5 that don't offer much additional functionality, but rather are simple shortcuts for common tasks. Though adding functions also adds more for beginners to learn, I think that if we keep the randomX and randomY API simple, the benefits outweigh the cons in this case.

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

[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().