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 however, 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 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, any other modifiers will wait for a future symbol.
 * 3) If a symbol does not have its required modifiers, again a random choice will be made (and additional modifiers may be added).  This includes primaries added by the previous rule.
 * 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:
 * 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.

Example: "Sun" 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 no sun page is specified at all, the grammar will add one or likely more. Since it will be randomly choosing between dark and normal suns, the world might have no, one, or many visible suns. If a writer specifically wants to have no sun in their Age, they need to explicitly specify "Dark Sun". 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.

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: Normal or amplified landscapes, cave or island worlds, or even an empty void. The materials for the world are supplied as modifiers.


 * Biome Controllers *
 * Specifies biomes for the Age, and their arrangement. They can range from tiny to huge, or be tiled in grids, or a single biome can cover the entire world.  The particular biomes to be used are supplied as modifiers.


 * Weather *
 * Several options for the overall weather of an Age, which can be fixed or changeable at various speeds. None of these take modifiers.


 * Lighting *
 * Options are Normal, Bright, and Dark, affecting overall visibility within the age. They take no modifiers.


 * Suns
 * Options are Normal Sun to add a(nother) sun to the sky, or Dark Sun, which does not appear nor shed light. Normal Sun takes modifiers for speed, direction, and position along its path, and also for the "sunset colors" (which also apply to sunrise).


 * Moons:
 * As with suns, the options are Normal Moon to add a(nother) moon to the sky, or Dark Moon, which does not appear in the sky. Normal Moon takes the same modifiers as Normal Sun:  Speed, direction, and position along its path, and also for the "sunset colors" (moonrise and moonset).


 * Stars
 * The options include Normal, Twinkling, or Dark Stars, or an Ender Starfield. The Normal and Twinkling stars take modifiers for speed and direction of motion.  These and the Ender Starfield also take a Gradient modifier for their colors.


 * Visuals
 * These symbols control the overall coloration of an Age, separately controlling sky, clouds, water, grass, and so on. Each colorable thing can get its own color or gradient modifiers, or (most of them) can be set to match the Overworld.  Also in this category is a Mystcraft feature, Rainbow.  Note that within the Visual category, each color scheme may only be specified once:  For example, having two Sky Color symbols is an error.


 * Structures and Alterations
 * 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 Populators (V12)
 * Medium Populators (V12)
 * Large Populators (V12)


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

Modifiers
For most modifier types, only one of the category can be "active" at a time. This applies to Colors, Lengths, Directions, Phases, and Gradients. When a new modifier of the same type is encountered, it will be combined pairwise with the current active modifier, to produce the new modifier for that type.

Biomes and material blocks are also modifiers, but these do not blend. They are accumulated on a sort of 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. See below for more details.

There is also a special "Sunset Color" symbol, which does not blend, and can be used either as a modifier or as a Visual primary symbol.

Blending Modifiers
Colors are the simplest example. A second color symbol will be averaged (RGB-wise) with the current color, resulting in a new color. The combination "red blue" in Mystcraft symbols is like "reddish blue" (aka "Purple") in English. Directions, phases, and durations all blend in a similar manner. All of these combine stepwise: If "red, blue, white" is written, the first two will produce purple, then the white will combine for a light purple. However, "red, white, blue" will go from pink to a somewhat darker and bluer purple.

Length (Duration) modifiers represent the length of a cycle or sequence. For most uses, the values are relative to a "Minecraft day" of 20 minutes (24000 game ticks). So a "full length, normal sun" takes the full 24000 ticks to travel a cycle. Note that the Length symbols themselves do not imply the day length; addons can use them for other purposes, and the "Sunset Colors" symbol applies them to the length of the sunset/sunrise effect. "Zero Length" is a little special: It combines with the others in the usual fashion, but if used alone, it will be interpreted as "no cycle", for example a sun that does not move in the sky. Currently (up to V12), lengths can range only up to Double Length, because that's the longest duration available as a symbol.

Directions are used to indicate the "rising" position of objects that move. They combine compass-wise: "West, North, South" will be further south than "West, South, North". Note that if you begin with, say "North, South", it is not officially defined whether you will get East or West for the next step.

Phases (Rising, Zenith, Setting, Nadir) refer to the starting position (the position they had at time 0) for celestial objects. "Zenith" and "Nadir" mean straight up and straight down respectively. They likewise combine stepwise, with the same warning about starting with opposed values.

Gradients are a complex modifier: A gradient is a sequence of colors, each with a length. When used, the color displayed will change over time, as given by the symbols that went into the gradient. Each step is defined by one Gradient symbol and its Color and Length modifiers. That is to say, when the grammar is parsing a book, it will have at most one gradient, one color, and one length active at a time. Each Gradient symbol will take all three of these, and replace them with a new gradient, adding the new color and length to the end. The default gradient is empty (the first Gradient symbol specifies the first step), but if there is no current color or length, a random value will be supplied. Many of the "Something Color" symbols actually take gradients; if they find a color but no gradient available, the grammar will supply a Gradient symbol, to produce a single-step gradient. This will also use any current Length value, but in any case a single-step gradient looks like a fixed color.

Non-Blending Modifiers
Material types modify a terrain controller (a "standard" world, cave world, floating island, etc.), or one of several "populators" (or, before V12, terrain alterations), such as obelisks or floating spheres. Biome pages are modifiers, too: They modify a "biome controller" such as "Small Biomes" or "Single Biome". Both biomes and materials can also be used by the populator "Floating Islands".

Material types and biomes do not blend, but are pooled until they are "picked up" by an appropriate primary symbol. Internally, there is only one pool of material types, and symbols that use materials take symbols out of that collection. Different symbols have various restrictions for the materials they can use: For example, obelisks can be almost any solid block, but most terrain controllers choose a "land" block and a "sea" block from limited sets. Notably, ores do not qualify as terrain blocks, nor do such materials as Stone Brick. Similarly, a "sea" block must be a liquid, ice, or the special No Seas symbol. Mod liquids may or may not be usable for a world's seas, but even a "seabanned" liquid can be used for lakes.

If you write reasonably, you should not need to worry too much about the details. It's wise to put modifiers immediately before what they're intended to modify, just to keep things straight and minimize unfortunate incidents. While you 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.

Sunset color is slightly special: It can modify a single normal sun or moon, but if found "dangling" at the end of the book (no sun or moon found after it), it will set the "default" sunset colors, for all suns or moons without their own sunset colors. Either way, it takes a Gradient modifier.