Guide: Siege University - 202: Lorebooks

== Introduction ==
A lore book is an object within the game, which has the physical appearance of a book, and can be traded or manipulated between inventories. The most important aspect of the lore book is the wide format scrollable window. This allows very long text to be written within it and referred to at the player's leisure.
The advantages of creating lore books are many, as the casual nature of the books within an adventure means that the player is not forced to read large volumes of text during important events or encounters, but can instead refer to them when engaging in casual activities, or whenever detailed information is required. Normally, lore books can be discarded or sold just like any other treasure, so it is not a good idea to expect the player to keep a book in their possession to further the plot or quest. If information absolutely must remain accessible to a player during an adventure, that information may be more appropriate in the journal, which will be discussed under quests in later Siege University courses. The primary difference being that the player does not have the option to discard Journal entries if the designer does not wish it.
=== What You Need For This Tutorial ===
* Dungeon Siege, updated to version 1.09B or later 
* A text editor. Notepad will work fine; UltraEdit-32 offers advanced functionality. 
* Untanked resource files, specifically Logic.dsres, if you did not untank in Siege U: 201. 
What This Tutorial Assumes You Have Already Learned
* Siege U: 100 - The Basics of the Siege Editor, specifically sections regarding tanking/untanking maps. 
* Siege U: 200 - Dungeon Siege Concepts and Terminology 
* Siege U: 201 - Templates 
What This Tutorial Will Teach You
* The components of a Lore Book and the steps needed to create your own 
* Additional tools used to convey the story 
Untank Logic.dsres
To untank the Logic.dsres into its editable components, follow these steps:
# Start the Siege Editor. 
# Select Convert .dsmap to Files... from the File Menu. 
# For the Source File, browse to Dungeon Siege\Resources. 
# Under "Files of type:", switch to Dungeon Siege Resource Files (*.dsres) 
# Select Logic.dsres and click Open. 
# For the Destination Folder, leave it at its default setting (My Documents\Dungeon Siege\Bits). 
# Click OK. 
# Once the untanking is completed, exit the Siege Editor. 
You have now untanked the Logic.dsres file into My Documents\Dungeon 
Siege\Bits. File paths listed in this tutorial can be found in this directory. If you untanked to a non-default directory, you will have to look there to find the files referenced below.
== Show me a Lore Book! ==
There are two components to make a lore book whole: the template and the Lore Key. The template resides within contentdb, and contains the information that determines the lore book's appearance in the world, minus the actual text that appears within the book. This template will look roughly like Figure 1.1 below:
Figure 1.1 A sample Lore Book Template:
 [t:template,n:book_glb_lore_goldsniffer]
 {
 category_name = "lorebook";
 doc = "Goldsniffer Mags";
 specializes = base_book_lore;
 [aspect]
 {
 [textures]
 {
 0 = b_i_glb_book-lore-02;
 }
 }
 [common]
 {
 screen_name = "Remembrance of Mags";
 }
 [gui]
 {
 lore_key = lore_goldsniffer;
 }
 }
(taken from world\contentdb\templates\regular\interactive\trs_book_lore.gas)
The second part of a lore book is the Lore Key, which is referred to in the template above as lore_goldsniffer. The Lore Key contains all the formatted text that appears within the book itself, and looks roughly like Figure 1.2 below:
Figure 1.2 A sample Lore Key:
 [lore_goldsniffer]
 
 {
 
 description = "A direct descendant of the mule packs imported by 
 Etan Stonebridge, 'Mags' was one of the most remarkable animals 
 ever to tread the Glitterdelve's stony passages.\n\nPreferring to 
 wander the darkness of the mines than be above, she often would 
 chew her way free of her restraints, only to be found hours later 
 standing near exposed veins of gold. In time, other miners began 
 to experiment with 'Goldsniffer' Mags' gold-homing nose, discovering 
 to their fortune that she possessed an uncanny knack of gravitating 
 to undiscovered deposits of rare metals.\n\nBut Mags could also be 
 temperamental, and sometimes demonstrated her pique by leading 
 miners to drill barren shafts which the locals began to call 
 'Mag Holes.' Beloved for her unusual talent, she easily would have 
 been remembered in the history books of the Glitterdelve, but it was 
 her actions during the Great Blast of 943 which would forever ingrain 
 her into the hearts and minds of her keepers.\n\nFollowing the 
 accidental ignition of unvented gases in a newly hewn coal shaft, 
 the passages of the mine became a howling death trap of flame and 
 flying rock for those trapped within.\n\nWhether disoriented by the 
 blast, or truly perceiving what had occurred, Mags broke free from 
 her restraints and plunged into the roiling black smoke of the mine, 
 even as stunned dwarves and men bolted from the fury of the roaring 
 catastrophe.\n\nVanishing from the sight of terrified onlookers for 
 nearly a quarter hour, Mags at last stumbled from the mine, dragging 
 three half-dead miners by the trailing rope of her broken harness. 
 Able only to stagger a few yards from the entrance with her 
 tremendous burden, 'Goldsniffer' Mags collapsed in a wheezing 
 heap, never to rise again.\n\nHaving pulled the last survivors of 
 the Great Blast to safety, Mags died the following morning, 
 surrounded by weeping men who knew her for the one-time miracle she 
 truly was.\n\nEighteen years later, the monument to her final heroism 
 would be constructed at the very spot she died.";
 
 }
(taken from world\maps\map_world\info\lore.gas)When used together, these two components (template and key) can give properties that make them very much like a normal book you would find in the real world.
== Lore Book Components ==
A discussion of each component broken down from Figure 1.1 and Figure 1.2 above follows:
=== Naming Convention ===
Figure 2.1 A sample Naming Convention:
 [t:template,n:book_glb_lore_goldsniffer]
As discussed in Siege U: 201 - Templates, the scheme used for naming lore books can follow any convention, but consistency is the key, especially when a large number of these books are to be used in a map. The text that appears in the template is not contained within the same gas file, so if the name does not reflect the content of the book, it will be very easy to misplace the books you have created when it comes time to add them to your world.
=== Category Name ===
Figure 2.2 A sample Category Name:
 category_name = "lorebook";
Category names determine the location of objects within the file tree of Siege Editor menus.
=== Documentation ===
Figure 2.3 A sample Documentation:
 doc = "Goldsniffer Mags";
The name you give here is what is seen as the name of the object when in the Development name content display in Siege Editor.
=== Specialization ===
Figure 2.4 A sample Specialization:
 specializes = base_book_lore;
Specialization is the template component that gives the exact properties to the object, in this case a Lore Book. Unless you want to further specialize the Lore Books you use at a template level, this is the only specialization you will ever need.
=== Texture ===
Figure 2.5 A sample Texture:
 [aspect]
 {
 [textures]
 {
 0 = b_i_glb_book-lore-02;
 }
 }
A large number of textures for Lore Books already exist if you want to create a distinctive look to accompany the contents. Those textures can be found at art\Bitmaps\Items\Global. The default texture if none are listed under [aspect] is [b_i_glb_book-lore.psd]. The magic book textures are sized identically, so nearly 30 different textures can be applied to the book you are creating. You can, of course, apply your own textures to apply to the books you create, for placement within the same directory structure.
=== Screen Name ===
Figure 2.6 A sample Screen Name:
 [common]
 {
 screen_name = "Remembrance of Mags";
 }
This is the actual text that appears on an in-game mouseover of the Lore Book you are creating. Don't forget the value of a mouseover name. In some cases that name can be more important than the contents themselves, see below for more discussion
=== Reference ===
Figure 2.7 A sample Lore Key Reference:
 [gui]
 {
 lore_key = lore_goldsniffer;
 }
This is the name used to connect the template in trs_book_lore.gas to the actual text that appears in lore.gas under the directory structure of the map you are creating.
=== Lore Key ===
Refer to Figure 1.2 above
The Lore Key is linked to the template by the Lore Key Reference block at the top.
The text block of the Lore Key can have any amount of text. Keep in mind that the size limitation of the Lore window will make anything over 2,000 characters appear rather daunting to the player, and possibly cause him or her to lose interest in your written material.
Formatting of the Lore Key block can be accomplished by adding spaces before and after text within the block, and by using the 'carriage return' character [\n] within the text itself. All other forms of formatting will be rejected by the engine when used in the Lore Key block.
To create separated paragraphs, simply use a double carriage return [\n\n] at the beginning of the next paragraph. To create large indents, just include several spaces within the body of the text.
== Conclusion ==
Creation of the Lore Book only requires some simple editing of two separate gas files. The first file is the template, wherein properties of the book can be adjusted. The second file is the Lore Key, which contains all the text that will appear within the book. 
Lore books are a very simple way to convey story and background into your world, without the additional work associated with timing of dialog and Story Sequences. Lore Books can contain an unlimited volume of text, and can be placed and transferred just like any other inventory object in game, making them an excellent choice for worlds that have a lot of story to tell.
== Appendix A: Conveying the Story in the Big Picture ==
Conveying story in your Siegelet can be accomplished in many ways, and you do not need to use all the tools available, but should consider switching out different methods to keep it interesting for your readers/players. 
In general, the primary ways to powerfully convey story are: mouseover names, specialized artwork, audio dialog, text dialog, lore books, journal entries, and story sequences. A short discussion of each follows: 
Mouseover Names
An often-overlooked device, mouseovers can convey a large amount of meaning to a category. Whether it is on an item or an NPC, the name they have can quickly convey whether they are friendly or enemy, and what action should be taken with them. An example would be using different mouseover names on a normal box. If the text that appeared when mousing over the box said 'Secula's Podium', that would convey a very different meaning and required action than if it said 'A clean crate', or 'A box of explosives'. The same goes for NPCs, where 'A wounded skeleton' or 'An aging peasant' might be able to convey something that the animation or posture does not. This should not be relied on heavily, as some players will not pay attention to the mouseovers, and would therefore miss the point. Consider using these names to add flavor for the attentive players, but do not depend on them to convey all your meaning.
=== Specialized Artwork ===
Creating legible text in artwork is very difficult when all possible resolutions are taken into account. What can be conveyed are important recognizable signals like a wanted poster, or a simple nameplate. Consider using specialized artwork when you have to convey a recognizable image in your world.
=== Audio Dialog ===
The premium map will include plenty of audio dialog. Although expensive, large, and/or time consuming, this is a widely accessible way to convey story. The best places to use dialog are for grandstanding and posturing in key encounters, background narration, and with storytellers.
=== Text Dialog ===
Second fiddle to Audio Dialog, text dialog can fill many of the same roles but with much less emotion. Some of the limitations on text dialog are: the difficulty in using it for enemy encounters when a click box would be inappropriate, and in places where you want to convey story during a surprise. The more casual players can also avoid text dialog. There is no guarantee that players will actually see it as they play through.
=== Lore Books ===
Lore Books are excellent for displaying large amounts of text in a casual manner. This shares the disadvantage of avoidance that is found in Text Dialog, but can be called upon at any time. If the relevance of a book is highlighted somewhere in the story, players will be more likely to hold onto them as they play through.
=== Journal Entries ===
Tightly woven in with Quests are Journal Entries. The Journal does not have to remain specific to Quests if the designer so desires, and can instead be used to keep important points at the player's easy reference later on.
=== Story Sequences ===
Action scenes can efficiently convey emotion and/or gravity of a situation, and are a very effective way to show off some of the nicer looking areas of your world. Story Sequences will not currently function in multiplayer games, so these are in the realm of the single-player experience.