We need to support extensions that use but do not require specific libraries. For example, a mod might want to take advantage of a paid library if it is installed.

This spec describes support for optional libraries:

Optional Include

We add a parameter to the library directive to indicate that a given library is optional:

<Library unid="&unidCorporateHierarchyVol01;" optional="true"/>

At bind time we treat this like a normal library directive but ignore the case where the library cannot be found (instead of returning an error).

Optional Types

A mod should be able to include types that rely on an optional library. For example, a certain mission might only be available if a given optional library is available. Similarly, we need to support fallback types which are included only if an optional library is not available.

We add a parameter called libraryCriteria:

<Type unid="..."
   libraryCriteria="+&unidCorporateHierarchyVol01;; -&unidHumanSpaceHD;;"
   ...
</Type>

In the example above, the given type is included only if Corporate Hierarchy Vol 1 is available, and if Human Space HD is not available.

Save/Load Considerations

Note that we must keep the set of libraries consistent across save/load. That is, if an optional library is included in a game, it must be included on subsequent loads. If the library cannot be found, we return an error at load time.

Similarly, if a game is created without an optional library and the library later becomes available, the game still loads without the library.

wolfy 4 May 2015:

The game should know not to error out on the use of a unid from an optional library though, but not sure how this would be implemented due to it needing the entity key-value pairs in the library in order to figure out what a given &Entity; string corresponds to.

Not sure if this was mentioned here?

the_shrike 5 May 2015:

So would this let me make an SM&M++-like mod that loaded (and modified entities from) the CC and EP libraries if available, but would ignore that stuff (and anything in that section) automatically? It's currently possible to do via bundling into different XMLs, but it'd be neat to be able to condense things.

arkheias 8 Dec 2017:

I am interested in optional libraries.

george moromisato 22 Dec 2017:

Optional libraries are now implemented in 1.8 Alpha 4. See also: https://ministry.kronosaur.com/record.hexm?id=75908

NOTE: When a library is optional, you cannot refer to any UNIDs defined by the library. You must define those UNIDs in your own header. More over, since the library is optional, you cannot assume the type exists.