LDrawLoader.html.md 6.6 KB
Inheritance: Loader →
LDrawLoader
A loader for the LDraw format.
[LDraw](https://ldraw.org/} (LEGO Draw) is an 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 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:
- !COLOUR: Color and surface finish declarations.
- BFC: Back Face Culling specification.
- !CATEGORY: Model/part category declarations.
- !KEYWORDS: Model/part keywords declarations.
Code Example
const loader = new LDrawLoader();
loader.setConditionalLineMaterial( LDrawConditionalLineMaterial ); // the type of line material depends on the used renderer
const object = await loader.loadAsync( 'models/ldraw/officialLibrary/models/car.ldr_Packed.mpd' );
scene.add( object );
Import
LDrawLoader is an addon, and must be imported explicitly, see Installation#Addons.
import { LDrawLoader } from 'three/addons/loaders/LDrawLoader.js';
Constructor
new LDrawLoader( manager : LoadingManager )
Constructs a new LDraw loader.
manager
The loading manager.
Methods
.addDefaultMaterials() : LDrawLoader
Initializes the loader with default materials.
Returns: A reference to this loader.
.addMaterial( material : Material ) : LDrawLoader
Adds a single material to the loader's material library.
material
The material to add.
Returns: A reference to this loader.
.addMaterials( materials : Array. ) : LDrawLoader
Adds a list of materials to the loader's material library.
materials
The materials to add.
Returns: A reference to this loader.
.clearMaterials() : LDrawLoader
Clears the loader's material library.
Returns: A reference to this loader.
.getMainEdgeMaterial() : Material
Returns the material for the edges main LDraw color.
Returns: The material. Returns null if no material has been found.
.getMainMaterial() : Material
Returns the Material for the main LDraw color.
For an already loaded LDraw asset, returns the 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 material. Returns null if no material has been found.
.getMaterial( colorCode : string ) : Material
Returns a material for the given color code.
colorCode
The color code.
Returns: The material. Returns null if no material has been found.
.load( url : string, onLoad : function, onProgress : onProgressCallback, onError : onErrorCallback )
Starts loading from the given URL and passes the loaded LDraw asset to the onLoad() callback.
url
The path/URL of the file to be loaded. This can also be a data URI.
onLoad
Executed when the loading process has been finished.
onProgress
Executed while the loading is in progress.
onError
Executed when errors occur.
Overrides: Loader#load
.parse( text : string, onLoad : function, onError : onErrorCallback )
Parses the given LDraw data and returns the resulting group.
text
The raw VRML data as a string.
onLoad
Executed when the loading/parsing process has been finished.
onError
Executed when errors occur.
Overrides: Loader#parse
.preloadMaterials( url : string ) : Promise (async)
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.
url
Path of the LDraw materials asset.
Returns: A Promise that resolves when the preload has finished.
.setConditionalLineMaterial( type : LDrawConditionalLineMaterial.constructor | LDrawConditionalLineNodeMaterial.constructor ) : LDrawLoader
Sets the conditional line material type which depends on the used renderer. Use LDrawConditionalLineMaterial when using WebGLRenderer and LDrawConditionalLineNodeMaterial when using WebGPURenderer.
type
The conditional line material type.
Returns: A reference to this loader.
.setFileMap( fileMap : Object. ) : LDrawLoader
Sets a map 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'.
fileMap
The file map to set.
Returns: A reference to this loader.
.setMaterials( materials : Array. ) : LDrawLoader
Sets the loader's material library. This method clears existing material definitions.
materials
The materials to set.
Returns: A reference to this loader.
.setPartsLibraryPath( path : string ) : LDrawLoader
This method must be called prior to 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).
path
Path to library parts files to load referenced parts from. This is different from Loader.setPath, which indicates the path to load the main asset from.
Returns: A reference to this loader.