Shakshuka Man's beginner-friendly tutorial

Basic world creation

This is a tutorial for basic and intermediate world creation and editing. Advanced topics such as triggers are out of scope of this tutorial, but links to more detailed guides will be given.

First steps

Creating a world is easy. All you need to do is to navigate to the world browser (see see here if you don't know how), and then you will see a button that says Create your own adventure:

This will open up a new window, where you will be presented with three choices:

In order to create the world, you will need to specify the art style, the AI model used for creation, and then describe your adventure. The important thing to remember is Don't worry about messing this up - Nothing that you choose here will be permanent, or have hidden side effects.

The world description

For the description, you want to write something that will describe your world and what kind of adventure you want to have in that world. You can be long and detailed, or you can be brief and ambiguous - the AI will fill in any gaps that you leave. In this example, I have been watching a lot of prison movies recently and feel like playing a prison escape adventure, so I use the following for my world description:

This world should be a prison adventure in the 1970s in America. The opening scene should be the player character arriving at the prison for the first day of a very long prison sentence, multiple decades. The win condition is if the player successfully escapes prison.

As this is set in the 1970s, the technology should reflect that era. CCTV camera exist, but are analog, and not recorded. If guards are not actively watching the CCTV feeds, then they will not notice what is going on. The CCTV cameras also only cover communal areas such as corridors and the yard, not individual cells.

This prison is named Blackridge Penitentiary. It is a deeply corrupt place. The guards are sadistic, abusing the prisoners for their own amusement and ego. The administration are greedy, cutting corners and skimming money off the top.

The relationships between the inmates should be complex and varied. Gangs are common, and prisoners who refuse to pick a side will be targeted by all gangs. Prisoners hold grudges, and debts are taken extremely seriously between prisoners. Violence between prisoners is frequent, performative, and often encouraged by the guards.

When parsing this description, the worldbuilding AI does not have the ability to follow links or read from other sources. However, it does have quite a bit of general cultural knowledge that it can use.

The art style

For the art style, you can look here to see what each art style looks like. Pick one that appeals to you the most; in this example I have gone for Manticore pencil drawing.

Once the world is created, you can change between these presets, or you can abandon the presets altogether and come up with your own prompt.

The AI model

The AI model choice is not the AI model that you will be playing with, it is the AI model that will be used to parse your description and build the initial version of your world. Leave this at its default - any world complicated enough that it needs specialized AI to parse its instructions is going to need the world editor to set it up more manually instead.

Building the world

Once all this is done, just hit Build my adventure! to build the world. It will take a few minutes, but once it's done we can go back to the world screen and see the newly created world:

The world is created now. Feel free to play a few turns of it before moving onto the next section.

Seeing what was built

If you edit this world you just created, you will see a menu like this:

You can see that there are five sections here, each of which contains some aspect of this world. When we built the world, the worldbuilding AI took the description as input, and use that to fill out these five sections.

If you want a full breakdown of each of these sections you can look here, but for the purposes of this tutorial I will only cover the most important bits.

Introducing the story

The three most important parts of this section are the background story, the first action and the objective.

The background story is the popup text that appears before you start the first turn of the game, and the first action is what happens in that turn. It can be useful for setting the scene, but it does not affect much beyond the first few turns. As we can see, worldbuilding AI has filled in some of the blanks we left in the initial prompt, giving us things like the name of the warden. If we didn't like what the worldbuilding AI generated, we could edit this to what we want instead.

The objective is one of the most important parts in determining how the storytelling AI generates turns. The AI wants to generate turns that let the player achieve their objective, and it will frequently push the player towards it.

Main instructions

The main instructions block is where the bulk of the world's instructions live. These should contain enough information about the setting for the storytelling AI to be able to generate turns. The majority of changes in how the world functions involve changing the main instructions.

It is possible to create extra instruction blocks (EIB) to organize the instructions. Splitting instructions out into EIBs has no functional effect - all EIBs are combined with the main instructions before being sent to the storytelling AI. The purpose of EIBs is to make it easier for the world developer to organize instructions, or for triggers that edit instructions (more details on that later).

Image style

You can choose a different image style preset, or use your own image instructions. How images work will be explained in more detail later.

Player character options

Each of these options are on the characters the player can choose from at the start of the world. There are two important things to note about these character options. The first is that the description of the character is supplied to the storytelling AI each turn, as if it was part of the main instructions. The second is that the image prompt for the chosen character does not feed into the adventure, it is only used for the image that appears on the character selection screen. If you want to give instructions for the player's appearance, it should be in the main instructions or in the character's description.

You can also set the skills of each character. The skill system is pretty rudimentary, and it is not recommended to try to use it for anything complex.

Victory and defeat

The victory and defeat conditions are optional, and whether or not you want them depends on your world. In this case, our world is all about escaping a prison, and that has a fairly obvious condition where the adventure should end - when the player has escaped from the prison. It would be possible to continue the adventure after escaping from the prison, but as all the instructions are related to the prison, the storytelling AI might struggle to reconcile those with the player being outside the prison.

Optional Features

It is recommended that you familiarize yourself with the basic world editing section above before delving into the optional features.

How things work behind the scenes

To understand how the optional features work, it is important to first understand how turns work in IW. Some of these we have not explained yet, and they will be explained in more detail later. The order of operations in a turn is:

• The player gives an input for the turn they want to generate
• IW assembles a prompt for the storytelling AI by combining the following:
  • The main instructions
  • All Extra Instruction Blocks
  • The character background
  • Any applicable Keyword Instruction Blocks
  • Any applicable NPC details
  • All Tracked Items that are visible to the AI, along with their names and descriptions
  • The author style and description instructions
  • The short term memory and long term memory
• IW sends this prompt to the storytelling AI
• The storytelling AI generates a response that includes the following:
  • The main text of the turn
  • The secret info of the turn
  • Instructions for the image generation AI
  • Which tracked items need to be updated
  • Other fields, which are detailed here
• IW updates tracked items according to their update instructions
• Triggers are evaluated
  • All situations in triggers are evaluated, regardless of if that trigger could fire
  • All triggers are evaluated in order
• An image is generated using the image prompt details
• Update the internal characters database
• The short term memory may get summarized into long term memory

There is a lot going on here, but the most important takeaways are:

• Triggers do not evaluate until the end of the turn, and so can only affect subsequent turns
• If you want to change one of the storytelling AI outputs, this needs to happen in the instructions that get fed to the storytelling AI
• The AI can double down on unintended behavior, as short term memory and instructions are both equally weighted input

Short term and long term memory

An important thing to note here is that there are only three ways that the storytelling AI knows what has happened in the world so far:

• Short term memory
• Long term memory
• Tracked items

Without these three items, the AI has no idea what has happened on previous turns and how to tell a coherent story.

The short term memory is the text of the last 2-8 turns, given exactly as input to the storytelling AI. Starting on turn 8 and every six turns after, the recent history is summarized and added to the long term memory. The AI has to make its decision of what details are important and what details are not. If you have ever noticed the AI getting forgetful, then this is likely a result of the AI and the player not being aligned on what details are worth remembering.

The instructions that the AI uses when summarizing short term memory to long term memory can be edited in the specialist instructions. For this world, I want the details of relationships between the player and NPCs to be important, as well as any progress the player has made towards escaping. Because of this I have set the summarization instructions as such:

Keyword Instruction Blocks

There are situations where you have instructions that you do not always want to input to the AI. This is typically done to keep the credit costs of the world low - instructions are a small part of the credit cost of a world, but they do add a nonzero cost. Keyword instruction blocks (KIBs) are a solution to this.

For a KIB to be applicable to a turn, IW scans the following: - The main text of the last 3 turns - The secret info of the last 3 turns - The player action of the last 3 turns - The player action that prompted the turn that is about to be generated

If any of the keywords a KIB are found, then that KIB is determined to be inscope for the turn, and it is part of the input to the storytelling AI.

It is important to note that KIBs cannot be fed to the storytelling AI partway through generating a turn. Because of this, it is important the main instructions contain enough information for the AI to be able to write a turn, and then the KIB can contain any extra instructions needed for follow-up turns.

In this example world, I want one of the escape routes to be through the prison's sewers, in the style of The Shawshank Redemption. I want to come up with some detailed descriptions of how the player can escape through the sewers, but I don't want it to feed it into the instructions every turn, so I create a KIB with the full details and an EIB with enough details for the AI to get through a single turn:

Other characters

There is an important distinction to be made here between the characters database, and the Other characters section of the world design.

The characters database is part of the current state of any adventure in IW. It contains details on every character that IW considers important. It does not exist in the design of the world, it is only created when an adventure starts in that world. It is currently not possible to view or directly edit the contents of the characters database of an in-progress adventure.

The Other characters portion of a world design is used to pre-populate the characters database when an adventure is started. After this is done, the characters listed are never used again.

As the adventure progresses, the characters database is updated and new characters will be added if they become important.

The purpose of adding characters to the Other characters section is to make sure that the character appears as the world designer intends. For this example, as the world designer, I want to ensure that the prison warden is a nepotism appointment and the prison chaplain is kind, so I can create entries for these two:

It can be useful to think of an entry in Other Character as a combination of a KIB and an EIB. The Brief summary of that character is always given to the AI, just like an EIB. The rest of the details of that character are only given to the AI when that character's name or location is in the recent turns.

Tracked items

Tracked items are an alternative to using short term memory/long term memory to track things that have happened in the adventure.

One of the weaknesses of the storytelling AI is that is is bad at numbers. It will give very inconsistent quantities for numbers, especially when things drop out of short term memory. In this world we want the player to be able to earn money through prison labor, and we want to be able to track money, so we will create a tracked item to track this:

This section only covers the basic applications of tracked items. Items to track gives a much more thorough and detailed explanation of how tracked items work and how they can be used for complex logic.

Trigger events

Trigger events are a more advanced feature, and are out scope of this tutorial. A more detailed guide is available here.

Common issues

These are common issues that world creators frequently encounter, and how to fix them.

The AI is forgetting important details

The AI has three ways of getting information about what has happened previously in the adventure:

• The short term memory (the exact text of the last 2-8 turns)
• The long term memory (built up by summarizing the short term memory every 6 turns)
• Any tracked items or instructions that the world designer has set up

If the AI starts forgetting important information, then this is because when the AI summarizes the short term memory into long term memory, it has cut some details that it considers unimportant, but the player considers important. There are three ways to fix this:

• Update the summarization instructions so the summarization process always includes important details
• Use a tracked item to track which important events have happened
• Use the trigger system to update instruction blocks

My trigger isn't firing

A very common pattern for new developers is to try to set up a trigger like this:

• Trigger on situation: I enter the kitchen
• Tell the AI what should happen: I find a bowl of cereal

The intention of the develop is that if the character enters the kitchen, they want them to find a bowl of cereal. However, when they play the world and go to the kitchen, there is no bowl of cereal found.

This is because of the order of operations. The Storytelling AI will generate a turn in its entirety, and only at the end of that turn will it evaluate the trigger situations and fire this trigger. Then, when generating the next turn, it will try to work in the player finding a bowl of cereal.

The solution to this is to have an EIB that contains the text Whenever I enter the kitchen, I find a bowl of cereal. This EIB can then be affected by triggers, if you want the player to only encounter a bowl of cereal under certain circumstances, then this EIB can be controlled by triggers.

Why are my changes not having any effect?

There are a few potential reasons why a change could not have an effect, or appear to not have an effect.

When you start playing a world, IW creates a copy of that that world, and runs your adventure using that copy. You can edit the definition of the in-progress world, but it will not affect the base copy of the world, and vice versa.

If a trigger updates the main instructions, or an EIB, then it does not show in the world definition. Instead, it creates an invisible patch that gets applied to the prompt before it gets sent to the storytelling AI.

Changes made to the Other Characters section will not affect an in-progress world. The Other Characters section is only used by IW once, at the start of the adventure, to pre-populate the characters database. After the adventure starts, the Other Characters section is not used and changes have no effect.

Why is the AI not following my instructions?

The storytelling AI prompt receives input from a lot of different sources, and these sources can disagree with each other. These can include:

• Short and long term memory
• The instruction blocks of the world
• Built-in instructions that IW always provides
• Character info from the character database

If these inputs disagree with each other, then the AI has to try to resolve this, and that normally involves deciding which instructions to ignore, and which instructions follow. As a worldbuilder, you can try to emphasize your instructions, but it is not completely reliable.

Common ways that this conflict can occur are:

• IW includes a lot of built-in prompts. For example, it wants to always ensure that when a character is introduced, the player is always told their name. If a world builder wants to keep the name of a character secret, then this will clash with the built-in prompt
• If a turn generates something that a player dislikes and they edit the world to remedy it, then they will need to revert to an earlier turn or use storyteller mode to also edit the existing turn. Otherwise, the incorrect detail will be included in short term memory (and later long term memory), and it will clash with thew new instructions.

Why is the AI so bad at pacing events?

There are two underlying causes of this.

The first is that keeping track of time is a known issue with many AIs. There is a more detailed page on it here, including instructions for how to fix AI time tracking issues.

The second is how short term memory works. Here is a common situation:

• The player is having a conversation with another character
• This other character has a cold in its early stages
• In the secret info, the AI is noting that the cold is fine now, but will get worse in time if untreated
• The short term memory is summarized and cut off to the last two turns, meaning the start of the conversation is no longer part of the short term memory
• The storytelling AI has no idea how long the conversation has lasted. It sees that there the cold should progress, but does not see any progress in the short term memory
• The storytelling AI decides it needs to advance this plot thread
• Over the course of a single conversation, the character goes from having a mild cold to dying of pneumonia

Unfortunately, there are no great solutions for this issue, this is still something that is being worked on.

How are my turn costs determined?

If you look at your credit balance, you can get a breakdown of your recent credit expenditure, and for teach recent turn you can get a breakdown of exactly what where the credits are going.

• The instructions section increases approximately linearly with the word count in the main instructions and extra instruction blocks.
• The input cost of a tracked item includes the name, description and update instructions of all tracked items that are visible to the AI.
• The short term memory increases each turn, until summarization happens (turn 8 and every 6 turns after that), when it will drop sharply.
• Long term memory increases slowly over the course of an adventure. How much it increases by depends on the summarization instructions.
• The output cost of a tracked item only applies if that item is updated according to its update instructions. If it is updated, then it is fully rewritten and the output cost is the cost of fully rewriting it.
• All inputs have the same credit cost per word, and all outputs have the same credit cost per word. The cost of a word of output is 5-10 times the cost of a word of input.