Story Library Documentation

Storyline Explanation

Function listing

Function Reference

Storyline explanation:

Everquest contains a storyline window that is accessible within the client.  The default key to open this window is Alt-N.  This library allows scripts to insert additional information into this window.  

Some definitions:

Story Window:  This is a window within Everquest that displays files.  These files can be formatted with EQHTML (Everquest HTML).  This is a limited form of HTML and allows file links, colorization and a few other elements.

The story library uses three types of file:

Master Story File:  At least one "master" file is required for EverQuest's system to realize ours exists.  EverQuest locks the master files when it first reads them, so we must use links to other files to do our dirty work.  The storyline library provides a default master file, but scripts may use their own if they wish.

Pointer File:  This is a secondary file, called a "pointer" because it "points" (links to) itself and all of the script story files.  EverQuest does not lock these files, because it's not technically in the EverQuest story system.  Because of this, we can freely modify this and our script story files.

Script Story File:  This is mainly used to show a set of data.  For example, buff or spell information, combat statistics.  Many are allowed so that the system can be categorized and not try to show everything on a single page.

                   -->Story File
                  /
Master -> Pointer<--> Story File
                  \
                   -->story file

An example: (to be replaced by screenshots when I can :)

-- EQStoryline window --
EQWatcher Information
Pursuit of the Stone
The Fall of Grobb
Mithaniel Marr's Blessing
The Stone is Stolen
-----------------
Panamah's Buff Script Information
EQWatcher Information is the master file. Panamah's Buff Script Information is a link to the pointer file for the Buff Script.  Clicking on Panamah's Buff Script Information takes you to the pointer file for the buff script, and that will contain links to the components of the buff script (i.e. help file, current buff list, etc).

Function Listing:

public string EQStoryPath;
function $Version()
function Init(string ScriptName, string ScriptDescription) as StoryInit
function Initialize(string ScriptName, string ScriptDescription, string MasterName, string MasterHeader) as StoryInitialize
function $GetScriptArray(string ScriptName) as GetScriptArray
function MasterUpdate()
function $CreateStory(string ScriptName, string storyFileName, string storyFileHeader, unsigned long arrPointer, boolean CreateLink, boolean Destructive) as StoryCreateStory
function Append(string ScriptName, string FileName, unsigned long arrOutput) as StoryAppend
function AppendLine(string ScriptName, string FileName, string OutputText) as StoryAppendLine
function Update(string ScriptName, string storyFileName, unsigned long arrOutput, unsigned long arrPointer)
function $FileNameSetup(string BasePath, string SubPath, string FileName, string Extention)
function ReadStory(string ScriptName, string storyFileName, string dynInput, boolean bStrip)
function $Pointer(string ScriptName, string storyFileName, string Extention, string storyFileHeader)
function StoryWrite(unsigned long arrStoryInfo, boolean truncate)
function $ColorString(string OutputString, unsigned long cRed, unsigned long cGreen, unsigned long cBlue)
function $Colorize(string InputString, string ColorHex)
function $ColorHexString(unsigned long cRed, unsigned long cGreen, unsigned long cBlue)
function $IntToHex(unsigned long value, unsigned long place)

Function Descriptions:

Frequently used parameters:

ScriptName - This is a string variable with the name of the script.  It should be something simple - the user will not see this name except in the file path.  It will be the name of the directory that is created to hold the story files for the script.  i.e. "Buff2"  This must remain constant throughout the script.  Every call to storylib from the same script must contain the same name.

storyFileName - This is a string variable with the name of the scripts story file.  It should be simple as well - the user will not see this except in the file path.  It will be the name of the file for the story.  Each filename must be unique.  i.e. "help", "current", "expired"

public string EQStoryPath;
Contains the path to the Everquest Storyline directory

function $Version()
Returns a string with the version information of the Story Library

string ver;
ver = Storylib.Version();

function Init(string ScriptName, string ScriptDescription)
This is the default initialization routine.  It places the story information in the default master story of EQWatcher Information.  It calls Initialize.  Unless you want your information in a different master story file, use Init.  It uses the default master story file, and therefore uses fewer parameters.  If you want to create your own master story file - use Initialize.
ScriptName - string with name of the script
ScriptDescription - string with the description of the script - can be used to identify or explain the script.  This is the text of the link the user sees in the master story window.
Return - handle to an array containing the pointer information for the script

unsigned long arrPoint; //an array handle
string MyScript = "mine"; // the short name of your script
string MyScriptDesc = "My very own script"; // the long name of your script

arrPoint = StoryInit(MyScript, MyScriptDesc);

function Initialize(string ScriptName, string ScriptDescription, string MasterName, string MasterHeader);
This is the main initialization routine.  A folder is created within the storyline folder and named after the script.  If the master file named does not exist, it is created.  A pointer file for the script is created.  An array is created with the contents of the pointer file (defaults is a link to the pointer file/itself).  An array is created which is the contents of the master story file for the script (default is a link to the pointer file).  A public variable is created as the handle to the array (this can be retrieved with GetScriptArray)
ScriptName - string with name of the script
ScriptDescription - string with the description of the script
MasterName - Filename for an alternate master file - this should be a simple name.
MasterHeader - This is the line that shows up in the selection area of the storyline window
Return - handle to an array containing the pointer information for the script.

unsigned long arrPoint;
string MyScript = "mine";
string MyScriptDesc = "My very own script";

arrPoint = Initialize(MyScript, MyScriptDesc, "othermaster", "This is a different master");

function $GetScriptArray(string ScriptName);
This function returns a string with the public variable name that defines the master story contents
ScriptName - string value with name of the script
Return - string value with name of the public variable that is the array handle to the story file master contents

unsigned long arrPoint;
string MyScript = "mine";
string MyScriptDesc = "My very own script";
unsigned long arrDesc; //array handle of master story contents

arrPoint = StoryInit(MyScript, MyScriptDesc);
arrDesc = GetPublic(GetScriptArray(MyScript));
ArrayAddElement(arrDesc, " - click the link above to see my scripts contents");
storylib.MasterUpdate(); // must be called unmasked due to a bug in the compiler.

function MasterUpdate()
This function rewrites the master file - pulling any changes made in the public arrays that defines the master story contents

function $CreateStory(string ScriptName, string storyFileName, string storyFileHeader, unsigned long arrPointer, boolean CreateLink, boolean Destructive)
This function creates or opens a story file, erases it (toggleable from Destructive), inserts a link into the pointer file (toggleable from CreateLink), writes the pointer file information to the story, and returns a string containing the link
ScriptName - the name of the script calling the function
storyFileName - the name of the story you want to open/create
storyFileHeader - the description you want in the link to this story
arrPointer - the handle to the array of the stories links
CreateLink - if true, a link will be created in the pointer file
Destructive - if true, will erase the file and put generic pointer information at top. If false will not touch the file if it exists and just create a link to it
Return - string containing the link to the story file.

function Append(string ScriptName, string FileName, unsigned long arrOutput)
This function writes an array to the end of a file, one line per element.
ScriptName - the name of the script calling the function
FileName - the name of the story to append
arrOutput - an array handle that contains the lines of text to output

function AppendLine(string ScriptName, string FileName, string OutputText)
This function writes a single string as a single line to the end of a file.
ScriptName - the name of the script calling the function
FileName - the name of the story to append
OutputText - a string with the line to append

function Update(string ScriptName, string storyFileName, unsigned long arrOutput, unsigned long arrPointer)
This function updates the contents of a story file. The entire contents must be kept in an array and passed to the Update function. The contents of the pointer file will be printed at top and bottom of the file.
ScriptName - the name of the script calling the function
storyFileName - the name of the story to update
arrOutput - handle of an array containing the complete contents of the story
arrPointer - handle of the array containing the contents of the pointer file

function $FileNameSetup(string BasePath, string SubPath, string FileName, string Extention)
This function is not exported

function ReadStory(string ScriptName, string storyFileName, string dynInput, boolean bStrip)
This function is not implemented

function $Pointer(string ScriptName, string storyFileName, string Extention, string storyFileHeader)
ScriptName - string containing name of script to create pointer for - used as directory name - if blank will use no directory
storyFileName - name of file to create link to
Extention - extention of file to create link to
storyFileHeader - text to use as the link name
Return - a string containing a link

string temp;

temp = Storylib.Pointer("buff2", "help", "txt", "This is the help file");
// the previous line creates a string of <a href="file:///storyline/buff2/help.txt">This is the help file</a>
// when seen in a story file - the link appears to be "This is the help file"

function StoryWrite(unsigned long arrStoryInfo, boolean truncate)
This function is not exported.
arrStoryInfo - handle to an array containing contents to write to file
truncate - boolean value - if true will start writing at beginning of file
This function writes an array to an open file.

function $ColorString(string OutputString, unsigned long cRed, unsigned long cGreen, unsigned long cBlue)
OutputString - string value containing text to change
cRed - value (0-255) of red to color the string
cGreen - value of green to color the string
cBlue - value of blue to color the string
Return - string with color tag applied

function $Colorize(string InputString, string ColorHex)
InputString - string value containing text to change
ColorHex - string containing a hex value representing a color
Return - string containing InputString with color tags applied

function $ColorHexString(unsigned long cRed, unsigned long cGreen, unsigned long cBlue)
This function creates a hexdecimal string representing a color
cRed - value (0-255) of red to color the string
cGreen - value of green to color the string
cBlue - value of blue to color the string
Return - string with color tag applied

function $IntToHex(unsigned long value, unsigned long place)
This function creates a string containing a hex value from a supplied value
value - integer value to convert to hex
place - number of digits to convert to (at minimum)
Return - string value containing Hex value