This page describes an older version of the Wide Ruled Story Generator, for the latest version click HERE ---- ---- ---- ===== Wide Ruled 1.0 (Old Version, No longer supported) ====== Welcome to the Wide Ruled information page. Wide Ruled is a Java program that allows a user to create automatically generated stories, using an author goal-based planning system. It is based on the Universe model of story generation. It is an an experimental research tool developed by the [[http://eis.soe.ucsc.edu/wiki/index.php/Main_Page|Expressive Intelligence Studio]] in the [[http://www.soe.ucsc.edu|School of Engineering]] at the [[http://www.soe.ucsc.edu|University of California, Santa Cruz]]. ===== Download ===== Download the zip file for the program [[Wide Ruled Release Files|here]]. ===== Install and Run ===== - You will need at least version 1.5.0 (a.k.a. Java 5), or Java 1.6 (a.k.a. Java 6) of the [[http://java.sun.com/javase/downloads/index.jsp|Sun Java Runtime Environment (JRE)]]. The Java runtime software is available for Mac, PC, Linux/Unix, and many other operating systems. - Extract the files from the downloaded zip file. - Run the program in three ways: * Double-click the included "WideRuled.bat" file if you are using Windows, or * From within the extracted folder, type "java -cp bin WideRuled" at a command prompt within a Unix or Mac OS 10 environment. * If you do not wish to see the story generator text output information in the command line, get the jar file version of Wide Ruled from the [[Wide Ruled:Wide Ruled Release Files|download page]], and simply double click on the .jar to run it. - A sample story comes with the program in the "Sample" directory. It is a simple Wide Ruled-based depiction of a typical episode of the T.V. show [[wp>House_(TV_series)|House MD]]. It makes use of character, environment, and plot point manipulation, as well as looping. - Start creating your own story! Make your characters, environments, plot points, and author goals! ===== Support ===== If you have any problems, please first read the [[Wide Ruled:Wide Ruled#Potential Problems, Slip-ups, or Bugs|Potential Problems]] and the [[Wide Ruled:Wide Ruled#General Debugging Notes|General Debugging Notes]] sections first. They have good info in them that I have picked up as I have developed and used Wide Ruled. If you have any more problems with Wide Ruled, please go to [[Wide Ruled:Support]] page, where you can publicly edit the page and add questions to be answered by me or any others who are having the same problem. ===== A Note About This Information ===== Most of Wide Ruled strives to be as straight forward as possible, even for those without programming or scripting experience. Where possible, it uses non technical language to describe information and processes. Obviously, due to the fact that this story generation model is indeed a lot like programming, there are concepts, such as the storing of variables, the passing of parameters, and the depth-first search style of goal execution that requires explanation for non-technical users. Because of this, the following description of features contains some detail that may be obvious for technical users. ===== General Editing Information ===== * **Hidden or Partially Hidden Text and Buttons:** I have developed Wide Ruled on a Windows XP computer with the latest versions of both Java 1.5 and Java 1.6. It uses the Java native "look and feel", instead of the default Java Metal look. The native "look and feel" uses the interface buttons, windows, and other widgets that come from the host OS running Wide Ruled, and therefore generally make a user feel less intimidated by the more foreign Metal interface appearance. I also used it because I believe it is a bit more pleasing to the eyes than Metal, both with Windows and Mac OS native interfaces. Unfortunately, due to this choice, as well as general Java interface inconsistencies, the buttons and text input boxes in the Wide Ruled interface can sometimes appear to be crammed together or run off the edge of a window, cutting off the view of their labels and contents. I have tried to remedy this by making those windows with potential interface problems resizable by the user. If you are having an issue, first try resizing the window by clicking and dragging the bottom right-hand corner of the window which is causing a problem. If you still cannot see something that you need to see, please contact me either though the [[Wide Ruled:Support|Support]] page, or by email. * **List Editing:** When you are editing a list of items, you can often double or single click on the item in the list to edit the value. For example, on the first, main screen in Wide Ruled, after you have created a character, environment, or plot point, you may double click on any element in any of those lists to edit the name of the respective item. This will automatically update the "Name" trait of the Character, Environment, or Plot Point you are editing. When you are editing a specific Character, Environment, or Plot Point, you also edit Traits, Relationships, and Aspirations/Fears by double or single clicking on the elements in the respective lists. When you are editing a value that requires a number, such as a Relationship strength or Trait of the type Number, you can only set the values in the table to number values, or use the up and down arrow within the table row to alter the value incrementally. When a Trait value or Plot Point attribute must be True or False, a visual check box is present to indicate true (Checked) or false (Unchecked). * **Table Selections:** When you are adding new Relationships or Aspiration/Fears to a character, or Relationships to an Environment, you may select more than one item in the list using the "Shift" key. When you click the "Add Selected" button, Wide Ruled will automatically add all of those items to the current Character or Environment. * **File Saving/Loading:** You can save your entire Wide Ruled story environment, including all Characters, Environments, Author Goals, and Plot Fragments using the "Save" command in the "File" menu at the top of the main Wide Ruled window. You can also load any existing Wide Ruled file, with the extension ".WideRuled" into the current window by using the "Open" command in the "File" menu. This will automatically overwrite your current story, so make sure to save it first. If you wish to clear the current story and start from scratch, you can make a new story world by selecting the "New" option in the "File" menu. ===== Basic Story World Objects ===== **Characters** Characters are objects in the world that have three types of attributes: Traits, Relationships, and Aspirations/Fears. You create a character by clicking the "New..." button beneath Character list in the main window of Wide Ruled. Every character is given a name before it is created, and must have this attribute, as a way to identify each one while generating stories. Each of these types of attributes are shown in three separate lists. Traits are sets of attributes that ALL characters must have, and relationships and aspirations/fears are attributes that each character may or may not have. Each trait has a name and a type. **Environments** Environments are objects in the world that have two types of attributes: Traits and Relationships. You create an environment by clicking the "New..." button beneath Environment list in the main window of Wide Ruled. Every environment is given a name before it is created, and must have this attribute, as a way to identify each one while generating stories. Each of these types of attributes are shown in two separate lists. Traits are sets of attributes that ALL environments must have, and relationships are attributes that each character may or may not have. **Plot Points** Plot points are objects that have a single list of values, simply called "Attributes". Every Plot Point has a name Attribute, which is fixed and cannot be altered. When you edit a Plot Fragment in the main window, you are editing the TYPE of data that is stored within one of a specific name. You do not actually set the values within the Plot Fragment. This is because Plot Fragments are objects that do not exist before the story is Generated. They are potential events that occur throughout the generation of the story. Typically, they represent key moments, revelations, or steps that happen in a story, and are used to keep track of progress and save important information, relevant to the particular story being generated. For example, if a Murder mystery story is created with Wide Ruled, the author could use a Plot Point to store the name of the murder, along with other information such as location of the murder, and the number of victims killed. This Plot Point would be created on the fly during generation within a Plot Fragment, and these values would be set and then checked in later plot fragments, to customize the story text and the events that occur. **Traits** Both Characters and Environments have Traits. The types of each trait can be Text, a Number, or a True/False. Depending on what type a Trait is, affects your ability to enter letters and numbers, numbers, or only true or false into the interface, respectively. As mentioned earlier, Traits are attributes that all Characters or Environments must have. All characters share one set of traits, and all Environments share another set. To edit the set of traits and their types, click the "Edit Shared Traits" button under the Trait list in either the Character or Environment editing windows. This button will let you modify the list of shared traits for Characters, or Environments, respectively. When editing the list of shared traits, click the "New" button beneath the current list, which will add a new trait with a default name and type. To edit the name and type, double click on the new item in the list. When you are finished creating, deleting, or editing share traits, click OK and the current character, along with all characters in Wide Ruled, will now have the updated list of shared traits. **Relationships** Characters and Environments have Relationships to other Characters and Environments, respectively. Each Relationship has a name, and stores a reference to another Character or Relationship, as well as a Number value of the strength of this relationship. Creating a Relationship is not a symmetric process. If you add a relationship to Character B while editing Character A, Wide Ruled will NOT automatically add the same relationship to Character B from within Character A. This allows for non symmetric relationships in the story world. **Aspirations/Fears** Aspirations/Fears are simply named elements for Characters, that non-numeric attributes. They can be checked for existence in the Plot Fragment preconditions section. **Author Goals and Plot Fragments** Author Goals and Plot Fragments are the core of the Wide Ruled Story Generation model. Respectively, they represent the arrangement of tasks and the actual tasks that that are performed when creating new stories. Each author goal has a set of associated Plot Fragments. These plot fragments are indented underneath the **bold** text Author Goal names in the Author Goal list in the Main Screen of Wide Ruled. Each Plot Fragment has a set of preconditions that must be fulfilled for it to be activated. When a Plot Fragment is activated, it can do various steps, such as perform and save a calculation, Output text to generate part of a story, add/remove/edit a Character, Plot Fragment, or Environment, and pursue a subgoal, which is another the same Author Goal. If a Plot Fragment chooses to Pursue a Subgoal (Author Goal) within it's set of Steps, the name of this Author Goal to pursue shoes up as //italic// text, indented underneath its Plot Fragment in the Author Goal list in the main window of Wide Ruled. Author Goals can be created by clicking the "New ..." button underneath the Author Goal list on the main window. When creating one, you are requested a required name for the Author Goal, and then you can modify the list of parameters for it. Parameters within author goals are pieces of data that can be passed on, at the time of story generation, to the Goal from a Plot Fragment that is pursuing it. It enables an author to keep track of dynamic information and actively change the process of plot fragment execution. These parameters can be used within a Plot Fragment to test the value of attributes of Characters, Environments, and Plot Points, or alter the text generated for the story. You can edit these Parameter types and names by selecting an Author Goal in its list on the main window and clicking the "Edit ..." button underneath the list. Plot Fragments can be created by clicking the "New .." button underneath the Author Goal list in the main window. You are required to enter a name for a Plot Fragment, and choose an Author Goal for which it will be a child. Once this is complete, you can edit the contents of your newly created Plot Fragment. This editing screen can be accessed by selecting a Plot Fragment from the Author Goal list in the main window and clicking the "Edit ..." button beneath that list. Plot Fragments contain three main sections for editing: Interactivity, Settings, Preconditions, and Steps. The **Interactivity** section is described below, in a later section. The **Settings** section shows the current parent Author Goal for this Plot Fragment, which be changed by clicking the "Change" button, and a list of the Goal parameters that will be sent to this Plot Fragment if it is chosen during the generation of a story. The **Preconditions list** is the list of preconditions that must be satisfied for this Plot Fragment to be available to execute for it's parent Author Goal. You can create a new Precondition by clicking the "New ..." button below this Precondition list. After clicking this button, you will be presented with a wizard that lets you generate a set of tests against the attributes of a Character, Environment, or Plot Point. You can check for the existence or non existence of one of these objects that satisfy the test, and also save any of the attributes of any of these objects to a variable which can be used in other precondition tests, in the Reader prompt in the interactivity section, or later in the Steps section of the Plot Fragment. When you are finished with a single text or saving of an attribute within the Wizard, you can continue to add tests by clicking the "Additional Text ->" button that appears. This allows you to put together a larger series of tests without having them spread out across multiple items in the Precondition list. However, if you save a variable value within a Precondition, it cannot be used later in that same Precondition, but only in other Preconditions in the list. The **Steps list** of the Plot Fragment is a list of actions that a Plot Fragment performs once its Preconditions have been satisfied, and the parent Author Goal has selected this particular Plot Fragment to execute. Here, you can use any of the values from the Author Goal parameters or any of the saved variables from the Precondition section of the Plot Fragment. Beneath this list is a set of actions that you can add to the Steps list. Clicking the "Do Calculation" button allows you to add a step that creates a variable within a Step that is a mathematical combination of two previous variables, two numbers, or a variable and a number. This is often used to increment some saved variable, which is then later stored in a Character, Environment, or Plot Point. You can also click the "Edit Object" button underneath the Steps list to open up a Wizard that lets you Add and Remove new Characters, Environments or Plot Points, and Modify any saved Characters, Environments, or Plot Points which were stored in the parameters or precondition list section of the Plot Fragment. When modifying any of these objects, you can use any variables that have been stored within the Parameters, Preconditions, or other Steps in this plot fragment, assuming they have the same type as the attribute you are modifying. You can also output text for generated story by adding a Text Output step by clicking the "Output Text" button underneath the Steps list. When you click this button, a window pops up that lets you enter any text, as well as insert the value of variables stored in the goal parameters, preconditions, or steps section of this particular Plot Fragment. This allows the generated story text to dynamically change based on the selections of the system. Finally, you can also pursue an Author Goal within a step. You add this kind of step by clicking the "Pursue Subgoal" button underneath the Steps list, which then displays a window of Author Goals from which to choose. After selecting a Subgoal to pursue, you must enter the current Plot Fragment variables that will be passed on as Parameters to the chosen Subgoal, if that Subgoal requires parameters. In both the Precondition and Steps list, you can click the "Move Up" and "Move Down" button to modify the order of the selected Precondition or Step within its respective list. You can also delete any Precondition or Step using the respective "Delete" button underneath either of the lists. Unfortunately, you **cannot at this time edit Preconditions or Steps**. If you wish to change any of these items, you must delete the old one and create a new one. ===== The Wide Ruled Story Generation Model ===== Wide Ruled generates a story in the following manner: - Look at all Author Goals, and for each Author Goal, look at all Plot Fragments - Reject any author goals that require parameters (we have no initial parameters when selecting the first Author Goal) - Test preconditions, in order, for all Plot Fragments of current Author Goal (or all Author Goals if this is the beginning of generation), reject any with one or more preconditions that fail. During this step, the variables that are saved within Preconditions are stored and associated with their Plot Fragment. - If no remaining precondition set of any Plot Fragments are satisfied, stop execution, and undo all changes made to Characters, Environments, and Plot Points, as well as outputted text. This Author Goal now fails. Go back to step 3, and choose a different Plot Fragment for a different Author Goal. - If there is at least one Plot Fragment with satisfied preconditions, randomly choose it or any of the other Plot Fragments with satisfied preconditions. - Execute the steps of the chosen plot fragment, in order. - If one of the steps is to pursue a subgoal, then pass on the parameters from this Plot Fragment to that Author Goal, and look at all Plot Fragments for this subgoal to pursue. Start at step 3 again, except search through Plot Fragments for the subgoal to be pursued. This can be a recursive call. - If the pursued subgoal fails, all changes are undone, and this Plot Fragment fails. Go back to step 3 and find another, different Plot Fragment for the previous Author Goal. - If pursued subgoal does not fail, then all consider this Plot Fragment a success. All changes are made, and any text output is kept in the generated story. - Continue with Plot Fragment Steps until completion, and if there is another Subgoal, go back to step 7 The execution of Wide Ruled is therefore like a Depth-First search through Author Goals, where the selection of the next subgoal is randomly chosen amongst the valid plot fragments with fulfilled preconditions. Whenever a subgoal of a Plot Fragment fails, the entire Plot Fragment is considered a failure, and all steps made before this subgoal are undone. Wide Ruled, after detecting this failure, then goes back to the Author Goal for the Plot Fragment and chooses another valid Plot Fragment, if it exists. If no other Plot Fragments with satisfied preconditions exist, then the entire Author Goal fails. This Author Goal could have also been a subgoal for a previous Plot Fragment, and if this is true, this Author Goal Failure fails the entire previous Plot Fragment. This process repeats, as Wide Ruled backs up the execution tree it has generated on the fly. ===== Interactivity ===== The interactivity section of the Plot Fragment editor lets you select any character in the world, or any character that you have saved to a variable in your preconditions, to act as the "initiator" of this Plot Fragment. This allows Wide Ruled to determine what character is the primary actor in this Plot Fragment, and use this information during the interactive generation process. You can also enter a prompt that will be displayed to a reader as a choice for her to potentially select. This text output can be filled with Author Goal parameters or variables created in the Precondition list. During the generation of a story, Wide Ruled replaces the random choice of Plot Fragments with satisfied preconditions, from step 3 in the previous section, with a human decision. If a reader selects a specific Character to act as during the story, and that character is the initiator chosen within the Plot Fragment editor, then the reader prompt for that Plot Fragment will be displayed as a choice. If multiple plot fragments with different initiator characters have satisfied preconditions for the current Author Goal during execution, and the reader has chosen to be one of those characters, than Wide Ruled will automatically present those Plot Fragments with the same Character initiator first, and if those fail, will only then automatically continue with the other Plot Fragments with different Initiator characters. If a player makes a choice or series of choices during the interaction process that leads Wide Ruled down a set of Plot Fragments that eventually fail, Wide Ruled will back up and could possibly present the same choice dialog again if there is no other path to a successful goal execution. The dialog will be the same, but with one fewer choices available, signifying the loss of a failed plot fragment. This is a feature of the story generation, and one of the ways it can sometimes be at odds with the interaction model present in this system. If the user chooses all of the items in a menu and all of them cause failure, Wide Ruled will back up another time, possibility creating another user dialog with the left-over choices of previous Author Goal executions. This will continue until the top level Author Goal fails, or the story reaches a successful ending. You can select the Character you wish to have a reader play in the "Story" menu on the top of the main window in Wide Ruled. You can also select the level of interactivity, which dictates how often Wide Ruled will, on average, request a reader decision for a Plot Fragment to pursue for the current Author Goal. If you select "All Decisions" from this menu, then all Plot Fragment choices that have the reader Character as an initiator will be displayed, and at no time will Wide Ruled automatically pick one of those Plot Fragments with that reader Character as an initiator. ===== Potential Problems, Slip-ups, or Bugs ===== **Missing data from altered Characters, Environments, Plot Points, or Author Goals** Wide Ruled attempts to only allow Plot Fragments to get attributes from Characters, Environments, Plot Points, or Author Goals that actually exist. Unfortunately, it does not make sure that, after editing the different attributes of Characters, Environments, Plot Points, or Author Goals, that your Plot Fragments are not still trying to access these attributes. Only when creating a new Precondition or Step for a Plot Fragment will Wide Ruled enforce these rules and make sure you are using the proper type of data, such as Numbers for calculation, or proper types for Author Goal parameters. After adding editing the type of value for a Trait, or removing or adding Traits, or changing the parameters of an Author Goal, make sure your Plot Fragments are all up to date before generating a story. Wide Ruled will attempt to catch these errors, but it is not perfect at doing this. This situation of missing data can cause unpredictable story generation results. Preconditions that store Traits will fail if they cannot find the proper Traits that are expected, and if Author Goal parameters are changed, added, or deleted, the preconditions within a plot fragment that rely on those parameters will be checking blank or null data, which can cause unexpected generation results, or errors. ** Wide Ruled giving errors about the Object Edit step trying to set data to a wrong or null type ** Whenever you create any new object (Character, Environment, Plot Point) within a plot fragment step, it creates a new object with any shared traits/attributes that exist WHEN you are creating it in the wizard. So if you change something, like **change the name of a plot point attribute or a character/setting shared trait, add a new shared trait or plot point attribute, or delete any of these two types of things**, Wide Ruled does **NOT** go and find those characters/environments/plot points that you are going to create with the plot fragment and go update them or fix them. This would be a nice feature, but it would require some major changes and additions to the program. (Similarly, it would be nice if Wide Ruled kept track of variables being removed from a plot fragment while they are still being referenced in some other part of it). Because of this, you should do as much of your character/setting/plot point creation before you create fragments, but I know this is not always easy to do. Most importantly, **if you modify the list of shared traits in environments or characters, or modify the list of attributes for a plot fragment, then you need to RECREATE any plot fragment steps that make new instances of these types of objects or does any editing of them**. If you don’t, steps that modify an object might try to assign an incorrect type to a modified trait/attribute, or those dynamically created new objects will not possess these new traits/attributes or these traits/attributes will be of a different type (assuming you changed the type elsewhere). **Duplicate variables within Plot Fragment** When changing the parent Author Goal of a Plot Fragment, or editing the Parameters of an Author Goal, Wide Ruled does not check to see if the parameter name is being used within any Precondition or Step section of a Plot Fragment. If this happens, the parameter coming from the Author Goal will be overwritten by the new variable within the Plot Fragment. This can cause problems, because typically, all variables within a Plot Fragment are supposed to have unique names. Make sure that, after changing the Author Goal or altering the Parameters of an Author Goal, that all of your preconditions and steps are able to still function properly, and do not have duplicate variables being created inside of them. **Missing data from out-of-order execution** Wide Ruled executes a plot fragment by first getting the parameters from the Author Goal, then doing the precondition tests and saving in the order which they appear in the Plot Fragment editor, then, assuming the preconditions are all met, it executes each plot fragment step in the same as order as displayed in the Plot Fragment window. With this order of execution, from a precondition, you cannot access data from a calculation in the Steps section of a plot fragment, because it will not exist yet during the generation of a story. Wide Ruled will ensure that you cannot access Step variables from within a Precondition, but it does not check to make sure that you are not accessing variables in the correct order within a Precondition list or Step list. For example, if a precondition performs a test on a saved name of a Character that is not saved until a later precondition, the value of the saved name will be blank during generation. As a reminder, here is a table displaying the variable access rules: ^ Plot Fragment Component ^ Variables that it can Access ^ | Reader Prompt Text | Goal Parameter Variables, and Any Precondition Variables | | Precondition | Goal Parameter Variables, PREVIOUS Precondition variables (Those that come before it in the precondition list) | | Step | Goal Parameter Variables, All Precondition Variables, PREVIOUS Step variables (Those that come before it in the Steps list) | ** Unexpected Text Output Later in a Story ** A couple of times, while I have been putting together stories in Wide Ruled, I have added a Pursue Subgoal action in a plot fragment, and then added a Display Text action right after this pursuit. Most of the time, this order of operations - first pursue subgoal, then display text, was not what I wanted to happen. My mistake was having these two steps out of order, and the result was some story text appearing at the end or somewhere later in the middle of the story, out of place. Make sure your actions within a plot fragment are in the correct order. Often, pursuing a subgoal can lead to a very complex set of operations which generate a lot of story text, and placing a Display Text action after this pursuit can result a story messages appearing in very unpredictable locations later during story generation. ===== General Debugging Notes ===== By far, the highest potential for bugs in this program, both for the author and for the program itself, is within the story generation process itself. As an author, it involves keeping track of a potentially complex recursive search through goals, and as a program it involves a lot of keeping track of state and undoing of previous actions. **A good way to debug is to take over as a character, set all the plot fragments to that character, and set the interaction level to "All Decisions". Then step carefully through the execution, writing out the execution tree on paper if needed.** Use the reader prompts as well as the text output as useful print statements for debugging, because they can output the values of variables you have saved within Plot Fragments. Another important note is that Wide Ruled outputs very verbose execution information to the command line. If you are running Wide Ruled from the command line, or from the ".bat" file, then you will be able to see a lot of text output there when generating a story. It is not the most user friendly information, but it gives you an idea of what is going on as the generator tries to find satisfied precondition sets, and where it backtracks when backtracking is needed. Take a look at the output if you absolutely cannot figure out what is happening from reader prompts and text outputs. If you do not want to see this output text, or it is slowing down the generation of your story, use the .jar version of Wide Ruled which comes with the release file from the [[Wide Ruled:Wide Ruled Release Files|Release Files Page]]. Finally, in the worst case, save your current Story, and start deleting unnecessary plot fragments to hunt down the source of the problem. It is easiest to figure out what is wrong when you have the fewest number of Plot Fragments and Author Goals possible. Be aware that this program is still a work in progress, so there can still be bugs!!