Translators: Story API - UA-ScriptEase/scriptease GitHub Wiki

Implementing the Story System will usually require the translator writer to add their own code to the module in the form of include files. These should be added in the addIncludeFiles method, and will likely not be ScriptEase generated.

Story Points have five states: Presucceeded, Succeeded, Enabled, Disabled, and Failed.

Presucceeded happens when you succeed a story point before it's enabled. This causes the story point to automatically succeed when it is enabled. For example, think of a quest with a dragon. If you kill the dragon before getting the quest from the quest giver, you can accept and then it automatically succeeds. This is a shoddy example, since you should have the dialogue option to say "I already killed it," but let's ignore good game design for the sake of this example. The rest of the states are self-explanatory.

"Descendants" refers to a story point's children, it's children's children, and so on. "Ancestors" refers to the same for parents.

To add the full functionality of the story system, we need a few basic functions that will be called:

Setup:

  • RegisterRoot: This registers the starting Story Point
  • RegisterChild: This registers a child of the Story Point. A combination of this and RegisterRoot is used to populate the story. Make sure to check if the Child already exists, as Story Points may have multiple parents.

Setters:

  • SucceedStoryPoint: Sets a Story Point and all of its ancestors to succeeded.
  • ContinueAtStoryPoint: Sets a Story Point to Enabled and all of its descendants to Disabled.
  • FailStoryPoint: Sets a Story Point and all of its descendants to failed.

Getters:

  • HasSucceeded: Returns true if story point's state is set to succeeded.
  • IsEnabled: Returns true if story point's state is set to enabled.
  • HasFailed: Returns true if story point's state is set to failed. The initialization of the story system, i.e. adding the story points, should occur right when the game is launched on an "automatic" script that is invisible to the designer.

Generally, you will use the "Unique Name" of a Story Point to identify it, as story points can have the same display name.

Note that the Neverwinter NIghts translator is much more confusing than this because Neverwinter Nights does not support collections or data structures. We may want to refactor it later.