playcanvas / playcanvas/engine
RFC: Migrate API constants to enum-like API
@willeastcott is already working on this.
Since Apr 23, 2025.
- Dominant language
- JavaScript
- Stars
- 16.8k
- Forks
- 2k
- Avg merge
- 4h 32m
- Merged PRs (30d)
- 222
Description
The API currently has a huge list of hundreds of capitalized constants that kind of play the part enums (which JS doesn't technically support natively). For example:
https://api.playcanvas.com/engine/variables/ADDRESS_CLAMP_TO_EDGE.html
Let's look at this specific group:
/**
* Texture data is not stored a specific projection format.
*
* @category Graphics
*/
export const TEXTUREPROJECTION_NONE = 'none';
/**
* Texture data is stored in cubemap projection format.
*
* @category Graphics
*/
export const TEXTUREPROJECTION_CUBE = 'cube';
/**
* Texture data is stored in equirectangular projection format.
*
* @category Graphics
*/
export const TEXTUREPROJECTION_EQUIRECT = 'equirect';
/**
* Texture data is stored in octahedral projection format.
*
* @category Graphics
*/
export const TEXTUREPROJECTION_OCTAHEDRAL = 'octahedral';
We could rewrite that to:
/**
* Texture projection modes for storing texture data. These define how the texture's data is
* interpreted or sampled, such as cubemap or equirectangular projections.
*
* @readonly
* @enum {string}
* @category Graphics
*/
export const TextureProjection = Object.freeze({
/** No specific projection format is used. */
None: 'none',
/** Cubemap projection format. */
Cube: 'cube',
/** Equirectangular projection format. */
Equirect: 'equirect',
/** Octahedral projection format. */
Octahedral: 'octahedral'
});
So, for properties and functions that took one of those constants and was typed as @type {string}, we could update to @type {TextureProjection}. This would result is a much more nicely structured API reference manual, with related constants grouped on the same page.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.