playcanvas / playcanvas/engine

RFC: Migrate API constants to enum-like API

Open
#7,589 32 comments 2 reactions 3 assignees View on GitHub

@willeastcott is already working on this.

Since Apr 23, 2025.

enhancement
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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.