playcanvas / playcanvas/engine

Merge pc.GraphNode into pc.Entity

Open
#1,035 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

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

Description

History
The engine has a layered architecture:

Layer 4 (highest): Framework (Entity, Component, Application)
Layer 3: Scene (GraphNode and related scene classes)
Layer 2: Graphics (low-level rendering layer)
Layer 1 (lowest): Core

Any given layer should be usable independent of any higher level.

Proposal
pc.GraphNode (from the scene layer) should be merged into pc.Entity. One option is to move pc.Entity, pc.Component (just component base class) and pc.Application to the core layer (maintaining the one way dependencies across layers).

Layer 4 (highest): (Components)
Layer 3: Scene
Layer 2: Graphics
Layer 1 (lowest): Core (Entity, Component, Application)

Rationale

  • The distinction between entities and graph nodes is needless and confusing.
  • Simplifies the API (and makes the API reference easier to follow).
  • Loaded models have hierarchies built from graph nodes rather than entities. This means it is not possible to directly add components to nodes in a model hierarchy (although you can add a pc.Entity as a child of a pc.GraphNode).
  • This change would pave the way for displaying a model's hierarchy in the Hierarchy panel of the Editor.

Problems

  1. There is code in the engine somewhere (or possibly the Editor) related to picking. A picked meshinstance is attached to a graph node and the node's anscestors are walked to find the parent entity. Some thought needs to be given to how we handle picking if this change is implemented.
  2. It is difficult to make this change without creating circular dependencies in the codebase. The pc.Entity class has a dependency on pc.Application which has a dependency on many classes in the scene layer.

Backwards Compatibility
pc.GraphNode should be aliased to pc.Entity.

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.

Research direction

Start by tracing pc.Entity, pc.GraphNode, pc.Application, and the scene-layer dependencies to understand where circular dependencies arise. Then inspect the engine or Editor picking path, especially how meshinstance ancestors are walked to find a parent entity. Done means GraphNode is merged into Entity, backward compatibility is preserved through an alias, and picking and layer dependencies still work.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
game-dev
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
20/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.