LDraw.org Standards: File Format Restrictions for the Official Library

Maintained by: The LDraw.org Standards Committee
Author: The LDraw.org Standards Committee
Writers: William Howard
Contributors: Many

Specification

This document describes additional restrictions to the LDraw File Format 1.0.2 specification for official parts. Unless contradicted by this document all details within the LDraw File Format 1.0.2 specification apply to official parts.

LDraw Files

File Name

Filenames must not be longer than 25 characters (including the extension) and must only contain the following characters: a-z, A-Z, 0-9, _, and - (to avoid confusion with English grammar, comma is not a permitted character). While both upper and lower case letters are permitted in filenames, filenames are case-insensitive. Currently, all official parts are issued with upper-case only names.

Extension

All files in the LDraw Parts Library are required to carry the .DAT extension.

Numeric Precision and Format

Precision

In general, three decimal places are sufficient for parts, sub-parts and primitives representing portions of parts that are not intended to be scaled (for example, studs, pegs, peg-holes, clips, hinge ends, etc). Four decimal places should be used for hi-res primitives and any primitives designed to be scaled (for example, cylinder sections, boxes, rectangles, discs, edges, etc) as this allows such primitives to be scaled by a factor of ten while still preserving three decimal places of accuracy. The primitives reference indicates which primitive families are not supposed to be scaled.

Format

Trailing zeros must be removed (ie 1.5 not 1.500). Leading zeros unless immediately before the decimal point must be removed (ie 1.5 not 01.5). The leading zero before the decimal point is optional (ie 0.5 and .5 are both valid).

Co-planar Tolerance

A quad (line type 4) must be planar, meaning that if it is split into two triangles, both triangles will be co-planar with each other. There are always two ways to split a quad into two triangles, and both must result in co-planar triangles. The triangles are considered co-planar if the angle between their surface normals is less than or equal to 3 degrees, however, an angle of less than 1 degree is strongly recommended, especially for large quads where the "warp" can be seen in the part at normal viewing magnifications. (Note: Parts already in the library or certified on the tracker are not to be re-submitted just to fix any co-planar violations.)

Colinear Tolerance/Concave Quads

A quad (line type 4) or triangle (line type 3) must not have aligned vertices. Additionally, quads should always be convex. (Concave quads should be split into two triangles.) To avoid concave quads, as well as aligned vertices in triangles and quads, every interior angle in a quad or triangle must not be greater than 179.9 degrees or smaller than 0.025 degrees. (Note: Parts already in the library or certified on the tracker are not to be re-submitted just to fix any colinear violations.)

Duplicate Line Types

Identical sub-files (line type 1) are not permitted.

Identical lines and conditional lines are not permitted. The order of end points is not considered when checking for identical lines (line types 2 and 5). Control points are not considered when checking for identical conditional lines (line type 5).

Identical triangles and quads are not permitted. The ordering of vertex points is not considered when checking for identical polygons (line types 3 and 4).

Overlapping and Intersecting Line Types

All or part of a line (line type 2) may not overlap all or part of any other line (line type 2).

All or part of a conditional line (line type 5) may not overlap all or part of any other conditional line (line type 5).

Part (but not all) of a conditional line (line type 5) may overlap all (but not part) of a line (line type 2).

Consider the line A-B-C-D

  • If AB and CD need to be conditional lines and BC a line, it is acceptable to define this as a line BC and a single conditional line AD
  • If AC needs to be a line and just CD needs to be a conditional line, it is not acceptable to define the conditional line as either AD or BD
  • If AD is a line, there are no valid conditional lines along the length of AD

Lines (line type 2 or 5) may intersect any other line (line type 2 or 5).

Every effort must be made to remove overlapping co-planar polygons (line type 3 or 4). Where overlapping polygons are unavoidable, the overlap must be kept to the absolute minimum.

Every effort must be made to remove intersecting (non co-planar) polygons (line type 3 or 4). Where intersecting polygons are unavoidable, the intersection(s) must be kept to the absolute minimum.

Note: Primitives that overlap/intersect other primitives or polygons (line type 3 or 4), provided that the overlap is small, are considered acceptable. The intention is not to force part authors to in-line primitives. However, there may be some cases where it is better to use (say) a 3-8cyli and a quad than a 1-2cyli; case-by-case decisions are left to the parts review process.

Matrix restrictions

The matrix specified for sub-files (line type 1) must not be singular nor contain columns or rows of all zeros.

Colour restrictions

Polygons (line types 3 and 4) must not use colour 24.

Lines (line types 2 and 5) should not use colour 16.

There are two cases where use of colour 16 for lines is acceptable:

  • where a line is being used for fine detail within a pattern and that pattern is re-used within many parts (and hence sub-parted) in different colours (for example, sub-part s/973p11a.dat)
  • when a sub-part pattern leaves a narrow gap of base-part colour around the pattern(for example, see sub-part s/973p11b.dat)

All colour numbers used in part files must be present in LDConfig.ldr, with the exception of pattern/sticker geometry, which may use Direct Colours (see LDraw Spec).

META Commands

(See also List of Official META Commands.)

Header Meta Commands

Official parts must conform to the Official Library Header Specification.

Body Meta Commands

Only the following meta commands are permitted in the body of official parts:

  • 0 // style comments
  • BFC CW
  • BFC CCW
  • BFC CLIP
  • BFC CLIP CW
  • BFC CLIP CCW
  • BFC NOCLIP
  • BFC INVERTNEXT

Legacy parts may not conform to these rules. Legacy parts (including those already on the Parts Tracker) should not be edited solely for the purpose of making them conform. However, if the part is changed for any other reason, non-conformant lines must be updated.

Generated line types

Lines and polygons generate by a utility program (such as LSynth) must conform to this specification. The meta commands used to generate the line types may be left in the part file provided they are correctly commented out. It is desirable to add a comment to mark the end of the generated section.

Sticker Shortcuts

Shortcuts that consist of one part (which may be a composite part) and one or more stickers are allowed in the official library. Such shortcuts will have a filename consisting of the part number for the part, followed by a "d", followed by a two-digit number that starts at 01 and increases with each new part/sticker shortcut. If the sticker is applied to a composite part, the full composite part filename will be used before the d. For example, the first sticker/part shortcut created for part 30185c01.dat would have a filename of 30185c01d01.dat. The following restrictions apply:

  • The shortcut may not include more than one part, although that part can be a composite part (one with a "c" in the filename).
  • The sticker(s) must entirely fit on the part, with no portions of the sticker(s) extending beyond the boundaries of the part.
  • The sticker(s) must be applied in the same location(s) as shown in the instructions for the official LEGO model from which the sticker(s) originate(s).

LDConfig.ldr

LDConfig.ldr will only contain colours that have at some point in time been used by LEGO as the non-painted colour of materials used in LEGO-branded toys, plus ldraw.exe's special colour codes 16 and 24. This includes materials such as the metal track for 9V train tracks, but does not include the colours of paint used to decorate parts or ink used on stickers.

Stud groups

Stud groups are provided to reduce the size of part files with many regularly spaced studs. The naming convention is as following:

stugN-XxZ.dat

where:

  • N = type of stud (regular stud, hollow stud, underside stud, …)
  • X = number of studs on the x axis
  • Z = number of studs on the z axis

To prevent an overload of the library with all sort of combinations, the numbers on the x and z axis are limited to:

  • 1xZ stugs
  • Xx1 stugs (Due to stud orientation you cannot rotate a 1xZ stud group by 90 degrees to get a Xx1 stud group)
  • XxZ stugs where X==Z

These primitives must not be scaled.

Note: This document is an official LSC specification and/or language extension. Material changes can only be made after ratification by the LSC.