Conversationalist, A Tutorial

Discussion in 'Ink NPC Dialogue Composition' started by Merrik, Apr 21, 2020.

Thread Status:
Not open for further replies.
  1. Merrik

    Merrik Bug Hunter

    Messages:
    188
    Likes Received:
    354
    Trophy Points:
    30
    Gender:
    Male
    Location:
    Elysium
    Lesson One: What is a Conversationalist NPC?

    It is a "Programmable" NPC that has the ability to use an Inkle dialogue script applied to it by the player. In this tutorial we will show how to use the Inkle language to add custom dialogue to your NPC.

    You can find the Conversationalists in the Crown Shop for between 1000 and 2000 crowns.
    There are many Conversationalists in the crown store (under Adventure Design/Custom Characters), There are a couple you can craft, and some players got one with their pledge or through rewards.

    In this Post, we are going to get you started programming your Conversationalist NPC with as little fuss as possible. We will start with the basics to get you going, and then cover a few more things in a bit more detail.

    All of the advanced features of Inkle scripting are not implemented in SotA. More of the advanced functions will have to be added as improvements over time. All of the methods and functions discussed here are fully operational in SotA.

    Now to the question of "where does My Conversationalist NPC live?" S/He lives in your SotA data folder which can be found by going into the game and typing "/datafolder" in the chat box (this will open the folder on your computer) and then opening the "Custom NPC" folder. This is where you will place your dialogue scripts. Make a note of the folder location.

    Use your favorite text editor to create a test dialogue script and add the following into the editor:

    Our very first dialogue script:
    Code:
    ->START
    ==START
    Hello!
    ->END
    
    Once this text is in the editor, save it (using text file format) in the folder location and name it after your NPC or in some descriptive manner for what the dialogue is used for and use the extension ".ink". For example, I named mine "helloWorld.ink".

    NOTE: this is the absolute bare minimum you can have for a functioning Conversationalist. (We will explain those parts in a bit)

    Save the file and go to your Conversationalist NPC in game and right click it in your inventory or bank. (NOTE: The NPC dialogue can not be changed while the NPC is placed in the game world.)
    Now, when you right click the NPC, you will get the option to "Edit Dialogue" and at the bottom of the next window will be "Import Content". click this and select the file for your NPC (in this case helloWorld.ink)

    Finally, place your NPC (at this point you can right click and rename the NPC if you like, I think I'll call mine "Henry") and VIOLA! your very own walking talking Buddy!
    [​IMG]
    Now at this point Henry is a bit Dull... We will fix that as we move forward.
     
    Last edited: May 31, 2023
  2. Merrik

    Merrik Bug Hunter

    Messages:
    188
    Likes Received:
    354
    Trophy Points:
    30
    Gender:
    Male
    Location:
    Elysium
    Lesson Two: The Basics

    Let me start by saying Inkle dialogue scripting can get a LOT more complicated than this. You can nest choices and all kinds of neat Code Sorcery like that. However, please remember there is a character limit in SotA's implementation of Inkle so you don't want all the indents and extra non-necessary characters that make it look pretty.

    The limits are, 2000 characters for the pledge and craftable Conversationalist, and 20000 for the in-game Crown Shop Conversationalist. This includes special characters like spaces, tabs, and CR/LF (Carriage Return and Linefeed)

    For Example, In Lesson One, the dialogue is 25 visible characters (including spaces), but 31 characters total including the Carriage Return/LineFeeds (CR/LF) from using a Windows editor. CR/LF is two characters for each line. You can reduce the number of characters used if your editor can do Linux formatting (which instead of using CR/LF, only uses LF). This is why you don't want to get all pretty with tabs, indents and such, as you will run out of characters pretty fast.

    The reason for the character limit in SotA is because each time you engage an NPC it loads the dialogue from the server to your PC and this creates a load delay. The longer the text, the longer the delay.

    So, instead of using all the pretty indents and spacing, What I use here is the most basic, and is all you need for dialogue scripting your NPC in SotA.

    NOTE: In our examples the Labels are all in CAPS to make it easier to see them. You do not need to use capitals when actually writing the dialogue scripts.


    Let's add an option to the dialogue:
    Code:
    This is a test script.
    ->START
    ==START
    Welcome to the Beginning
    +Hello World
    ->A
    +Good Bye
    ->B
    ==A
    Why hello!
    ->START
    ==B
    ->END
    

    NOTE: In the lesson descriptions, commands are in BLUE, Labels are in YELLOW and Terms are italicized.

    • The first line is the greeting. Generally this is used for setting up the mood of your dialogue.
      Since it is before any commands, in this case before the "->START" line, you will only see it when you start talking to the NPC
    • The "->" is called a Divert command, think of it as saying "go to" and START is the Label (destination)
    • The "==START" is called a Knot, and the "==" must not have a space between them. This is where the START Divert command is going to.
    • Both Divert and Knot commands have to be single words, or words separated with an underscore "_" such as: "==my_function"
    • The "+" is a Choice Bullet command. You can make as many of these as you need for the choices the reader will make.
    • The dialogue script must have a "->START" and "->END" command. Everything between these two commands is the dialogue script Loop.

    For example, in our helloWorld.ink we start with:
    Code:
    This is a test script.
    ->START
    ==START
    Welcome to the Beginning
    +Hello World
    ->A
    
    [​IMG]
    • The First line is a Greeting followed by a Divert and the first Knot which is the start of the dialogue
    • The next line after the "==START" Label is a text header with options that will display each time we are diverted to start (->START)
    • The first choice is "Hello World" and when you click it, it will use the Divert "->A" to take you to the Knot Label "==A" (Go to A)

    Now lets look at where the Divert takes you:
    Code:
    ==A
    Why hello!
    ->START
    
    [​IMG]

    • The "==A" Knot and Label tells the script "hey this is where I wanted to go if they click "Hello World"
    • Since the next line in the dialogue script is "->", the script Diverts you back to the start using "->START"
    • So basically you have a Greeting, a "->START", and an "->END" and everything else goes between the "->START" and "->END" from there you add the rest using the same principle


      NOTE: The line "This is a test script" will only display when the player initially engages the NPC. Since this is not part of our "dialogue loop" it will not be shown again even if the conversation returns to the beginning.

      At this point you have EVERYTHING you need to make a fully interactive NPC
      Now the fun part!! Import this to your NPC and test it out to see how it all works in real time.

      In Lesson Three we will talk about one point in particular ... Choice Bullets
     
    Last edited: May 31, 2023
    Womby, Time Lord, Xithar and 10 others like this.
  3. Merrik

    Merrik Bug Hunter

    Messages:
    188
    Likes Received:
    354
    Trophy Points:
    30
    Gender:
    Male
    Location:
    Elysium
    Lesson Three: Options!

    We've been using + as Choice Bullets, however, you can also use the * instead if you want the choice to never re-appear once it's been chosen. This is great for when you want to create an option that is a one way trip.


    Code:
    This is a test script.
    ->START
    ==START
    Welcome to the Beginning
    *Hello World
    ->A
    +Good Bye
    ->B
    ==A
    Why hello!
    ->START
    ==B
    See Ya Later!!!! o/
    ->END
    
    [​IMG]

    As you see here, we have "Hello world" and "Goodbye" and as "Helo World" is a * choice,
    click it...

    [​IMG]

    and it goes away leaving "good bye" as the only choice left
    so we click it and...

    [​IMG]


    What have we learned?

    We've learned about the basic structure, Greetings, Diverts and even Choices that go away. Now, why not experiment with your Conversational NPC? Try inserting extra text, Choice Bullets, Diverts, ending options, and see what happens!
    As an exercise, look at the following screenshots and see if you can duplicate this with the knowledge you have learned!


    [Greeting output]
    [​IMG]

    [Click: What is your Name]
    [​IMG]

    [Click: I am on a quest]
    [​IMG]

    [Click: Coconuts]
    [​IMG]

    In Lesson Four we will get into more advanced options like Nesting.
     
Thread Status:
Not open for further replies.