User:TheSatanicSanta/Mystcraft Wiki import/Grammar

Mystcraft's signature feature is the creating of new worlds by means of descriptive books. In the original Myst lore, writers had to fill in a complete description of their new world, or face disaster. However, in earlier versions of Mystcraft, it became clear that in a Minecraft mod, such a high standard makes for impractical gameplay; it is necessary to give the player some breaks, or age-writing will be so dangerous that players won't have the chance to master the craft. Accordingly, the mod has become progressively more forgiving over recent versions.

In current Mystcraft if the book does not completely describe a world, the game will randomly fill in the missing parts to produce a complete "age description", at the cost of player control. In the extreme case, an "empty" book consisting only of a link panel will produce a completely random world; more-or-less stable, but likely with some undesirable features. Errors in writing can still add instability, but over versions 10 and 11, omissions and some (not all) other errors became "correctible", adding random features but not instability.

Both the checks for correct writing, and this filling-in process, are performed by the mod code known as "the grammar". More formally, the Dn'i writing is represented as a "regular-expression grammar", a set of simple rules for how symbols can and must be combined (and if the player doesn't do so, the game will). A writer who violates these rules in their book will at least get unexpected results, and they risk adding instability to their world for uncorrected errors.

Symbols added by the grammar will be hidden; the player cannot view nor copy them from the book, nor change a book after its Age has been created. Thus, it is easy to write random and mostly-random ages, but if a player wants to control an Age's contents, they will need to collect the necessary symbols to do so, and learn how to use them properly.

Writing a World
The age description is a series of Dn'i symbols, each page of the book containing one symbol. These symbols are organized into a series of "phrases". Each phrase consists of a "primary symbol", with both required and optional "modifier symbols". The primary symbols fall into categories, representing various required features of a world. Each category (one exception, see below) must appear at least once in an age, and some categories can also appear only once. The modifiers appear first, followed by the symbol they modify. There are also a few modifiers that can be preceded by modifiers of their own.

When a world is first created (the descriptive book is linked for the first time), the book is read in page order, following various rules:
 * 1)  Modifiers are accumulated (by rules described below), until they are "accepted" by another symbol.
 * 2) Each symbol read will accept the modifiers that apply to it, removing them from further consideration. Any other modifiers will wait for a future symbol.
 * 3) If a symbol does not have any required modifiers, a random choice will be made (and additional modifiers may be added).
 * 4) If a symbol does not have optional modifiers, some may be supplied, otherwise default values will be used.
 * 5) Some categories of primary symbols may not appear more than once; having a second symbol from such a category is an error.  (instability)

At the end of the book, the grammar fills out the description further: Example: "Suns" is one of the required categories, but can appear multiple times. It has only two options: "Normal Sun"  puts a sun in the sky, and takes modifiers specifying its path in the sky. A "Dark Sun" does not put anything in the sky, and takes no modifiers. If a writer specifically wants to have no sun in their Age, they need to explicitly specify "Dark Sun"; if no sun page is specified at all, the grammar will add one or more. Since it will be randomly choosing between dark and normal suns, the world then might have no, one, or many visible suns. Similarly, if the path of a visible sun is not specified it will have a random choice of modifiers, and could end up fixed in the sky or moving at any speed or direction.
 * 1) If a required category did not appear in the book, the grammar will choose one of the options randomly.  If the category can appear multiple times, the grammar can add multiples.  If the new symbol(s) take modifiers and none are available, those will also be randomly chosen as above.
 * 2) If any modifiers are left unclaimed at the end of the book, this is an error:  In V10, it will always add instability.  As of V11, primary symbols may be added to claim the dangling modifiers.  However this is not guaranteed, and any unfixed modifiers will still add instability.
 * 3) A very few symbols will add instability merely by being used.  As the world is generated and explored, instability can also be added by the presence of excessive ores or other valuable materials.

Primary Symbols
These are the categories required for a full age description (and the exception). Starred categories must apear once and only once. Note that in V12, the "Populators" and "Terrain Alterations" categories were merged, and re-divided by size. Each category should be described on its own page.
 * Terrain generators *
 * Controls the overall shape of a Age, and takes material modifiers for the terrain and sea.


 * Biome controllers *
 * Specifies biomes for the Age, and their arrangement. The particular biomes to be used are supplied as modifiers.


 * Weather *
 * Several options for the overall weather of an Age. None take modifiers.


 * Lighting *
 * Options are Normal, Bright, and Dark, affecting overall visibility regardless of lighting. They take no modifiers.


 * Suns
 * Adds (or doesn't) suns to the sky. Modifiers specify their speed and path, and "sunset colors" (which also apply to sunrise).


 * Moons:
 * Adds (or doesn't) moons to the sky. Modifiers specify their speed and path, and "sunset (moonrise, moonset) colors".  Up through V12 there is no way to affect the phase, all moons will match the Overworld's.


 * Stars
 * A variety of starfields are available, including an End-like field of static. Modifiers control their motion and colors.


 * Visuals
 * These symbols control the overall coloration of an Age, separately controlling sky, clouds, water, grass, and so on. They take color or gradient modifiers, or specify a match for the Overworld.  Also includes a couple of Mystcraft features, Rainbow and Boundless Skies.  Note that within the Visual category, each color scheme may only be specified once:  For example, having two Sky Color symbols is an error.


 * World Features
 * These categories provide various features to the world -- structures ranging from pillars or floating islands through lakes, caves and ravines, and even dungeons, villages, strongholds, and the like.  Up through V11 these were divided into "Populators" and "Terrain Alterations", but as of V12 they have been recategorized by size.  Most take various modifiers, especially for the material they are made of.
 * Populators (Up to V11)
 * Terrain Alterations (Up to V11)
 * Small Features (V12)
 * Medium Features (V12)
 * Large Features (V12)


 * Special Effects (not required)
 * This category includes various special symbols which are not required for a world, and will not be randomly added by the grammar.

Modifiers
Modifiers are the symbols that fill in the details for the primary symbols. As a new descriptive book is "read" on creation, modifiers are alternately accumulated as they are read, and "used up" when they are accepted by other symbols. They do fall into categories, but these are only "required" in context, and as noted above, they can easily be filled in by the grammar. Each type is discussed on its own page, as linked below.

Several modifier types share an "blending" behavior. As a book is read, at most one value is held for Colors, Lengths, Directions, and Phases. This value starts out "unset", until the first modifier of each type gives it a value. When another modifier of the same type is encountered, it will be combined pairwise with the current active modifier, to produce a new value. This allows the modifier values to take values beyond those provided by individual symbols, such as directions other than the four compass points. When another type of symbol accepts the modifier of that type, the value will again be considered unset. Gradients work much the same, except that they accumulate by adding steps onto the current Gradient (and accepting Color and Length modifiers).

Biomes and material blocks are also modifiers, but these do not blend, only accumulate on a stack. When a primary symbol needs one or more biomes or materials, it will take the most recent eligible items from the stack, leaving any others undisturbed. Different primary symbols have different restrictions on the materials they can accept. See their pages for more details.

The Sunset color symbol does not blend, and can be used either as a modifier to a Sun or Moon. It is distinct because it can also double as a Visual primary symbol, providing a default for those suns and moons without their own sunset colors. Either way it takes a Gradient.

The special symbol "Clear Modifiers" will use all dangling modifiers at the point it was encountered. In V10 it eliminated the resulting instability, while in later versions it still minimizes the cost for the errors.

It's wise to put modifiers immediately before what they're intended to modify, just to keep things straight and minimize unfortunate incidents. While a writer can get away with writing "Stone Block, Oak Wood Block, Tendrils, Spheres", it's much safer to write "Stone Block, Spheres, Oak Wood Block, Tendrils" for the same results, and be clear about which material goes with which structure.