LDraw.org Discussion Forums

Here's the latest draft. Discuss!! (Note: there is a quote bug that's removing the text between <>. Be aware of that and restore the text if needed)
--
The Offical Model Repository Specification
Version: 0.3 (will turn 1.0.0 upon ratification by the LSC)
Author: Orion Pobursky

Purpose:
--------
The Official Model Repository (OMR) is a database of file in the LDraw File Format describing models that are released as sets by Lego®.

For consistency between models and ease of indexing by software, a standard for the file headers, names, and hierarchy in the OMR is needed. This document will outline the extra requirements (in addition to those set forth in the current LDraw File Format specification) for a model to be included in the OMR

Base Requirements:
------------------
All files in the model will conform to the current LDraw File Format

Base File Naming:
-----------------
Each model in the OMR will consist of several files that are packaged together into a single MPD file. For sets that include instructions for multiple models, each model will have its own MPD file. Each MPD for the set will be named in the following manner:

<Set Number>( <Optional Specifier> )-[main or alt<Number>]

Where:
<Set Number>: the number assigned on the container of the set
<Optional Specifier>: Sometimes different sets with the same number are released, the specifier will be a single digit number, in parentheses, that is different between different sets, to distinguish these sets from one another.
[main or alt<Number>]: The main model of the instructions (i.e. the model featured on the cover of the container) will have the word "main". For sets that feature more than one model on the front of the container (e.g. the Creator line), the largest or most prominent model is the main model. For alternate models that are detailed in instructions, the word "alt" and a single digit number starting at 1 will be used. For playsets or other sets where there are multiple models that are part of an integral whole, all of the submodels will be contained in the main model MPD.

Example:
Set 4896 - Roaring Roadsters. This creator set has 3 models in the instructions. The roadster is featured prominently on the box. 4896 is the only set with that number. Therefore:
Roadster MPD: 4896-main.mpd
Dragster MPD: 4896-alt1.mpd
etc...

MPD File Structure:
-------------------
The MPD will conform to the MPD File Specification.

The naming of the individual files in the MPD wis up to the discretion of the author with the following guidance:
- A logical nameing scheme is highly desired.
- Individual models in the set (e.g a vehicle or minifig) shall have thier own separate file inside the MPD.
- Minifig file name should have the name of the character, if known
- The <MPD Filename> is reqired to be prepended to the file name of each indiviual file in the MPD

The unofficial parts are allowed to be used. The filename of the unoffical part is subject to the naming rulles above (e.g. 33056.dat would be renamed to <MPD Filename> - 33956.dat). It is highly encouraged that any parts created for use in a OMR file be submitted to the LDraw.org Parts Tracker.

If a part is unavailable both officially or on the LDraw.org Parts Tracker. a suitible substitution may be made. If the unavailable part is a patterned part with an unpatterned version available use the unpatterned version. A comment should be inserted stating that a subtitution has been made or, if no substitution is available/suitable, that a piece has been omitted. Reference the step and page number of the instructions if possible.

Example:
0 // The next peice should have the Star Wars Hatch pattern per step X on page Y
or
0 // Bionicle piece X should ge here per step Y on page Z

File Headers:
-------------
Each individual model file in the MPD must have a standard header format.

Standard Header:
0 FILE <MPD Filename> - <Filename>.ldr
0 <MPD Filename> - <File Desciption>
0 Name: <MPD Filename> - <Filename>.ldr
0 Author: <Author Name>
0 !LDRAW_ORG Official Model Repository
0 !LICENSE Redistributable under CCAL version 3.0 : see CAreadme.txt

0 !THEME Theme name
0 !KEYWORDS words, more words,…,
0 !KEYWORDS words in second row, …, final words

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

Where:
<MPD Filename>: The name of the containing MPD
<Filename>: The name of the file
<Author Name>: The name of the author. Real full name are highly desired but not required. If the full name is not provided, a first or last name, with or with out initials, is requested.

Optional commands are !THEME, !KEYWORDS, and !HISTORY

Example:
To Be Inserted Later

META commands:
--------------
All META commands are allowed in the model file but not specifically required except as specified for the header. If included, any META commands used should enable any instructions generated to be as close to the official instructions as possible.

The more I think of, the less sense this:

<Set Number>( <Optional Specifier> )-[main or alt<Number>]

makes to me. Looking at the set currently in the Official Models forum all come with its name. A:

<Set Number>( <Optional Specifier> )-<Set Name>

would make it more human readable and also solve the problem with the alternative model:

MPD: 4896-Roadster.mpd
MPD: 4896-Dragster.mpd

The rest looks just fine to me beside Lego should be LEGO - you know how picky they are on this.

w.

Hmm. Good point. The Creator line still requires a subspecifier. Something like 4896-<Creator Set Name>-Dragster.mpd Usually 3-4 models are in the instructions to those sets. Also, adding the set name means that we can get rid of the optional specifier.

I'm toying with requiring the 0 !THEME Meta in the header. Thoughts?

Do we need some way of indicating which component(s) of the official library are required? If a model relies upon Alias or Physical_Colour parts, which are optional installs, it will fail to render if the user has only installed the Core parts library.

Although we have made great strides forward, there are still 21 Non_CA files in the official library, so a similar issue might apply to them.

Chris

Chris Dee Wrote:
-------------------------------------------------------
> Although we have made great strides forward, there
> are still 21 Non_CA files in the official library,
> so a similar issue might apply to them.

Could you please list them? Also prioritize them would make sense.

w.

No, I don't think so. If a user needs to install an official distributed product, then they can.

How will they know whether or not they need to install the optional library components? If they have opted to only install the Core Library and a model uses a part from the Alias or Physical_Colour libraries, they will just get a "file not found" error but will not have any clue as to why. They will think the .mpd is broken and we wil have to deal with questions.

Something like this might help:
0 !REQUIRE LDraw_Core
0 !REQUIRE LDraw_Alias
0 !REQUIRE LDraw_Physical_Colour

Another way around it would be to ensure that models only use Core Library (+/- unofficial) parts.

Chris

Chris Dee Wrote:
-------------------------------------------------------
> Another way around it would be to ensure that
> models only use Core Library (+/- unofficial)
> parts.

Personally I would go for this and prohibit the usage of aliases or physical colored parts.

w.

Orion Pobursky Wrote:
-------------------------------------------------------
> I'm toying with requiring the 0 !THEME Meta in the
> header. Thoughts?

I'm not all against the idea, but I think it could fit in under 0 !KEYWORDS or maybe (but probably not?) 0 !CATEGORY.
I'm not 100% familiar with those two metas and what's the difference between them as I don't use them.

Just my 50 öre...
/Tore

Maybe:
0 !KEYWORDS Theme_name, words, more words....
ie, requiring the theme name as the first keyword?

/Tore

No I think Theme needs it's own META. 0 !CATEGORY is for parts and, to me, 0 !KEYWORDS is probably not needed but I kept it since I knew someone would ask.

I'm not sure a new command is needed. We can just scan the MPD, identify if there are any of these types of parts, and the publish the requirement on the download page. We're already going to scan the file for header and syntax complience so this doesn't really add on that much.

Some thoughts:

Why must the full mpd filename be prepended to every submodel? That's very redundant and makes for very long names. I think it's enough to only add something to embedded parts.

In spirit of the part standards you shouldn't allow spaces in the 'new' part names, so maybe only add 'unof-' infront of them e.g.: unof-33956.dat

Why don't use !keywords for the theme, it's already done for parts e.g. 6267.dat

Willy Tschager Wrote:
-------------------------------------------------------
> Personally I would go for this and prohibit the
> usage of aliases or physical colored parts.

I agree, I never understood the need for colored parts anyway.

The point is to have each file inside the MPD have a unique name. This is for file tracking purposes and to prevent file overlap if the MPDs are unrolled in 1 directory. As far as part naming, I'm trying to make this spec as loose as possible while still preserving some structure. This will allow more submissions in a shorter amount of time and not discourage the non-technical form submitting files.