referenceSpecs [3]

IMPORTANT NOTE: This specification has been superceeded by the LDraw File Format 1.0 specification [4]

---

File Extensions
LDraw Model files carry either the extension LDR (default) or DAT. LDraw Part Files carry the extension DAT.

Text-Based
LDraw files are plain text. Each line is a single command, and each line is independent. Only a few commands are used in the file format. Specific commands are identified by the first number on the line, which is called the line-type. The contents and format of the rest of the line depend on the line-type. No length-limit on command lines is known.

Line types
Each line in the file is a single command. The first number on each line is the line type, valid values are 0 through 5, with the following meanings:

0:

comment or meta-command

1:

Part-file reference

2:

Line

3:

Triangle

4:

Quadrilateral

5:

Draws a line between the first two points, if the last two points are on the same side of that line.

If the line type for a line is not a valid value, the line is ignored.

Meta-commands require a keyword to follow the line-type. These keywords must be in all-caps, and you should assume that if the meta-command doesn't require more information, you shouldn't give it any additional information.

Commands
Here is a complete list of LDraw drawing- and meta-commands:

• Model Title
• Step
• Write
• Clear
• Pause
• Save
• Comment
• File Type
• Part
• Line
• Triangle
• Quadrilateral
• Conditional-Line

And here are the details of each command. Meta-commands are listed first, with the "real" commands after. The command-names are wholly made up by me, I don't have any "official" names for these things.

Model Title.

The descriptive name of the model- or part-file.

Line format:

0 title-text

where title-text is whatever you want to name your model.

This is a meta-command, sort of. If the first line in a file has line-type 0, the remainder of that line will be considered the title for the file (at least for parts files). This overrides any meta-commands on the line.

Step meta-command.

Marks the end of a building step.

Line format:

0 STEP

This command will cause LDraw (ldraw.exe) to stop until you press <enter>, and it will cause LDraw to save the current image into a bitmap file in the ldraw\bitmap directory. These two effects are controlled by the -M command line option (see ldraw.doc for info on -M).

Write meta-command.

Displays a message at the top of the screen.

Line format:

0 WRITE message-text

or:

0 PRINT message-text

where message-text is whatever you want displayed on the screen.

The displayed message is not saved in the image-bitmap files.

Clear meta-command.

Clears the screen.

Line format:

0 CLEAR

Useful for advanced model files. Don't forget to redraw all the parts you just erased by using this command.

Pause meta-command.

Causes LDraw to stop until you press <enter>.

Line format:

0 PAUSE

This is like the Step command, but it does not save bitmaps, and it is not affected by the -M command line option.

Save meta-command.

Causes LDraw (ldraw.exe) to save the current image in a bitmap.

Line format:

0 SAVE

This is also like the Step command, but it does not cause LDraw to pause, and it is not affected by the -M command line option.

File Type meta-command.

Indicates the type of file (model, part, etc), and if it is part of the LDraw.org Parts Library.

Line format:

     0 LDRAW_ORG type update-tag
or: 0 Official LCAD type update-tag
or: 0 Unofficial type
or: 0 Un-official type

This meta-statement should appear as the last line of the primary file header (that is, the first lines in the file, with the Model Title, Name: and Author: lines). The first format (LDRAW_ORG) is the current standard for files in the official parts library. Older files still carry the second (Official LCAD) format. The valid values for the type field are:

• Part *
• Element -
• Subpart *
• Sub-part -
• Primitive *
• Shortcut *
• Alias *
• Cross-reference +
• Model -
• Submodel -
• File -
• Hi-Res Primitive -
   
• * = values currently in use for official part files.
• + = obsolete code, still appears on some official files.
• - = only used in unofficial files

Some older official files do not include a type code on their File Type line. Unofficial files may have a variety of values after the initial tag. In particular, the type values of Element, Model, and Submodel may be used.

The exact format of the File Type line has changed over time. In general, this linetype should be considered case-insensitive and free-format.

Part command.

Inserts a part defined in another LDraw file.

Line format:

1 colour x y z a b c d e f g h i part.dat

where

• colour is a colour code: 0-15, 16, 24, 32-47, 256-511
• x, y, z is the position of the part
• a - i are orientation & scaling parameters (see below for more on this)
• part.dat is the filename of the included file

Parts may located in the p\, parts\, or models\ subdirectories (under the ldraw\ directory). They may also be located in the current directory. James has arranged the directories so that p\ contains elements that are intended to be used as part of elements (such as stud.dat). The parts\ directory contains finished parts, ready to be used in construction models. And the models\ directory contains construction models.

Part files can also include Part commands. There don't seem to be a specific limit to how deep these references can go.

Line command.

Draws a line between two points.

Line format:

2 colour x1 y1 z1 x2 y2 z2

where

• colour is a colour code: 0-15, 16, 24, 32-47, 256-511
• x1, y1, z1 is the position of the first point
• x2, y2, z2 is the position of the second point

Triangle command.

Draws a filled triangle between three points.

Line format:

3 colour x1 y1 z1 x2 y2 z2 x3 y3 z3

where

• colour is a colour code: 0-15, 16, 24, 32-47, 256-511
• x1, y1, z1 is the position of the first point
• x2, y2, z2 is the position of the second point
• x3, y3, z3 is the position of the third point

Quadrilateral command.

Draws a four-sided, filled shape between four points.

Line format:

4 colour x1 y1 z1 x2 y2 z2 x3 y3 z3 x4 y4 z4

where

• colour is a colour code: 0-15, 16, 24, 32-47, 256-511
• x1, y1, z1 is the position of the first point
• x2, y2, z2 is the position of the second point
• x3, y3, z3 is the position of the third point
• x4, y4, z4 is the position of the fourth point

Conditional-Line command.

Draws a line between the first two points, if the projections of the last two points onto the screen are on the same side of an imaginary line through the projections of the first two points onto the screen.

Line format:

5 colour x1 y1 z1 x2 y2 z2 x3 y3 z3 x4 y4 z4

where

• colour is a colour code: 0-15, 16, 24, 32-47, 256-511
• x1, y1, z1 is the position of the first point
• x2, y2, z2 is the position of the second point
• x3, y3, z3 is the position of the third point
• x4, y4, z4 is the position of the fourth point

Colours
Colours are outlined in LEDIT.DOC. Two special values are 16 and 24. 16 is the 'current colour', i.e., whatever colour was specified on the type 1 line which caused the current line to be executed. Colour 24 is a complementary colour to the current colour, usually the bright/dark complementary shade. So if the current colour is dark blue, colour 24 would give bright blue.

Also, colours 256 through 511 are dithered. So if you want to combine colours J and K, figure your colour value as

colour = (J * 16) + K + 256

The complementary colour of J is used as the complementary colour of the dithered value. So you can control the edge colour (somewhat) by switching J and K.

Format of Linetype 1
The Part command (linetype 1) has some unique features that require special attention. This section makes more sense if you're familiar with matrix math. It makes much more sense if you're familiar with using matrix math in graphic modeling.

Line Format:

1 colour x y z a b c d e f g h i part.dat

Fields a through i are orientation & scaling parameters, which can be used in 'standard' 3D transformation matrices. Fields x, y and z also fit into this matrix:

    | a d g 0 |
    | b e h 0 |
    | c f i 0 |
    | x y z 1 |

so that every point (x, y ,z) gets transformed to (x', y', z') :

    x' = a*x + b*y + c*z + x
    y' = d*x + e*y + f*z + y
    z' = g*x + h*y + i*z + z

or, in matrix-math style:

                                    | a d g 0 |
    | X' Y' Z' 1 | = | X Y Z 1 | x  | b e h 0 |
                                    | c f i 0 |
                                    | x y z 1 |

Explanation of Conditional Lines (Linetype 5)
Here is an example using the conditional line command. If we try to approximate a (cylindrical) stud with a hexagonal prism we have something like this:

             1___________2
            /             \
           /               \
         6/                 \3
         |\                 /|
         | \               / |
         |  \5___________4/  |
          \  |           |  /
           \ |           | /
            \|___________|/

• The line below 1 should not be drawn because 6 and 2 are on different sides.
• The line below 2 should not be drawn because 1 and 3 are on different sides.
• The line below 3 should be drawn because 2 and 4 are on the same side.
• The line below 4 should not be drawn because 3 and 5 are on different sides.
• The line below 5 should not be drawn because 4 and 6 are on different sides.
• The line below 6 should be drawn because 5 and 1 are on the same side.

resulting in the following drawing:

             1___________2
            /             \
           /               \
         6/                 \3
         |\                 /|
         | \               / |
         |  \5___________4/  |
          \                 /
           \               /
            \_____________/

For questions, contact Steve Bliss [5].

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