NodeMaterial documentation

[donmccurdy]

I'd be willing to write documentation for node-based materials in three.js, but need to get a couple questions answered before I feel comfortable doing so.

1. Is StandardNodeMaterial the material that should be documented, and not MeshStandardNodeMateral? I believe that's true, based on [WIP] GLTFLoader: Add .setUseNodes() option. #14572 (comment) and the goal that MeshStandardNodeMaterial will just be a drop-in replacement for MeshStandardMaterial but the docs would be very different if this is wrong.
2. Which syntax (see NodeMaterial Simplified Syntax #17105 and NodeMaterial - r8 #17265) should be documented?

I'd prefer to document only one recommended material class, and one recommended syntax style, at the beginning — even if multiple will be available. I'm a bit nervous about having many syntax permutations in use so early with this API.

/cc @sunag @bhouston

[sunag]

1. StandardNodeMaterial is a simplified version of MeshStandardMaterial it avoids some unnecessary inputs and arithmetic operations for node-based material. I started a similar simplified in other natives materials but this generated a lot of extra code. For this reason, maybe in principle, we can initially follow with MeshStandardNodeMateral? Maybe you can be started with nodes individually before adding the materials?

2. NodeMaterial Simplified Syntax #17105 is an experiment, I think that the syntax to follow is NodeMaterial - r8 #17265, its syntax is more common for threejs users, it is in fact an extension of the current syntax with some changes in functions parameters order.

[DennisSmolek]

@donmccurdy @sunag @mrdoob I know this issue is VERY old but there is still a TON of active stuff going on with Nodes (137/138 with the editor additions)

As has been mentioned before, the codebase has very little commenting and sometimes can be very confusing.

For example, From the get-go there are multiple examples that load nodes from multiple different "Nodes" folder.

Trying to figure out what everything is, how everything works and determine what "best practice" is is very difficult at the moment when I'm not even sure what the current supported nodes are and what the correct schema is for things.

Something minimal to start I think would be a simple list with the eventual goal to be similar to How Babylon's Nodes are listed

I'm pretty interested in this and am willing to help with docs/examples/etc but at the moment I'm not sure where to start nor what the plan/status/etc is...

[Mugen87]

The "old" node material located in examples/jsm/nodes and all respective examples will be removed with the next release.

I would not yet start to document the new system in examples/jsm/renderers/nodes until it is a bit more mature and stable. Otherwise we will slow down the development process since we constantly have to update the documentation.

[DennisSmolek]

Right I saw the 138 notes and that's why I decided to reach out because something is happening with Nodes but from the outside it's a bit mythical..

I understand if you're doing a major refactor you don't want to be bound by legacy or issuing changes or maintaining technical documentation.

But there's no legacy to worry about at this point.

Who is doing the rapid Dev work?

• It there a set of goals?
• Milestones?
• Reqs?
• Assignments?
• Delegation?

Or are they working free flow?
What help do they need?

How can anyone get involved?

If it's going to be black-box for a while is there a timeframe?

At the very least having a schema and list/status of current nodes would be a good guide for both the devs as well as potential implementers.

I'm not coming in and asking for a handout, I'm totally willing to put in effort,

but where all this development is happening and what the goals/timeline/etc are is frustratingly difficult to decipher..

And if the people doing all the recent work off their own write ups and stuff it would give my efforts a significant starting point...

[sunag]

@DennisSmolek I started developing NodeMaterial docs about a week or two ago. I will post what I developed in the next few days even if unfinished I think it might help . Your suggestion is good, I think it's worth sharing some goals.

[DennisSmolek]

Very awesome!

Like I said I'm willing to put in the work and you don't have to make a perfect tech guide.

• Do you have set goals?
• Specific tasks?
• Any areas you need specialized help with?
• or is low priority but open for work? (Good for new people, etc)

I've been trying to go through all the Recent PR's to catch up...

[sunag]

@DennisSmolek in next release, some goals are:

• [ ] add support to serialization files in NodeEditor NodeEditor: Support to file, textures and updates - PR 1/2 #23376
• [ ] create a serialization system to new NodeMaterial NodeMaterial: serialize/deserialize and Material.fromType() #23314
• [ ] publish NodeMaterial docs

There's a lot of open to finalize beside these, this might take a while to list, but I think any contribution would be of great help.

[Mugen87]

FYI: A JSDoc based API documentation is available with the new documentation next release ( r175). If someone is interested in writing more in-depth explanations, an ideal place for that would be the manual (https://threejs.org/manual/). Existing guides from the previous docs like Color Management have been moved to this location.