Usage Guide (Runtime & Build)
Runtime usage.
Most Narrative Designer components are intended for Editor work and are not included in the build. However, the system supports converting all data into a compact JSON file for further runtime use. You can also access media files stored in ND scriptable objects at runtime.
See Narative Demo scene → NarrativeDesignerRuntimeAPI → Run Usage Examples as example.
Setup
Add the NarrativeDesignerRuntimeAPI.prefab to the scene with Narrative Designer Menu.
Assign a reference to the Narrative Designer Menu on the scene in Menu.
In Narrative Designer Menu, click Save All Data as JSON to save all system data to a file for runtime reading.
When the API component is connected to the Menu and json file containing current system data, it's easy to extract any information from it. Various usage examples are available inside the NarrativeDesignerRuntimeAPI → ExampleUsage() method.
Runtime Usage (Script part)
Globally 2 things allowed: select events and read data. Editing ND data at runtime is not supported.
Allows to assign the Current Selected Event at runtime with persistence between sessions.
Allows to read any data from the database without modifying it.
Once selected, the current event is saved to a separate json file on the player`s device via SaveSelectedEventToFile(). At Start, the current event is assigned from the memory via LoadCurrentSelectedEvent(). The current event is saved until another one is selected.
Using current event data at runtime, control NPC routes, music, generally use event as a reference point for writing the rest of the logic.
For extracting basic data types like string, int, float, the JSON file from the menu is used. F.e. extract the positions of points on the current event's board. For extracting media data like images or sounds, direct references to the system's scriptable objects are used. F.e., to extract the current event's illustration from the database or a character's gallery from Character Brain.
In runtime, use a reference like NarrativeDesignerRuntimeAPI dataInserter; and call the methods from the table through it. For example:
public class YourGameController : MonoBehaviour
{
public NarrativeDesignerRuntimeAPI dataInserter; // API reference
void Start()
{
// Get basic game info
string gameTitle = dataInserter.GetGameTitle();
// Select an event by index and get its data
dataInserter.SelectEvent(3);
string eventDescription = dataInserter.GetCurrentEventDescription();
// Check character state by name
float playerState = dataInserter.GetCharacterCurrentState("Player");
// Get media assets
List<AudioClip> sounds = dataInserter.GetSoundLibrary();
Texture2D eventImage = dataInserter.GetCurrentEventIllustration();
}
}Runtime Usage (Event Selectors part)
The system supports selectors that allow to assign one or multiple events for subsequent selection independent of timeline positions (GUID-based approach). All operations with selectors occur within the same component NarrativeDesignerRuntimeAPI.
Method Call Examples
Event Selection
Is possible in 2 ways: by sequence number in the list or using a selector, independent of the order or deletion of events in the timeline. Selectors can be created in the editor within the same NarrativeDesignerRuntimeAPI component and accessed by name or sequential index.
bool success = SelectEvent(eventIndex);
Select event by timeline position
JSON file (Global Events Array)
Progress story based on player choices
var selector = GetSelectorByIndex(0);
Get event selector by index
Component (Event Selectors List)
Organize events into categories for gameplay
var selector = GetSelectorByName("Event Selector 1");
Get event selector by name
Component (Event Selectors List)
Organize events into categories for gameplay
bool success = SelectFirstFromSelector(selector);
Select first or single event from selector
Component + JSON (Event Selector)
Progress story based on player choices
bool success = SelectRandomFromSelector(selector);
Select random event from selector
Component + JSON (Event Selector)
Add randomness to encounters or events
bool success = SelectBestEventForCharacter(selector, "Sorh");
Select event with most positive effect for character
Component + JSON (Event Selector)
Event selection based on character benefit
ClearEventSelection();
Clear current event selection
Runtime State
Reset to neutral state or main menu
bool hasEvent = HasSelectedEvent();
Check if any event is currently selected
Runtime State
Conditional logic for event-based features
Data Reading
string gameTitle = GetGameTitle();
Get game title from global context
JSON file (Global Context)
Display game name in UI or save files
int eventCount = GetEventCount();
Get total number of events in database
JSON file (Global Events Array)
Show progress or validate event indices
List<AudioClip> allSounds = GetSoundLibrary();
Get all sounds from library
Scriptable Object (Global Context)
Switch background music based on scene
List<Texture2D> allImages = GetDesignGallery();
Get all images from gallery
Scriptable Object (Global Context)
Random environment decorations
Texture2D boardTexture = GetBoardBackgroundTexture();
Get board background texture
Scriptable Object (Character Database)
Set scene background for character interactions
List<Texture2D> playerImages = GetCharacterImageGallery("Vitazis");
Get images for specific character
Scriptable Object (Character Brain)
Character portraits, expressions, customization
string relation = GetCharacterRelation("Player", "Sineid");
Get relation between two characters
JSON file (Character Relations)
Adjust dialogue tone or unlock special interactions
string description = GetCurrentEventDescription();
Get current event description
JSON file (Selected Event)
Display event narrative text
Texture2D eventTexture = GetCurrentEventIllustration();
Get current event image
Scriptable Object (Global Event)
Show event illustration in UI
bool knows = DoesCharacterKnowCurrentEvent("Player");
Check if character knows about current event
JSON file (Character Memory)
Filter dialogue options or reactions
float effect = GetCurrentEventCharacterStateChange("Player");
Get character's numeric effect from event
JSON file (Character Effects)
Calculate reputation or relationship changes
string impact = GetCurrentEventCharacterImpact("Player");
Get character's text impact description
JSON file (Character Effects)
Show detailed consequences in text
var eventData = GetCharacterEventData("Player");
Get complete character event data
JSON file (Character State Events)
Access before/after states and impact details
Vector2 boardPos = GetCharacterPositionOnEventBoard("Citrakis");
Get character position on event board
JSON file (Event Board Positions)
Position characters in tactical or visual layouts
Color boardColor = GetCharacterColorOnEventBoard("Citrakis");
Get character color on event board
JSON file (Event Board Positions)
Color-code characters by faction or status
float boardSize = GetCharacterSizeOnEventBoard("Citrakis");
Get character size on event board
JSON file (Event Board Positions)
Scale character importance or influence visually
string closestCharacter = GetClosestCharacterOnBoard("Citrakis");
Find closest character on board
JSON file (Event Board Positions)
Trigger proximity-based interactions
float distance = GetDistanceBetweenCharactersOnBoard("char1", "char2");
Calculate distance between characters
JSON file (Event Board Positions)
Range-based gameplay mechanics
float playerState = GetCharacterCurrentState("Player");
Get character's current state value
JSON file (Character State)
Conditional content based on character condition
var affectedCharacters = GetCurrentEventAffectedCharacters();
Get all characters affected by current event
JSON file (Character Effects)
Show group consequences or party dynamics
List<string> charactersOnBoard = GetCharactersOnBoard();
Get all characters positioned on current board
JSON file (Event Board Positions)
Initialize tactical scenarios or social scenes
bool isOnBoard = IsCharacterOnBoard("characterName");
Check if character is on current board
JSON file (Event Board Positions)
Include/exclude characters from board-based mechanics
List<string> nearby = GetCharactersNearby("Player", 0.3f);
Get characters within distance from target
JSON file (Event Board Positions)
Trigger area-of-effect events or conversations
Last updated