Wow this has been really some time off the game. We’ve actually run to the point of doing nothing for months, because after finishing a basic game engine – and being quite content with being able to make a prototype game to test its neat features – we’re quite daunted by the fact that we somehow have to start making lots and lots of graphics, sounds, etc and therefore have to start working on the more boring stuff of building a good tool for putting in these game assets, which should prevent pulling out hairs every time you want to test e.g. changing a parallax layer or a few altered pixels in a sprite sheet.

Anyway for the interactive dialogue, which this post is about, this tool should not be necessary, since the input format should be easy enough to edit and understand without needing a separate tool. Check out the previous two posts on this topic for some context on this.

Ok before I’ll wrap up interactive dialogue, let’s just say: we still love to finish this game before the sun explodes, however it’ll take some aligning of stars before we’re ready to take it on afresh. Until this happens however, we’re still interested in doing the occasional tech update here, since we haven’t quite covered everything there is to say about our game engine.

Enough chatter, let’s finish up what there is to say about the dialogue engine by getting into:

• How to parse the YAML dialogue files into a model the dialogue engine can handle
• How the dialogue engine is built up
• How the dialogue is put up on the screen

~ Loading & parsing ~

Before the dialogue engine can do anything, the dialogue files have to be loaded and parsed into human understandable objects. Here’s the first bit of loading code (contained within DialogueUtil) the DialogueEngine calls whenever it needs to start a dialogue for a certain character:

public static function loadDialogue(actorId: String, roomName:String):Dialogue {
  var data:AnyObjectMap = Yaml.parse( Luxe.resources.text("assets/game/dialogue/" + actorId + ".yaml"    ).asset.text);
  var d:Dialogue = new Dialogue(actorId);
  var blocks:Map<String, DialogueBlock> = new Map<String, DialogueBlock>();

//each k is a DialogueBlock, make sure to distinguish between a hero block and another block
  for(k in data.keys()) {
    var commands = parseCommandArray(data.get(k), null);
    var block:DialogueBlock = new DialogueBlock(

      k,isHeroDecisionBlock(commands)

    );
    block.commands = commands;
    blocks.set(k, block);
  }
  d.blocks = blocks;
  return d;
}

As mentioned in the previous post, you can see that each dialogue file represents all of the dialogue of a single game character (actor). What this function basically does is that it returns a Dialogue, which in turn contains a number of DialogueBlocks, which in turn each contain a number of DialogueCommands. More on the underlying model in a bit.

As you can see as well, each DialogueBlock either represents a ‘hero decision’ or not. Here’s the ugly (I actually left the comment saying it is ugly in, so you are super aware of the fact that it ain’t pretty) function that determines whether a block is a ‘hero decision’ block:

//keilelijk maar ja nou en!?

private static function isHeroDecisionBlock(commands:Array<DialogueCommand>):Bool {
  for(c in commands) {
    if(Std.is(c, ActorSpeakCommand)) {
      var asc = cast(c);
      if(asc.optionId != -1) {
        return true;
      }
    }
  }
  return false;
}

It basically looks if the contained DialogueCommand contains an option ID, which  represents the choice number of a dialogue option.

Well what about the actual function (parseCommandArray) that parses the YAML data structure and puts everything into the dialogue model? It’s a bit too much to go through it in this post, but you can find it in the GitHub repository I put up which contains all of the dialogue related code. You’ll find the link at the bottom of this post.

~ The model ~

As mentioned, the model that powers the dialogue engine is made up of the following objects:

Dialogue

A dialogue contains all of the dialogue logic the hero can have with a certain NPC regardless of location. In code a dialogue is basically a hash/map/dict containing a bunch of DialogueBlocks, which have been loaded by the aforementioned parsing functions:

class Dialogue {

  public var id:String;
  public var blocks(default, default):Map<String, DialogueBlock>;

  public function new(id:String) {
    this.id = id;
  }

}

DialogueBlock 

A DialogueBlock basically groups a number of related dialogue phrases or actions, all types of DialogueCommands, by topic. It has a human readable ID, which should reflect this topic, and can be conveniently referred to, for execution, after a certain DialogueCommand has finished.

class DialogueBlock {

  public var blockId:String;
  public var isHeroDecision(default, default):Bool;
  public var commands(default, default):Array<DialogueCommand> = new Array<DialogueCommand>();

  public function new(blockId:String, isHeroDecision:Bool) {
    this.blockId = blockId;
    this.isHeroDecision = isHeroDecision;
  }

}

DialogueCommand

A DialogueCommand is the abstract concept that reflects any action within a DialogueBlock. In code the DialogueCommand is an abstract class and currently has four different implementations, namely ActorSpeakCommand, BlockRefCommand, ExecCommand, SetGameStateCommand.

Most importantly, each implementation should implement the toLuaString() function. This function basically maps the command to a piece of Lua script that in turn will call the game engine to do some stuff.

Here’s the abstract DialogueCommand class, followed by the ActorSpeakCommand class that extends it.

class DialogueCommand {

  public var precondition(default, default):String;
  public var optionId(default, default):Int;
  public var optionIndex(default, default):Int;

  public function new(precondition:String, optionId:Int = -1, optionIndex = -1) {
    this.precondition = precondition;
    this.optionId = optionId;
    this.optionIndex = optionIndex;
  }

  public function run():Void {

  }

  public function toLuaString():String {
    return null;
  }

}

class ActorSpeakCommand extends DialogueCommand {

  public var actorId:String;
  public var text:String;

  public function new(precondition:String, actorId:String, text:String, optionId:Int=-1, optionIndex=-1) {
    super(precondition, optionId, optionIndex);
    this.actorId = actorId;
    this.text = text;
  }

  override public function toLuaString():String {
    var s:String = "\tactorSays(\""+actorId+"\", {\""+text+"\"})\n";
    s += "\twaitSignal(\"finishedspeaking_"+actorId+"\")";
    return s;
  }
}

The optionId and optionIndex are used to directly reference the command in case it is related to a choice the player makes in the dialogue HUD (so if the command is within a DialogueBlock that is a ‘hero decision block’).

~ The engine ~

The DialogueEngine is basically capable of executing DialogueBlocks and DialogueCommands. In order to start a dialogue, the scripting engine or game engine simply has to call the runDialogue function and supply it with an actor ID:

public function runDialogue(actorId:String) {

  if(currentDialogue == null) {
    currentDialogue = DialogueUtil.loadDialogue(actorId, null);
  }

  if(currentDialogue != null) {
    playState.currentGameState = Util.DIALOGUESTATE;
    runDialogueBlock(currentDialogue.blocks.get('first_encounter'));
  }
}

What follows is that the correct YAML file is loaded – based on the actor ID – and subsequently the game state is set to DIALOGUESTATE, which is needed to make sure that the game engine e.g. knows that it should hide the regular interface elements to make room for the DialogueHUD, which needs to be displayed whenever the dialogue runs into a choice for the player (more on this later). Lastly the dialogue is started by executing the mandatory DialogueBlock with the label/ID ‘first_encounter’ (see previous post).

You should check out the runDialogueBlock function on GitHub. Basically it checks whether it should show the dialogueHUD (and populate it with the correct options) and give the player a choice, or it simply translates the DialogueCommands to Lua code and executes this, so e.g. an NPC will say something and/or a cutscene will start, etc.

~ How the engine is integrated ~

The dialogue engine is simply a package that is part of the game engine and which has a specific goal & task: make it possible to have the game characters engage in conversation. More specifically, the dialogue engine exposes a number of functions that can be used in the Lua scripting engine. How this scripting engine works is something for another post. In the meantime however, here are the functions that your scripting guy can use now:

runDialogue(actorName)

waitSignal('finished_dialogue)

The first one simply makes a certain dialogue start. Of course the actors involved must be present in the same room for it to work.

The second simply blocks the script until the game engine sends the ‘finished_dialogue’ signal, but how all this exactly works is for the next time.

~ Dialogue HUD ~

Finally the only thing that requires some attention is the DialogueHUD that draws the options for the player choices on the screen.

Well the only thing interesting to say is that the DialogueHUD gets called by the dialogue engine with the options it should show. Whenever the user selects an option, the HUD calls the dialogue engine to execute all of the DialogueCommands that are related to the selected option’s ID.

~ Code! ~

Probably way easier than reading this post is actually checking out the code itself in GitHub. I added lots of comments, so it shouldn’t be that hard to figure out. Also please note that you cannot simply check-out and run the code, since you would require the rest of our game engine, which we don’t have publicly online. I did keep all the imports and code that refers to our game engine, so you can better understand how it would work.

Alright, I hope this stuff makes sense to you. Please feel free to ask any question in the comments!

Until we meet again (and most likely will go into the Lua integration)