Modders to guide making custom stories

### The basics ###

Just like in writing in general, a story in KEE consists of a number of beats.

Every beat represents some kind of significant event that happens to drive
the story forward.

Once there are stories, they need to be randomly put into the approriate circumstances.
This is handled via a system of randomizers. You can write your own randomizer in
Lua and attach it to the Story manager via the KnoxEventStoryAPI.

The Story manager will randomly pick a story randomizer every time an event
occurs and let it generate a random story based on the circumstances.

### NpcStory ###
The NpcStory class consists of four functions used by the Story Manager.

The start function initializes the story and sets the npcs to "in a story",
so that the game knows that the AI knows not to pursue long-term goals.

The isActive function is simply a utility that tells the game whether a story
is still running.

The update function runs every tick of the story. This can be passed to a story beat
so that it knows how far it has progressed.

The onComplete function runs once the story is finished.

### NpcStory in Java ###
Once the default NpcStory class runs, the Story Manager will call start.

The affected actors/npcs are put in "story mode" i.e. the AI will run the basic
survival loop, but not purpuse other goals e.g. scavenging, cleaning etc.

Finally, it will call update on the first StoryBeat attached to the story.

From here, the story is periodically updated via the Story Manager. The NpcStory
class will continously update the current beat until it is finished. After that,
it moves on to the next beat.

### NpcStoryBeat in Java ###
The NpcStoryBeat calls represents a beat in the story and consists of two abstract
functions to implement, onUpdate and onComplete, and two base functions, update and
isComplete.

The update function is called from NpcStory and drives the story forward. When
constructing a NpcStoryBeat, you also say how long a the beat is, expressed in
seconds. The update function will keep track of this while continously calling
the onUpdate function.

Once the full time has elapsed, it will mark itself as complete, so that NpcStory
can see this by calling isComplete, and also call the onComplete function.

### NpcLuaStory ###
The NpcLuaStory class is a subclass of the NpcStory class. It allows you to provide
a Lua table implementing the functions: start, isActive, update, and onComplete.

Aside from calling the Lua equivalent, the start function and the onComplete function
will still handle marking of npcs i.e. you don't need to worry about the npcs all
of a sudden begin cleaning mid conversation.

With this, you have full control over what happens in the story and you are responsible
for driving it forward.

### NpcLuaStoryBeat ###
The NpcLuaStoryBeat class is a little bit simpler than the NpcLuaStory class in
the sense that it gives you a bit less control over the state. This is intended
and I hope this will become clear once you see the common use cases later in this
guide.

Similarly to NpcLuaStory, you construct this class by giving a Lua table, as well
as a total time expressed in seconds.

The Lua table allows you to override the functions onUpdate and onComplete. These
are simply callbacks, so you only need to keep track of which npcs are in the beat
and what they should do.

### Some common setups ###
Aside from these classes, there are some common use-cases that can be solved via
"off the shelf" story beats.

NpcApproachStoryBeat - Lets a npc approach another npc.
NpcSpeakingStoryBeat - Lets a npc speak to another npc.

With this, you can implement something like TwoNpcsChatStory.

In this story, we use the fact that
