Narrative Engine Documentation

This document provides a comprehensive guide to the narrative engine syntax and features.

Basic Syntax

The narrative engine uses a custom syntax to define interactive stories. Each line in a .nar file is processed sequentially unless flow control commands redirect execution.

Comments

Use the # symbol for comments. Anything after # on a line is ignored.

# This is a comment
@scene forest # This sets the scene to forest

Line Processing

Each line is processed in order. The engine pauses at dialogue lines until the player presses space to continue.

Scene Management

Defining Scenes

Scenes help organize your narrative into logical sections.

@scene forest

Jumping to Scenes

You can jump to a specific scene using:

>scene:forest

Tags

Tags are named locations in your script that you can jump to. Define a tag with a less-than symbol followed by a space and the tag name:

< forest_entrance
[Guide] We've arrived at the forest entrance.

# Jump to the tag
>forest_entrance

Dialogue

Basic Dialogue

Dialogue is defined with a character name in square brackets followed by the text.

[Character] This is what the character says.

The engine will pause after displaying dialogue until the player presses space.

Choices and Branching

Presenting Choices

You can present choices to the player using the @choice tag followed by options.

@choice
"Yes, I'll help you." >help_path
"No, I'm busy." >refuse_path

Each choice consists of the text in quotes followed by > and the destination tag.

Handling Choice Results

Define tags for each choice outcome:

< help_path
[Character] Thank you for your help!

< refuse_path
[Character] I understand. Maybe next time.

Variables

Defining Variables

Variables store information that can change during the story.

${player_name} = John
${gold} = 50
${has_sword} = true

Using Variables in Text

Reference variables in dialogue or choices:

[Merchant] Hello, ${player_name}! You have ${gold} gold coins.

Conditional Logic

If Statements

Control flow based on conditions:

if ${gold} = 50
    [Merchant] You have exactly 50 gold coins!
else
    [Merchant] You don't have 50 gold coins.

Condition Operators

Supported operators include:

• = – Equality check
• and – Logical AND
• or – Logical OR
• not – Logical NOT

Background Images

Setting Backgrounds

Change the background image:

@background forest.png

Background Transitions

Add smooth transitions between backgrounds:

@background beach.png transition:true

Actor System

Creating Actors

Add characters to your scene:

@actor character_id, sprite_filename.png, x_position, y_position, depth

Example:

@actor hero, hero_neutral.png, 300, 400, 10

Removing Actors

Remove an actor from the scene:

@remove_actor hero

Changing Actor Sprites

Change an actor’s appearance:

@change_sprite hero, hero_happy.png

Animating Actors

Apply animations to actors:

@animate hero, slide_in_right
@animate villain, shake, wait

The optional “wait” parameter pauses the narrative until the animation completes.

Available Animations

Metadata

Adding Metadata

Include metadata about your story:

{start_meta}
{title} My Adventure Story
{author} Jane Doe
{version} 1.0
{description} An exciting adventure in a fantasy world.
{end_meta}

File Structure

Narrative Files

Narrative files use the .nar extension and contain the story script.

Resource Organization

Organize resources in these directories relative to your .nar file:

• /res/img/background/ – Background images
• /res/img/actors/ – Actor sprites

Complete Example

# My Adventure Story

{start_meta}
{title} Forest Adventure
{author} Game Developer
{version} 1.0
{description} A short adventure in an enchanted forest.
{end_meta}

@scene intro
@background forest_entrance.png

# Create our main characters
@actor hero, hero_neutral.png, 300, 400, 10
@animate hero, slide_in_right, wait

[Narrator] You find yourself at the entrance to an ancient forest.

@actor guide, guide_smiling.png, 500, 400, 15
@animate guide, slide_in_left, wait

[Guide] Welcome, traveler! I can show you around this forest.

@choice
"Yes, please lead the way." >follow_guide
"No thanks, I'll explore on my own." >solo_path

< follow_guide
${has_guide} = true
@change_sprite guide, guide_happy.png
@animate guide, bounce

[Guide] Excellent! Follow me, and stay close.
@background deep_forest.png transition:true

>forest_exploration

< solo_path
${has_guide} = false
@change_sprite guide, guide_disappointed.png

[Guide] As you wish. Be careful in there!
@animate guide, slide_out_left, wait
@remove_actor guide

@background deep_forest.png transition:true
[Narrator] You venture into the forest alone.

>forest_exploration

< forest_exploration
[Narrator] The forest is dense with ancient trees.

if ${has_guide} = true
    @actor guide, guide_neutral.png, 500, 400, 15
    [Guide] Watch out for that branch!
    @animate hero, shake
    [Hero] Thanks for the warning!
else
    [Narrator] A branch hits you in the face.
    @animate hero, shake
    [Hero] Ouch! I should have brought a guide.