[page:Loader] →

[name]

A loader for LDraw resources.

[link:https://ldraw.org LDraw] (LEGO Draw) is an [link:https://ldraw.org/article/218.html open format specification] for describing LEGO and other construction set 3D models.

An LDraw asset (a text file usually with extension .ldr, .dat or .txt) can describe just a single construction piece, or an entire model. In the case of a model the LDraw file can reference other LDraw files, which are loaded from a library path set with [page:Function setPartsLibraryPath]. You usually download the LDraw official parts library, extract to a folder and point setPartsLibraryPath to it.

Library parts will be loaded by trial and error in subfolders 'parts', 'p' and 'models'. These file accesses are not optimal for web environment, so a script tool has been made to pack an LDraw file with all its dependencies into a single file, which loads much faster. See section 'Packing LDraw models'. The LDrawLoader example loads several packed files. The official parts library is not included due to its large size.

Extensions

LDrawLoader supports the following extensions:

!COLOUR: Colour and surface finish declarations.
BFC: Back Face Culling specification.
!CATEGORY: Model/part category declarations.
!KEYWORDS: Model/part keywords declarations.

Code Example


		// Instantiate a loader
		const loader = new LDrawLoader();

		// Optionally set library parts path
		// loader.setPartsLibraryPath( path to library );

		// Load a LDraw resource
		loader.load(
			// resource URL
			'models/car.ldr_Packed.mpd',
			// called when the resource is loaded
			function ( group ) {

				// Optionally, use LDrawUtils.mergeObject() from
				// 'examples/jsm/utils/LDrawUtils.js' to merge all
				// geometries by material (it gives better runtime
				// performance, but construction steps are lost)
				// group = LDrawUtils.mergeObject( group );

				scene.add( group );

			},
			// called while loading is progressing
			function ( xhr ) {

				console.log( ( xhr.loaded / xhr.total * 100 ) + '% loaded' );

			},
			// called when loading has errors
			function ( error ) {

				console.log( 'An error happened' );

			}
		);

Examples

[example:webgl_loader_ldraw]

Packing LDraw models

To pack a model with all its referenced files, download the [link:https://www.ldraw.org/parts/latest-parts.html Official LDraw parts library] and use the following Node script: [link:https://github.com/mrdoob/three.js/blob/master/utils/packLDrawModel.js utils/packLDrawModel.js] It contains instructions on how to setup the files and execute it.

Metadata in .userData

LDrawLoader returns a [page:Group] object which contains an object hierarchy. Depending of each subobject type, its .userData member will contain the following members:
In a [page:Group], the userData member will contain:

.numConstructionSteps: Only in the root [page:Group], Indicates total number of construction steps in the model. These can be used to set visibility of objects to show different construction steps, which is done in the example.
.constructionStep: Indicates the construction index of this step.
.category: Contains, if not null, the [page:String] category for this piece or model.
.keywords: Contains, if not null, an array of [page:String] keywords for this piece or model.

In a [page:Material], the userData member will contain:

.code: Indicates the LDraw code for this material.
.edgeMaterial: Only in a [page:Mesh] material, indicates the [page:LineBasicMaterial] belonging to edges of the same color code (in the LDraw format, each surface material is also related to an edge material)
.conditionalEdgeMaterial: Only in a [page:LineSegments] material, indicates the [page:Material] belonging to conditional edges of the same color code.

Constructor

[name]( [param:LoadingManager manager] )

[page:LoadingManager manager] — The [page:LoadingManager loadingManager] for the loader to use. Default is [page:LoadingManager THREE.DefaultLoadingManager].

Creates a new [name].

Properties

See the base [page:Loader] class for common properties.

Methods

See the base [page:Loader] class for common methods.

[method:undefined load]( [param:String url], [param:Function onLoad], [param:Function onProgress], [param:Function onError] )

[page:String url] — A string containing the path/URL of the LDraw file.
[page:Function onLoad] — A function to be called after the loading is successfully completed. The function receives the loaded JSON response returned from [page:Function parse].
[page:Function onProgress] — (optional) A function to be called while the loading is in progress. The argument will be the XMLHttpRequest instance, that contains .[page:Integer total] and .[page:Integer loaded] bytes. If the server does not set the Content-Length header; .[page:Integer total] will be 0.
[page:Function onError] — (optional) A function to be called if an error occurs during loading. The function receives error as an argument.

Begin loading from url and call the callback function with the parsed response content.

[method:this setPartsLibraryPath]( [param:String path] )

[page:String path] — Path to library parts files to load referenced parts from. This is different from [page:Loader.setPath], which indicates the path to load the main asset from.

This method must be called prior to [page:.load] unless the model to load does not reference library parts (usually it will be a model with all its parts packed in a single file)

[method:this setFileMap]( [param:Map fileMap] )

[page:Map map] — Set a map from [page:String] to [page:String] which maps referenced library filenames to new filenames. If a fileMap is not specified (the default), library parts will be accessed by trial and error in subfolders 'parts', 'p' and 'models'.

[method:undefined parse]( [param:String text], [param:String path], [param:Function onLoad], [param:Function onError] )

[page:String text] — LDraw asset to parse, as string.
[page:String path] — The base path from which to find other referenced LDraw asset files.
[page:Function onLoad] — A function to be called when parse completes.

Parse a LDraw file contents as a String and fire [page:Function onLoad] callback when complete. The argument to [page:Function onLoad] will be an [page:Group] that contains hierarchy of [page:Group], [page:Mesh] and [page:LineSegments] (with other part data in .userData fields).

[method:Material getMaterial]( [param:String colourCode] )

[page:String colourCode] — For an already loaded LDraw asset, returns the [page:Material] associated with the parameter colour code.

Source

[link:https://github.com/mrdoob/three.js/blob/master/examples/jsm/loaders/LDrawLoader.js examples/jsm/loaders/LDrawLoader.js]