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.

To properly understand what the expansion of an age description will look like after the grammar has corrected and filled-in any gaps, a writer needs to understand "modifiers". Briefly: Most primary (and some other) symbols are like nouns that take adjectives to modify their behavior, and while it is possible to have no adjectives, most of the time there will be at least one, and possibly many such adjectives. If a book does not specify any such modifiers, the Grammar will most likely add some. Most types of modifiers can combine within their type, allowing their results to be far more flexible than single symbols could provide. For more information see the Modifiers page, and the individual pages it links to.

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 in an internal pool, 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.