LDraw.org Standards: Official Library Header Specification

Maintained by: The LDraw.org Standards Committee
Writers: Willy Tschager, Travis Cobbs, William Howard
Revision: 9.0, 06 Sep 2007

Specification

LDraw Official Library header format suitable for the implementation of the Contributor Agreement (CA).

Scope

The header has to identify the LDraw.org username - the basis upon which CA affirmation is assessed - and if the part is covered by the CA or not. It has to conform to the new meta command syntax, where backwards compatibility allows this, as well as structure the history comment lines.

Syntax

0 PartDescription
0 Name: Filename.dat
0 Author: RealName [UserName]
0 !LDRAW_ORG Part|Subpart|Primitive|48_Primitive|Shortcut (optional qualifier(s)) ORIGINAL|UPDATE YYYY-RR
0 !LICENSE Redistributable under CCAL version 2.0 : see CAreadme.txt

or
0 !LICENSE Not redistributable : see NonCAreadme.txt

0 !HELP Optional free text description of file usage
0 !HELP Second row after user's line break to simulate paragraph

0 BFC ( CERTIFY ( CCW | CW ) | NOCERTIFY )

0 !CATEGORY Category name
0 !KEYWORDS words, more words,...,
0 !KEYWORDS words in second row, ..., final words

0 !CMDLINE LDraw run-time command(s)

0 !HISTORY YYYY-MM-DD [UserName] Free text description of change. This can wrap to a
0 !HISTORY YYYY-MM-DD [UserName] second row with the same date if necessary. However authors should lean toward writing longer
0 !HISTORY YYYY-MM-DD [UserName] single !HISTORY lines(and not feel constrained to the historic 80-character limit on line length)

or
0 !HISTORY YYYY-MM-DD {RealName} Free text description of change

0 // Comments

1 <colour> x y z a b c d e f g h i <file>

Where:
PartDescription is the descriptive name of the part. If the part is good enough for public use, but has some deficiencies that need to be addressed, the text " (Needs Work)" (without the quotation marks) can be added to the end of the description. If the description includes "(Needs Work)", a comment must be added to the file immediately following the official header describing the work that needs to be done.
Filename
is the file name
RealName is the author's real name.
UserName is the author's LDraw username. It needs to be optional for those past authors that still don't have a username.
YYYY-RR is the LDraw update year and release within year.
CAreadme.txt or NonCAreadme.txt is the human readable version of the CCAL added to the parts library package. The square brackets are included in the file to indicate LDraw usernames.

The following meta-commands are optional:
!HELP (Authors should constrain themselves to a 50-character limit to keep the text readable.)
!CMDLINE
BFC (It is highly recommended to include this statement with a NOCERTIFY for non-BFC certified parts, but not required.)
!KEYWORDS
!CATEGORY (This is required if the first word of the part description isn't in the official category list here: LDraw.org CATEGORY and KEYWORDS Language Extension. Note however, that if CATEGORY is set it has to be one of the listed categories.)

All other meta-commands above are mandatory. No other meta-commands are allowed in the part header.

Examples

0 Animal Scorpion
0 Name: 30169.dat
0 Author: Chris Dee [cwdee]
0 !LDRAW_ORG Part UPDATE 2006-01
0 !LICENSE Redistributable under CCAL version 2.0 : see CAreadme.txt

0 !HELP Obviously there is no need for additional
0 !HELP information in this part. But it will give
0 !HELP you an idea of a primitive formatting.
0 !HELP
0 !HELP We should limit the length of
0 !HELP a line to 50 characters for the sake of readability.

0 BFC CERTIFY CW

0 !CATEGORY Animal
0 !KEYWORDS Sting, Poison, Adventurers, Egypt
0 !KEYWORDS Zodiac

0 !CMDLINE -c1

0 !HISTORY 2000-08-?? {Axel Poque} fixes to resolve L3P error messages
0 !HISTORY 2000-08-?? {Manfred Moolhuysen} fixes to resolve L3P error messages,
0 !HISTORY 2000-08-?? {Manfred Moolhuysen} fixed gap where body meets head
0 !HISTORY 2002-04-25 [PTadmin] Official update 2002-02
0 !HISTORY 2004-05-18 [guyvivan] Made BFC compliant
0 !HISTORY 2004-05-18 [guyvivan] Used more primitives
0 !HISTORY 2006-??-?? [PTadmin] Official update 2006-01

0 // Tail
1 16 1 0 23 1 0 0 0 1 0 0 0 1 4-4cyli.dat

or

0 Boat Base 8 x 10
0 Name: 2622.dat
0 Author: Chris Alano
0 !LDRAW_ORG Part UPDATE 2000-02
0 !LICENSE Not redistributable : see NonCAreadme.txt

0 BFC NOCERTIFY

0 !KEYWORDS Pirates, Caribbean, Ship

2 24 100 24 80 80 24 20

Appendix I (29-Sep-06)

Format of the !LDRAW_ORG meta-statement suitable for the LDraw Parts Tracker.

0 !LDRAW_ORG Unofficial_Part| Unofficial_Subpart| Unofficial_Primitive |Unofficial_48_Primitive|Unofficial_Shortcut (optional qualifier(s))

This basically adds the prefix "Unofficial_" to the file type and removes the UPDATE details. It will be implemented within the PT GUI to automate the generation/correction of this line during the sub-mission process by deleting any existing "0 !LDRAW_ORG" line in a submitted file and insert an "0 !LDRAW_ORG Unofficial_..." line in the correct place.

Appendix II (02-Oct-06)

Format of the "~Moved to" files suitable for the implementation of the Contributor Agreement (CA) by using the special username of [PTadmin].

Scope

The current format of the "~Moved to" files:

0 ~Moved to {new_number}
0 WRITE Part {old_number} moved to {new_number}
0 BFC CERTIFY CCW 1 16 0 0 0 1 0 0 0 1 0 0 0 1 {new_number}.dat

(where {new_number} and {old_number} are LDraw part numbers)

does not conform to the agreed standard above. It has therefore been changed to the following format.

Syntax

0 ~Moved to {new_number}
0 Name: {old_number}.dat
0 Author: [PTadmin]
0 !LDRAW_ORG {Part, Subpart, etc as appropriate} (optional qualifier(s)) UPDATE YYYY-RR
0 !LICENSE Redistributable under CCAL version 2.0 : see CAreadme.txt

0 BFC CERTIFY CCW

0 !HISTORY {date} [PTAdmin] {any necessary comment(s)}

0 // {part_description}
1 16 0 0 0 1 0 0 0 1 0 0 0 1 {new_number}.dat
0

Examples

0 ~Moved to 3842a
0 Name: 193a.dat
0 Author: [PTadmin]
0 !LDRAW_ORG Part UPDATE 2006-01
0 !LICENSE Redistributable under CCAL version 2.0 : see CAreadme.txt

0 BFC CERTIFY CCW

0 !HISTORY 2006-12-31 [PTadmin] Official update 2006-01

0 // Minifig Helmet Classic with Thin Chin Guard
1 16 0 0 0 1 0 0 0 1 0 0 0 1 3842a.dat
0

There is however a possible issue with any programs that use the removed "WRITE" line to update parts.

The new format has been worked out in collaboration with the Parts Tracker Administrators and meets their requirements. The PT GUI submission page will include a check, such that PT authors cannot submit a "~Moved to" file. Implemented should also be a check for existing version of the file against the newly-submitted version, for the case an author changes the title to something other than "~Moved to".

Appendix III (06-Sep-07)

Optional qualifiers for the !LDRAW_ORG meta-statement

Alias

The purpose of the Alias qualifier is to identify a part which is visually identical to another (often caused by LEGO using two differnet numbers, one for opaque and one for transparent versions of the same part (e.g. 32061), but more recently, there have also been new part numbers for well-established parts - such as brick 2x6
An alias file will typically, but not necessarily, contain only one sub-file reference (line type 1) entry
A file with an Alias type qualifier must not refer to a file that itself has an Alias qualifier.

Physical_Colour

The purpose of the Physical_Colour qualifier is to identify a part which is encoded as a specific colour of a part (e.g. 70770)
A part file with the Physical_Colour qualifier will typically, but not necessarily, contain only one sub-file reference (line type 1) entry, where the entry has a specific colour value and not colour 16.

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