Writing an age is the act of adding symbols representing different features to a Descriptive Book in order to make a customized age.

An age description will contain information about the terrain, the biomes and their layout, the weather, the lighting, the suns, moons, and stars, and the colors seen in the ages, as well as the terrain alterations (think caves/ravines) and populators (usually structures, but also giant trees, etc.) found in the world. Any segment of the description not provided by you will be filled in automatically by the grammar. Oh, and don't forget the "special effects".

Several of the segments take exactly one item -- for example, there is exactly one biome layout, or one terrain, or one weather, or one lighting. Others take a list of things -- there can be many populators, such as villages, mineshafts, dungeons, strongholds, etc.

Within any segment, or element of the segment, there will be "nouns", or "primary" items -- for example, "normal sun", or "medium biomes". These will usually take modifiers (think adjectives). The exact nature of which adjectives are valid will depend on the symbol -- a sun will take information about where it starts in the sky (at time 0), it's speed of travel, etc; the biome layout will take a list of biomes; the terrain will take the ground and sea information, and so on.

Cautions To the Author Of Worlds

It is easy to write random and mostly-random ages. If you want to specify an age completely, you need to actually //specify// it -- and you must have the necessary symbols to do so. Any aspect of the world which you do not supply will be supplied for you, and will likely be a mix of sensible defaults and random strangeness. (Note in particular that if the terrain material is not "stone", most of the biome-specific decoration, from dirt and sand on up, simply won't happen.)

In order to establish an age completely you need to provide a mix of symbols from an assortment of categories. In any category if you have not supplied a symbol of that type, at least one is likely to be supplied.

At the opposite extreme, you can write a world with no specified pages at all (just a link panel), letting the game supply //everything//. While there's no intrinsic penalty for doing that, such a world //will// have many random elements, some of which might add instability.

There are a few conditions that make an age unstable and therefore dangerous, with results ranging from afflictions for the player (or buffs for monsters), up to the world destroying itself around (and beneath) the player. These fall into two categories:

 * Outright errors in page grammar, self-contradictions, or incorrectly used symbols, will produce instability to no benefit.  However, the range of "punishable" errors has been shrinking over recent mod versions.  As of version 0.11.0, omissions in general (and many other errors) will be silently fixed by the game adding symbols to the book, which may have strange results but //mostly// won't cause instability.  However, there are still unfixable errors that will make the world unstable.
 * Aside from errors, //greed// is the primary hazard.  In particular, ages with easy-to-reach ore will almost always be unstable (and XCompWiz is working on that "almost").  Ages with piles of gold and diamonds on the surface will be //disastrously// unstable.  Most blocks (//especially// liquids) provided by other mods will also be presumed "valuable" unless the mod itself specifies otherwise.  Asking for extra block ticks ("Accelerated"), or for Bright Lighting, can cause instability.
Getting Started

First you should craft some tools. For the "quick peek" described below you'll need:

 * Ink:  Two inc sacs and a bottle of water per vial, shapeless recipe.  You'll be using a lot of ink.
 * An Ink Mixer: Creates "Link Panels".  It uses paper, and a full vial of ink for each link panel. Crafted from (smooth) stone and planks.
 * A Book Binder:  Creates descriptive books. Made from wood and iron.
 * A Linking Book (several, actually), for your tickets home.  Craft with leather and a link panel (shapeless). Most important item in the mod. 
 * Eventually, a Descriptive Book.  This is created in the book binder, from leather, a link panel, and optionally some symbol pages. This is how you get to a new age.

And you might as well complete the set of basic tools:

 * A Writing Desk:  Organizes and duplicates symbols, uses paper and ink.  Requires wood, a glass bottle and a feather.
 * Bookstands and/or Lecterns. Made from planks and sticks.
 * One or more Notebooks to collect and hold symbol pages.  Craft with 3 leather in the "bowl" shape. 

See Crafting for the crafting recipes of the above items.

In the discussion below, "using" an item or block refers to Minecraft's "use" command, which [| defaults to right-click].

Crafting a return L-Book

    • You must have a return linking book before you leave, if you want to return.** Linking books cannot be stressed enough. Usually, you'll want more than one, but even for the "quick peek" you need at least one.
 - Make a Link Panel in the ink mixer:  Place the ink mixer as a block, and "use" (default right-click) it to open the GUI.  Just load some paper and ink into the appropriate slots, and take the link panel out of the output slot.
 - Craft the link panel together with a piece of leather (shapeless recipe, you can do it in your inventory crafting grid. 
 - This gives you an "Unlinked link book".  Link books function like maps -- they are crafted as "blanks", and later activated (wield and "use") at a chosen spot.  So, choose your desired return point (any convenient spot in your base will do), and take the book there.  (If you have more than one, separate one out; you can't link a stack.)  Wield and "use" (right-click) it.
 - The book becomes a "linking book".  This book will //not// work in the same dimension it was made in, but when opened and invoked in any //other// dimension, it will return you to this spot.  (Linking books also allow travel among the Overworld, Nether, and even the End.)
 - Please note that there is a game "achievement" for traveling into an age without a return book. This is not //necessarily// a fatal mistake:  You may well be able to play "slidecraft", making books in each age, to eventually reach a world with a "star fissure" that can return you to the Overworld.  However, this is no sure thing -- it //is// possible to be trapped in an age which does not have the resources to make new books; lack of sugar cane is a particular hazard, but leather or ink may also be a problem.  There //is// a much safer way to gain this achievement, but figuring that out will be a challenge for the reader.

Crafting the D-Book

 - Make another link panel, the same way.  Instead of crafting this one, you will use it in the book binder.  
 - Like the ink mixer, place the book binder and open its GUI.  
 - Supply some leather in the left slot.  
 - In the main "track", add a link panel (and in future, any symbols you wish to add).  With no symbols at all, you will get a "random" world.
 - There is also a text box at the top of the GUI, which you canMUST use to name your new world.  As of 0.11.0 or so, descriptive books no longer get default names -- you need to name the book before you can take it.
 - Take your descriptive book from the output (right-hand slot).  

Traveling through the D-Book

For your first peek

 - Place both the D-book and the return L-book in your hot bar. 
 - Activate the D-book. (Make it the active item, and then "use" it.)  You will see the GUI of the book, with a large panel to the right. Click on that panel, and welcome to your new world.
 - On entry into the new world, select the L-book in your hot bar. Take a look around your world. If you are in any obvious danger, then immediately use your L-book. This includes but not limited to;  Stuff falling on you from above; Darkness, and/or monsters approaching you; Explosions, meteors, lightning, catching on fire.
 - If you're not in immediate danger, you can look around a bit, but don't go far or push your luck just yet.  Go back to the spawn platform before you use your L-book to return, just like you used the D-book:  Wield, Use, and click the large black panel. This will return you to where you activated that L-book.

Having returned to the Overworld

Note that both of the books you used are "gone" from your hotbar. Look around the ground where you are. There should be a large book lying on the ground right near you. This is the D-book that you used to travel. Note that while most items "float", and are picked up by touching, Mystcraft books rest on the ground (think "boat" or "minecart"), and trying to touch it will only push it.

To retrieve the book off the ground, "use" it (usually right-click). You will see the same open book with black panel. There will be a single inventory slot containing a book. Pick that up (left click, like moving something in an inventory), and you will see your inventory; you can place it in your inventory and it is now off the ground. You can also pick up book entities by sneak-using (default shift-right-click), if you have a free inventory slot.

Books are left in this "book entity" form whenever you use them "out of hand", and sometimes when they're simply dropped. (Your linking book is in the same state, back on the spawn platform in your first age. You can pick it up on your next visit.) In this form, books can take damage from the environment and eventually be destroyed. Even in a sheltered area, it will slowly take damage from exposure, but water or rain will damage it quickly, and other attacks can also harm it. (As you might expect, the book is safe while its chunk is unloaded.)

Future trip tips

This was the quick-and-dirty way, for an age which was assumed reasonably safe: For future age visits, it's better to make heavy use of bookstands or lecterns, and spare linking books:

 * The only difference between a bookstand and a lectern is height:  You'd generally use bookstands on the floor, while lecterns would go on a block, for proper "reading level".  Both protect books from the milder abuses of the environment,
 * Start by putting one in your base, and put the D-book into it.  You will use it from there, and leave it safe.
 * For each new world, you should bring 3 return L-books, two of them on your hotbar.  Also on the hotbar should be 2 lecterns or bookstands and a chest.
 * As soon as you enter your new age, place a bookstand or lectern down on the spawn platform, and put one of the L-books there.  The second linking-book should stay in your hotbar //no matter what//, as an emergency escape hatch.
 * After looking around, getting oriented, and deciding not to panic-link back home, place the chest some distance from the spawn platform -- far enough that, say, a charged creeper couldn't take out both your bookstand and the chest.  In the chest, put the other bookstand, and the third L-book (from your main inventory).
 * And //now// you can go ahead exploring, building, or whatever.  To go home normally, you'll want to go back to your spawn platform and use the book there, or place another return book at any base you set up.  If you get killed, you've got that book back at the spawn platform, or if that gets destroyed, you have the one in the chest.  And in case things go south in a hurry, you have the book in your hotbar.  Note that if you use that one you're likely to lose it -- emergency links usually imply "burning" a link book.  (Sometimes you can go back and collect it later.)  
 * Note that if you die, you will end up at the spawn platform.  In most ages, you can change this as usual with a bed.  (To sleep, there must be no suns above the horizon, or else it must be storming.)
 * Once you decide to keep using an age, make a link book to travel to some chosen point in the age (like your base there).  Put the D-book someplace safe, and use the link book for ordinary travel.  (Note that in future versions, books will wear out from use.)
Gaining Control


The next thing you'll want to do (if you haven't already) is craft three leather in the shape of a "v" or a glass bottle. This will make a notebook where you can store your pages of symbols. You may want to make several in order to organize lots of symbols, but for now one will do.

Now "use" the notebook and you will see a scrolling interface. Placing pages in the top slots will put them in the notebook. Notebooks have, for all purposes, infinite storage. Place your symbol pages in the upper inventory and they will be stored in the notebook. You can always skip this and use the writing desk to do this for you, but it's handy to have a notebook with you when symbol hunting so that the symbols you find don't take up your inventory slots as they do not stack.

Now you're ready to go hunting for symbols. Symbols are found as random treasure in dungeons, strongholds, and such. However, you will find many more in libraries, which are found in every Mystcraft Age. Symbols can also be purchased as a trade item, from a Archivist villager (bright purple robes, much snazzier than the priest's).

Writing desk

Place the writing desk down like a bed (it is 2 blocks wide). Use (right-click by default) it to open the interface.


At the very top are two utility features. The "AZ" button sorts the pages in the selected notebook, but be warned that up to version 0.11.0, the sorting is bugged: it will misarrange pages if there are any duplicates. The Search box will hide any pages not including the given search string.

Below these are the main sections: The left area is dedicated to known symbols. The leftmost column is a list of books (or pages) stored in the desk. There are 25 slots, numbered from 0 to 24 in [numerals], with scroll buttons at top and bottom. At any given time, one of the slots is selected.

Next to this is a large dark area which may have pages displayed. This is the contents of the currently selected notebook. Pages can have any position, even overlapping each other. However, the positions of pages here, do //not// guarantee any particular order of pages in the book. There is unlimited space to place pages, and the scrollbar for this area will expand to suit the contents. You can also place linking or descriptive books here, but you will not be able to see any symbols that you did not place in the book. You can pick up and move pages by left-clicking them, or copy them (to the right side of the desk) by right-clicking on them.

On the right side are areas devoted to copying and managing pages. At the top are slots for paper and ink. The bar next to the ink bottles shows the level of the current ink bottle; when empty, an ink bottle from the top will become an empty bottle below it. Each bottle can write about 25 pages, but each page uses a full sheet of paper.

Below the paper slot is another slot, which can hold a book or symbol page. This is the working slot. When you copy a symbol, it shows up here, if there is a notebook in the slot, it will be added to the end of the notebook. If any book is placed here, the "track" in the middle of this section will appear to show the pages in the book. Ths track display resembles the book binder's, showing all the book's pages in one row, and unlike the left-side display, this //does// reflect the page order in the book. While there are no visible scroll buttons, you can still scroll along this track by clicking at the edges, and for a notebook you can also rearrange the pages. Again, for a descriptive book, you will only see the symbols you wrote yourself. The text box can be used to rename any book, and if used on a descriptive book, this effectively renames the age.

Finally, the player inventory is visible at the bottom. Pages, books, and supplies can be moved as appropriate among your inventory, notebooks, the table slots, and both page-display areas.

To use the writing desk, you can drag pages around physically, or you can right-click pages in the left display area, which copies them to the right side (working slot). Everywhere on the desk, you can see the name of a page by hovering the cursor over it. This lets you organize your pages in multiple notebooks, or move and copy pages into a working notebook, eventually to be used in the book binder.

The Book Binder

The book binder has a very simple interface. The text box at the top lets you name the book you're producing, and the slot holds leather. The "track" shows the current pages in one long row, so there's no confusion about order. You can drop symbol pages in individuallty. or "dump" a notebook (the pages will stay in order. It's usually best to put the link panel in first. You can also add pages directly from your inventory, and rearrange them in the binder.

The Ink Mixer

The ink mixer's interface is simple: Paper and ink go in the left slots, empty bottles and link panels come out the right slots. In the middle, however, is an "ink pool", which is rather special. You can give your link panels (and the books they go into) special properties, by dropping various materials into the ink pool. If the addition is successful, The pool will change color and pattern to reflect the new features. Note that some materials can add one of several effects. The full list of materials and effects is given at the link above, but here is a summary of the effects and their most common sources:

 * No effect:  Adding an ink sac will clear any other effect.  Mostly useful if you got Disarm instead of something else.
 * Disarm:  Any entity linking through will have its inventory dumped on the ground //before// they are transported, so they'll arrive with nothing.  Mostly useful for traps.  Produced by several items, but gunpowder or mushroom stew are easy.
 * Generate Platform:  Every time the link is used, the spawn platform will be regenerated.  Useful for void ages or horribly unstable ones.  Granted by clay (balls).
 * Maintain Momentum:  Entities linking through will keep their velocity.  Mostly useful for traps,  Given by feathers.
 * Intra-linking:  This prized effect allows a book to be used within the same dimension, effectively a teleport.  This can be provided by Ender Pearls or Bottles o' Enchanting (or by various "dusts", if you have certain industrial mods).  Note that this effect will fade from the ink pool within a few seconds, so you should add this effect last, and take the panel while the green pattern still shows.

All the effects apply equally when a book is used by way of a portal.

Symbols, Proper Writing, and Effects

{ This section is current for 0.11,0, possibly modulo some page names }

A full list of the symbols

The basic idea of symbols is that you have to build complete phrases from parts, and then use those phrases to describe your world. Much like English words, there are various types of symbols, and they must be used in appropriate combinations, or the results can range from trivial or ridiculous mistakes, to potentially serious unpleasantness. The restrictions are few, but violating them can produce dangerously unstable worlds.

The broadest division of symbols is among "primary" symbols representing major features or alterations, and "modifier" symbols, which provide additional information about the resulting features. Each D'ni phrase consists of a primary symbol and optional modifier symbols, which need to come //before// the symbol they modify, and usually close before it: When a book is "read" by the game to create an age, modifiers will accumulate and combine on a "stack", while each primary symbol takes all the modifiers it can use off the stack. (There are also modifiers which can take other modifiers.)

The book grammar can also supply additional symbols beyond what the player wrote. These may be "safe" default values, or random (and perhaps wierd) selections. In particular:

 - If a primary symbol needs a modifier value, one will be supplied.
 - If no primary symbol in a required category (terrain, biomes, weather, etc.) is written, at least one will be supplied, and may have random modifiers added as well.  
 - If any modifiers are left unused at the end of the book, the grammar will //usually// add primary symbols that can use them (for example, extra biomes can become Floating Islands).  If this does //not// happen, the remaining modifiers can produce instability.
 - Most categories of primary symbols are also limited to one from the category per book. If more than one is used, this //will// produce instability.

Different symbols take different modifiers. For example, a moon does not currently take colors, but it can take Direction, Duration, and Phase modifiers. Most terrain controllers -- "Flat world", "Standard world", "Cave world", etc. -- will use two material blocks as modifiers (one for the land, a second for sea), but not all materials are valid for these. (And "Void World" does not use any materials, for obvious reasons.)

Only one of most modifier types can be "active" at a time. For example, only one color can be active. Trying to write a second color acts to modify the color, resulting in a new, single color. "red blue" in Mystcraft symbols is like "reddish blue" (aka "Purple") in English. Directions, phases, and durations all blend in a similar manner. However, material types and biomes do //not// blend, but are pooled until they are "picked up" by a symbol they can modify.

Material types modify a terrain controller (a "standard" world, cave world, floating island, etc.), or one of several "populators" or terrain alterations, such as obelisks or floating spheres. Internally, there is only one pool of material types, and symbols that use materials take stuff out of that collection. However, different symbols have various limits in the materials they can use: For example, obelisks can be almost any solid block, but terrain controllers choose a "land" block and a "sea" block from a limited sets. Notably, ores do not qualify as terrain blocks, while a sea block must be a liquid, ice, or the special No Seas symbol. (Mod liquids may be usable for seas, but even if they haven't been blacklisted by the mod, they tend to produce //lots// of instability.)

For the most part, this is something that you, as a writer, do not need to worry about if you write reasonably. For example, you can simply include a ground-type block, and a sea-type block, before the terrain type of the world. Equally, you can write something like "stone block, wood block, tendril, tendril", without issue, to get two sorts of tendrils. However, as usual it's wise to put modifiers immediately before what they're intended to modify, just to keep things straight and minimize unfortunate incidents.

Biome pages are modifiers, too: They modify a "biome controller" such as "Small Biomes" or "Single Biome". They can also be used by the populator "Floating Islands", and any "leftover" biomes will usually get Floating Islands supplied (without causing instability).

Length modifiers are normally relative to a "Minecraft day"; internally, they are a number that is normally used relative to the normal 20 minute (24000 tick) day cycle. So a "full length, normal sun" takes the full 24000 ticks to travel a cycle. Note that the symbols themselves do not require being used relative to a day length; addons can use them for other purposes.

Directions are used to indicate the "rising" position of objects that move.

Phases (rising, noon, setting, etc) refer to the starting position of celestial objects.

Colors can be used as modifiers directly, or combined into gradients; a gradient is essentially 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. Most symbols that accept "colors" actually accept gradients, but a lone color //can// be used for a gradient if there is not already a gradient on the stack.

When writing a book, you can only 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. As usual, if a color or length is missing when needed, it will be supplied, probably with a random value.

Causes of Instability

In older versions of Mystcraft, missing symbols would cause instability. This is no longer necessarily the case: When a player links with an incomplete or even empty Descriptive Book, symbols will be automatically selected in order to create the new age. Modifiers will also be autogenerated as needed: If you don't specify a material for the terrain, or enough biomes for the biome controller, something will be provided for you -- often a "safe" default, but sometimes a completely random variation. Likewise for the colors of sky or foliage, or the directions and speeds of various heavenly bodies.

The second main constraint is that there needs to be at least one "primary" symbol of each category. Terrain and biome controllers are obvious here, but there are also "Terrain Modifiers" and "Populators" (the difference between them is mostly internal, but they are separate categories), and if you do not supply at least one, then at least one will usually be randomly selected. The same applies for celestial bodies (need at least one each sun, moon, and stars), and weather controllers. (Symbols such as "No Weather" or "Dark Sun" do count as supplying the category.)

There is a third case: If there are //extra// modifiers (not used by any other symbol), those //may// get primary symbols added to use them. In particular, biomes tend to produce Floating Islands, while materials may produce various populators (Floating Islands, Spikes, and so forth). However, if the dangling modifiers are //not// corrected this way they will also cause instability.

There are several primary symbols that are explicitly "one per world", such as terrain controllers or weather symbols. Using more than one of these //will// cause instability.

And lastly, a few symbols will increase instability of an age simply by being used. Currently, the list of such symbols is Cave World, Bright Lighting, and Accelerated. Use of some other symbols can make ores more accessible or add more ores, adding instability indirectly. Dense Ores is the most obvious culprit, but Cave Worlds in general tend to be less stable. Adding populators made of ores (such as the classic Diamond Ore Spikes) is also a surefire way to make the world unstable, as are oceans of most mod liquids (especially oil). Note that a few mod liquids are considered dangerous enough to //add// stability.

Note that while supplying missing symbols does not itself make the world unstable, the random selection can certainly include things that //do// make the world unstable (such as ore on the surface), and the results can be odd: For example, if suns are needed, you may get more than one. Also, if the world material is not stone, "biome-specific decoration" (dirt, sand, gravel, and such) will not happen, and most ores will not be placed. (If there are stone tendrils, spheres, etc., parts of those may get surface replacement/ores.) (Exception: nether quartz ore will be placed in netherrack.) If the world material is not stone or dirt, then plants, trees, grass, and such will not appear.

A surprise for some authors: adding more and more cave symbols will increase the accessibility of the ores, increasing instability. At least, until you have so many cave symbols that there is very little ground down there.

The combination of Cave World, and Bright Lighting, plus the extra accessibility of the cave world itself, is generally worth the ordinary hazards of the "underground" start. If those are the only relevant factors, you should not see any effects on you while underground in such a world, but the surface may be unpleasant. However, any //more// instability will probably cause effects that //do// affect you underground.

Stable and Controlled Ages

For versions before 0.11.0, see Stable Ages for more helpful tips.

For current versions, and considering the previous sections:

 * Worlds are stable by default, but can be made unstable by errors, or by adding "greedy" things to the world:  More ores, faster plant growth, and so on.  
 * Ages which are not completely specified get random things added, but some of those may add instability.  
 * So, to guarantee stability, you need to specify all the key features of an age.
 * Even more important is avoiding errors:  Some categories of symbol are limited to one per age, and dangling modifiers can still produce instability and/or unexpected results.
 * Using the Clear Modifiers symbol at the end will at least minimize the damage from dangling modifiers.

The list of categories which must appear in an age (or they will be added) is as follows. Categories limited to //only// one per age are **bolded**.

 * **Terrain Generator**
 * **Biome Controller**
 * **Weather**
 * **Lighting** 
 * Sun
 * Moon
 * Stars
 * Populators
 * Terrain Alterations

For more details on these categories, see the Symbols page.

For a "clean" Void age, you can specify Caves for your terrain alteration, and Obelisks for your populator (obelisks will not spawn over the void). For other ages, Villages can be specified as a populator, but if there are no plains, deserts, or savannahs, no villages will appear. Note that this doesn't prevent all random additions: some effects such as Charged can appear regardless.

For "a world like the Overworld", see overworld-clones for tips.