LDrawLoader cleanup and docs improvement (#23231)

* LDrawLoader: Remove two unused vars in parse scope object

* Remove redundant local variable 'parentParseScope'

* Use local variable 'subobjects'

* Substitute color codes literal values with static constants.

* LDrawLoader: Improve documentation

* Fix invalid class static constants

* Fix docs about main color codes constants

* Change getMainColorCode to getMainMaterial

* Change getMainMaterial docs

docs/examples/en/loaders/LDrawLoader.html

@@ -37,7 +37,7 @@
 		</p>
 
 		<ul>
-			<li>!COLOUR: Colour and surface finish declarations.</li>
+			<li>!COLOUR: Color and surface finish declarations.</li>
 			<li>BFC: Back Face Culling specification.</li>
 			<li>!CATEGORY: Model/part category declarations.</li>
 			<li>!KEYWORDS: Model/part keywords declarations.</li>
@@ -176,9 +176,41 @@
 
 		<h3>[method:Material getMaterial]( [param:String colourCode] )</h3>
 		<p>
-		[page:String colourCode] — For an already loaded LDraw asset, returns the [page:Material] associated with the parameter colour code.
+		[page:String colourCode] — Color code to get the associated [page:Material].
 		</p>
 
+		<h3>[method:String getMainMaterial]()</h3>
+		<p>
+		Returns the [page:Material] for the main LDraw color.
+		</p>
+
+		<p>For an already loaded LDraw asset, returns the [page:Material] associated with the main color code.
+		This method can be useful to modify the main material of a model or part that exposes it.
+		</p>
+
+		<p>
+		The main color code is the standard way to color an LDraw part. It is '16' for triangles and '24' for edges. Usually
+		a complete model will not expose the main color (that is, no part uses the code '16' at the top level, because they
+		are assigned other specific colors) An LDraw part file on the other hand will expose the code '16' to be colored, and
+		can have additional fixed colors.
+		</p>
+
+		<h3>[method:String getMainEdgeMaterial]()</h3>
+		<p>
+		Returns the [page:Material] for the edges main LDraw color.
+		</p>
+
+		<h3>[method:void preloadMaterials]( [param:String path] )</h3>
+		<p>
+		[page:String path] — Path of the LDraw materials asset.
+		</p>
+
+		<p>This async method preloads materials from a single LDraw file. In the official parts library there is a special
+		file which is loaded always the first (LDConfig.ldr) and contains all the standard color codes. This method is
+		intended to be used with not packed files, for example in an editor where materials are preloaded and parts are
+		loaded on demand.</p>
+
+
 		<h2>Source</h2>
 
 		<p>

examples/jsm/loaders/LDrawLoader.js

@@ -1486,6 +1486,9 @@ function createObject( elements, elementSize, isConditionalSegments = false, tot
 
 //
 
+const MAIN_COLOUR_CODE = '16';
+const MAIN_EDGE_COLOUR_CODE = '24';
+
 class LDrawLoader extends Loader {
 
 	constructor( manager ) {
@@ -1631,16 +1634,14 @@ class LDrawLoader extends Loader {
 
 			// Subobjects
 			subobjects: null,
-			numSubobjects: 0,
-			subobjectIndex: 0,
 			inverted: false,
 			category: null,
 			keywords: null,
 
 			// Current subobject
 			currentFileName: null,
-			mainColorCode: parentScope ? parentScope.mainColorCode : '16',
-			mainEdgeColorCode: parentScope ? parentScope.mainEdgeColorCode : '24',
+			mainColorCode: parentScope ? parentScope.mainColorCode : MAIN_COLOUR_CODE,
+			mainEdgeColorCode: parentScope ? parentScope.mainEdgeColorCode : MAIN_EDGE_COLOUR_CODE,
 			matrix: new Matrix4(),
 			type: 'Model',
 			groupObject: null,
@@ -1715,6 +1716,16 @@ class LDrawLoader extends Loader {
 
 	}
 
+	getMainMaterial() {
+
+		return this.getMaterial( MAIN_COLOUR_CODE );
+	}
+
+	getMainEdgeMaterial() {
+
+		return this.getMaterial( MAIN_EDGE_COLOUR_CODE );;
+	}
+
 	parseColorMetaDirective( lineParser ) {
 
 		// Parses a color definition and returns a THREE.Material
@@ -1975,13 +1986,13 @@ class LDrawLoader extends Loader {
 
 			// Parses next color code and returns a THREE.Material
 
-			if ( ! forEdge && colorCode === '16' ) {
+			if ( ! forEdge && colorCode === MAIN_COLOUR_CODE ) {
 
 				colorCode = mainColorCode;
 
 			}
 
-			if ( forEdge && colorCode === '24' ) {
+			if ( forEdge && colorCode === MAIN_EDGE_COLOUR_CODE ) {
 
 				colorCode = mainEdgeColorCode;
 
@@ -2054,8 +2065,6 @@ class LDrawLoader extends Loader {
 		currentParseScope.category = info.category;
 		currentParseScope.keywords = info.keywords;
 		currentParseScope.subobjects = info.subobjects;
-		currentParseScope.numSubobjects = info.subobjects.length;
-		currentParseScope.subobjectIndex = 0;
 		currentParseScope.type = info.type;
 		currentParseScope.totalFaces = info.totalFaces;
 
@@ -2236,8 +2245,6 @@ class LDrawLoader extends Loader {
 		const parseScope = this.newParseScopeLevel( null, parentScope );
 		parseScope.url = url;
 
-		const parentParseScope = parseScope.parentScope;
-
 		// Set current matrix
 		if ( subobject ) {
 
@@ -2245,13 +2252,12 @@ class LDrawLoader extends Loader {
 			parseScope.inverted = subobject.inverted;
 			parseScope.startingConstructionStep = subobject.startingConstructionStep;
 			parseScope.fileName = subobject.fileName;
-			if ( subobject.colorCode === '16' && parseScope.parentScope ) {
+			if ( subobject.colorCode === MAIN_COLOUR_CODE && parentScope ) {
 
-				const parentScope = parseScope.parentScope;
 				parseScope.mainColorCode = parentScope.mainColorCode;
 				parseScope.mainEdgeColorCode = parentScope.mainEdgeColorCode;
 
-			} else if ( subobject.colorCode !== '16' ) {
+			} else if ( subobject.colorCode !== MAIN_COLOUR_CODE ) {
 
 				parseScope.mainColorCode = subobject.colorCode;
 				parseScope.mainEdgeColorCode = subobject.colorCode;
@@ -2267,7 +2273,7 @@ class LDrawLoader extends Loader {
 		const promises = [];
 		for ( let i = 0, l = subobjects.length; i < l; i ++ ) {
 
-			promises.push( loadSubobject( parseScope.subobjects[ i ] ) );
+			promises.push( loadSubobject( subobjects[ i ] ) );
 
 		}
 
@@ -2281,7 +2287,7 @@ class LDrawLoader extends Loader {
 		}
 
 		// If it is root object then finalize this object and compute construction steps
-		if ( ! parentParseScope.isFromParse ) {
+		if ( ! parentScope.isFromParse ) {
 
 			this.finalizeObject( parseScope );
 			this.computeConstructionSteps( parseScope.groupObject );