help/Basic Guide

Introduction

If you ever played a modern RPG like Dragon Age or The Witcher (I had to mention that one ;) ), you should recognize the NPC dialogue system, where you have to choose from several possible options, what exactly do you want to say. Depending on the game, your choice may affect further storyline, the way other characters see you or lead to getting some secret information and begin some kind of side quest. Of course, the usage could be also more trivial - like picking the topic for small talk or asking the smith if he wouldn't mind fixing your stuff. The possibilites are countless - it's only about the dialogue writer's creativity. For sure, there are also technical limitations, but the plugin is being constanly developed and I will probably add any requested (and reasonable) features, if you ask politely. Also, it's not so hard to extend NPGuys to for your own needs - read more in API Guide (coming soon).

Configuration

First start-up

So, you have installed NPGuys and all the dependencies, now what? You probably want to start fun straghtaway and play with what the plugin has to offer. What do you need to know at first is that every NPGuys' NPC has his own file that stores something like his "identity" - basically, it contains every dialogue line that can be ever used in conversation with that NPC. So, let's create one with command:

/npguy Bob create

You have now an NPGuy named Bob! At this point, you should learn that it doesn't matter how do you name your NPGuy - it won't really be displayed anywhere and it's only usage is to be easier to remember for you than ID or anything like that. OK, now we have to attach that data to an actual NPC. Let's say we have just created Citizen with ID 0. Firstly, we have to give him a special NPGuy trait:

/trait npguy

Then we perform the attachment:

/npguy Bob attach 0

And voila! Now you should be able to start a conversation with the NPC by right-clicking him and see a short default dialogue. By default, you change your response by right-click and confirm it by left-click. Notice, that NPC name, displayed in the dialogues is in fact the name of certain Citizens' NPC. As I said before, NPGuy name doesn't matter. Protip: If you want more insta-fun, you can skip next section and go right to Dialogue system.

Config.yml reference

Warning: This is a bit outdated, please compare with the actual config. I will try to update the guide soon.

Without unnecessary delay, let's just look into config file!

conversation:
  distance: 5.0

That one is easy. It's just the maximum distance for conversating. If we move too far from NPC we are talking to, the conversation will be automatically abandoned.

ui:
  default: "SCOREBOARD"

The plugin's idea was to be fully customizable in all possible ways, so there are (well maybe not yet, but there will be in the future) many types of conversation UIs. What we can see up there is the name of UI type all the user's will use.

  configs:

Here starts the section, where every registered UI type (also the external ones, created with API) can store it's own piece of data.

    scoreboard:
      headline: "Your answer"

Headline is the text that will appear at the top of response list (displayed in scoreboard, in this case).

      npc:
        message_format: "&9[&6NPGuys&9] %npc: &r%msg"

You can make the message, that displays in chat, look however you like. Note that there are 3 variables that will be replaced in-game: %npc is NPC name, %player is player name and %msg is... well, the message itself.

        delay: 20

NPC response, displayed immediately under the message "sent" by player, would look a bit unnanural. Delay (in server ticks) is just time difference between these two.

      player:
        message_format: "&9[&6NPGuys&9] %player: &r%msg"

Similar to npc.message_format, but reffers to what does the player say.

dialogues:
  default:

That's default dialogue that is attached when NPGuy is created (by command). Read more in Dialogue system section.

  exit:

And that's the default dialogue for quitting conversation (it's displayed only when there is no other possible responses).

Dialogue system

OK, now let's go back to our friend, Bob. Althought he showed us how amazing do conversations look like in NPGuys, he didn't really tell us anything interesting. It's time to learn him some tricks.

General structure

Every conversation in NPGuys is divided into small parts, called just dialogues, which are stored separately for each NPGuy. Example file with dialogues could look like this:

welcome_message: "hello"
dialogues:
  hello:
    shortcut: "Hello"
    message: "Hello, %npc. My name is %player."
    requirements: {}
    actions: {}
    npc_response:
      message: "%player, %player... Oh yeah, I remember you! By the way, this plugin is awesome, isn't it?"
      possible_responses:
      - perms1
      - perms2
      - bye
  perms1:
    shortcut: "Gimmie perms"
    message: "Of course it is. Now, please give me the permission I don't need to anything."
    requirements:
      '0':
        type: "PERMISSION"
        reversed: true
        permission: "useless.permission"
    actions:
      '0':
        type: "GIVE_PERMISSION"
        permission: "useless.permission"
    npc_response:
      message: "OK, here you go."
      possible_responses:
        - perms2
        - bye
  perms2: 
    shortcut: "I have perms"
    message: "Oh look, now I have some awesome permission!"
    requirements:
      '0':
        type: "PERMISSION"
        reversed: false
        permission: "useless.permission"
    actions:
      '0':
        type: "TAKE_PERMISSION"
        permission: "useless.permission"
    npc_response:
      message: "Aaaand it's gone..."
      possible_responses:
        - bye
  bye:
    shortcut: "Bye"
    message: "Oh... nevermind, bye!"
    requirements: {}
    actions:
      '0':
        type: "ABANDON_CONVERSATION"
    npc_response:
      message: "Goodbye, %player!"
      possible_responses: []

Now, try to stop the server, go to plugins/NPGuys/npc/Bob.yml file and replace everything with that. Rerun server and see, what happens.

Firstly, let's look into hello dialogue, because it will be called at the beginning of each conversation (you can change it by replacing value of welcome_message at the very top). The most important fields here are message and npc_response.message. It shouldn't be hard to guess that they determine what does the player say and how does the NPC respond to that. Note that you could use %player and %npc variables (they represent callers' names) in here, as well as various formatting (& followed by some character, just like on chat or signs).

Another interesting field is npc_response.possible_responses. As the name indicates, it's a list of possible responses for a player after NPC "says" his part. In this case, we have dialogues perms1, perms2 and bye.

And what's the mysterious shortcut? It's just a shortened message representation that will occur on the scoreboard response list.

Special interaction

But, wait... We have 3 dialogues in the npc_response.possible_responses, but only two show up on the in-game list. That's because some dialogues may be rejected before creating list of avaliable responses for the player. Response is valid only if all requirements (notice the requirements list in dialogues perm1 and perm2) are met. There are many types of requirements, full list is avaliable here. Requirements with reversed value set to true work as logical negation of themselves.

There is one more special field - actions list. Actions, unlike requirements, are performed once the player has choosen certain response. They can do many awesome things, like executing commands, giving quests etc. Full action list is avaliable here.

NPGuys

Bukkit Plugins

Pages