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.
LDrawLoader supports the following extensions:
// 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 building 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' );
}
);
[example:webgl_loader_ldraw]
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.
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:
In a [page:Material], the userData member will contain:
[page:LoadingManager manager] — The [page:LoadingManager loadingManager] for the loader to use. Default is [page:LoadingManager THREE.DefaultLoadingManager].
Creates a new [name].
See the base [page:Loader] class for common properties.
See the base [page:Loader] class for common methods.
[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.
[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)
[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'.
[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).
[page:String colourCode] — Color code to get the associated [page:Material].
Returns the [page:Material] for the main LDraw color.
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.
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.
Returns the [page:Material] for the edges main LDraw color.
[page:String path] — Path of the LDraw materials asset.
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.
[link:https://github.com/mrdoob/three.js/blob/master/examples/jsm/loaders/LDrawLoader.js examples/jsm/loaders/LDrawLoader.js]