= Qualified References =
Or, how stuff is named and referred to (referenced) by Olivine scripts.  This is a core feature of the Olivine domain-specific language, it is used for identifying the following things:
 * Fixtures (blocks)
 * Items
 * Entities
 * Sound effects

A qualified reference is comprised of two parts, the ''resource group name'' and the ''sub-name''.  The syntax takes one of the two forms: `&group:name` or `&name` where ''group'' is the resource group name and ''name'' is the name of the thing in that resource group.  As you may notice, the second form doesn't specify the group, that is because it is optional.  If the thing is descriptive enough as is then Olivine will find it, however, if there is more than one thing loaded with the same name in that thing category (fixture, item, entity, sfx), but it exist in separate resource groups, then you would use the first syntax approach to be more definitive, more specific and mitigate ambiguity.  Olivine will tell you when it cannot figure-out what you're trying to reference.

== Spaces ==
If a qualified reference ''name'' part contains spaces, then wrap it backticks {{{`}}} so that it's clear to Olivine what you are trying to express, the general syntax is: {{{`some name with spaces`}}}

== Examples ==

Here is a simple example that expresses an item by name without a resource group, this will cause Olivine to go looking for it in all loaded resource groups:

{{{
   &stone
}}}

Suppose there is another resource group that the `stone` item but you want the ''Minecraft'' one, here's how you express that:

{{{
   &minecraft:stone
}}}

Referencing something with spaces in its name and has a resource group:

{{{
   &mmm:`my cool thing`
}}}

= Categorized sub-items =
Sometimes, even though we have the concept of resource groups, it is still pretty awesome to organize items into sub-item categories especially if there are a number of items that are pretty similar, such as tree saplings.  This is a part of the ''name'' part of the qualified reference and there is no limit to the number of categories and sub-categories used, but it is predetermined by the Olivine system.  This is also configurable using the Olivine configuration file.  The backslash '\' character (not to be confused with forward slashes '/') in the name part of the qualified reference is how these categories are expressed, the general syntax takes the form of `category\sub-category\name`.

== Examples ==

Here's how you would express some really awesome music in ''Minecraft'':

{{{
   &minecraft:music\game\end\credits
}}}

Here would be the way to express a sapling qualified reference:

{{{
   &minecraft:sapling\`dark oak`
}}}

= Sound Identification =
Sounds in Minecraft contain the ''dot'' character '.' to separate words.  In Olivine these are converted to backslash '\' characters consistent with categories explained above.

== Examples ==

Here's how you would express the Vanilla Minecraft sound ''mob.zombiepig.zpigangry''

{{{
   &minecraft:mob\zombiepig\zpigangry
}}}

Here's how you would reference the ''!MadMartian Mod'' sound ''sander.powered''

{{{
   &mmm:sander\powered
}}}

= Potion Identification =
Referencing potions in Olivine works very differently from other items in Minecraft due to the fact that potions are very weird in Minecraft as it is:
* Unlike items, blocks and entities, potions cannot be organized according to the mod they came from
* All potions are bound to the same item id, the meta-data is used to identify the potion type and variety
* A single potion type can have several different variety combinations called ''states''

Referencing a potion starts by using `potion` as the resource group name, the name of the potion as the top-level category, and the complete state of the potion as the second category (unless plain).

== States
Potions can have a few different ''states'' as indicated below:
* plain
* intense
* splash
* long
* intense + long
* splash + long
* intense + splash
* intense + splash + long

To identify potion combinations the qualified name works a little differently from others.  Refer to the table below to identify the potion states in a qualified reference for a potion:

||= Name =||= Ingredient =||= Denotation =||
||'''Splash'''||''gunpowder''||`x`||
||'''Intensity'''||''glowstone dust''||`2`||
||'''Duration'''||''redstone dust''||`b`||

== Examples ==

Here's a basic healing potion:

{{{
   &potion:healing
}}}

Here's a splash healing potion with extra duration:

{{{
   &potion:healing\bx
}}}

Here's an intense healing potion with extra duration:

{{{
   &potion:healing\2b
}}}

Here's an intense splash rust potion:

{{{
   &potion:rust\2x
}}}


Here's just a regular splash breathing potion:

{{{
   &potion:breathing\x
}}}

Here's long-running and intense splash fire-resistance (not sure why you'd want intensity on that potion but then again this is just an example):

{{{
   &potion:retardant\2bx
}}}