playcanvas / playcanvas/engine

Complete deprecated API refactoring and remove deprecated.js

Open
#9,086 1 comment 0 reactions 1 assignee View on GitHub

@willeastcott is already working on this.

Since Aug 29, 2026.

Dominant language
JavaScript
Stars
16.8k
Forks
2k
Avg merge
4h 32m
Merged PRs (30d)
222

Description

Goal

Remove src/deprecated/deprecated.js and its side-effect import model while preserving compatibility that is still within its deprecation period.

This follows the pattern established by #6900 and continued by #9083, #9084, and #9085: functional compatibility members belong with their owning implementation, remain undocumented, and emit Debug.deprecated. Shims whose original functionality has already been removed should be reviewed by age and usage and deleted once they no longer justify a compatibility presence.

Remaining work

Exported aliases and constants
  • Review and relocate or remove the legacy pixel-format and blend-mode aliases.
  • Review the CHUNKAPI_* version constants.
  • Review the Key, Node, and LitOptions aliases.
  • Review the legacy input event constants.
  • Review the legacy rigid-body constants.
Standalone compatibility helpers
  • Review the primitive mesh helpers (createSphere, createPlane, createBox, createTorus, createCapsule, createCone, and createCylinder).
  • Review createMesh.
  • Review drawFullscreenQuad.
Class-owned compatibility members
  • Move or remove the remaining material compatibility members on Material, StandardMaterial, and StandardMaterialOptions.
  • Move or remove AssetRegistry#getAssetById.
  • Move or remove the XrInputSource aliases (ray, position, and rotation).
  • Move or remove the ElementInput#wheel and MouseEvent#wheel aliases.
  • Move or remove the remaining AppBase fullscreen and scene-loading helpers.
  • Move or remove ModelComponent#setVisible.
  • Move or remove the remaining RigidBodyComponent and RigidBodyComponentSystem aliases.
Cases requiring a specific decision
  • Decide how to handle the global shaderChunks proxy, which relies on the current application and cannot simply become an owner-class member.
  • Decide whether to retain or remove ForwardRenderer#renderComposition; moving its current implementation into ForwardRenderer would introduce a forbidden scene-to-framework dependency.
  • Coordinate removal or migration of Material#blend, which is still used by the Editor.
  • Review the dynamically generated StandardMaterialOptions proxies and replace them with owner-local compatibility without adding runtime reflection or unnecessary generated code.
  • Audit the already-removed Material#shader and StandardMaterial tint shims against removal date and Engine/Examples/Editor usage.
  • Decide whether silent aliases such as StandardMaterial#shininess and StandardMaterial#useGammaTonemap should gain diagnostics, remain temporarily silent, or be removed.
Final cleanup
  • Confirm remaining aliases are not used by Engine, Examples, Editor, or supported downstream tooling before removal.
  • Remove export * from ./deprecated/deprecated.js from src/index.js.
  • Remove the deprecated module entry from package.json#sideEffects.
  • Delete src/deprecated/deprecated.js and the directory if empty.
  • Verify ESM tree-shaking no longer retains compatibility code through side effects.
  • Run lint, type generation/tests, documentation generation, and relevant unit tests.

Compatibility policy

  • Keep deprecated functionality for the required compatibility window.
  • Put functional deprecated members on their owning classes without JSDoc so they do not reappear in the API reference.
  • Use Debug.deprecated only for shims that still perform their original function.
  • Delete sufficiently old no-op or Debug.removed shims after checking Engine, Examples, and Editor usage.
  • Avoid new cross-layer dependencies while relocating compatibility code.

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.