dialogue.py - display interactive dialogue trees

The goal of this python module is to create a simple and easy to use dialogue system for blender games.

Scrolling overflow
Control flow of dialogue using goto statements
Display choices
Drawn using bgui
Themed using the bgui theme system

How to use:
Add an always active python controller to update the dialogue system each frame.

Call a dialogue file by creating a python controller calling ‘dialogue.display_dialogue’. Give the game object a property named ‘dialogue’ with its value set to the path of the dialogue file.

(you may need to set up a state system on your NPC to only fire the dialogue when the player is near it, see the demo for an example)

Thats it, it should work, just make sure your game can find the required files (bgui, dialogue.py, font files, background image, bgui theme and the dialogue file). The easiest way to ensure this is to place them alongside your .blend. See the demo for an example.

Creating dialogue files
You can use the dialogue editor which will let you create a dialogue tree and save it as a xml file that this system can read.


This looks incredible! What version of Blender is it created for?
Is it possible to write data to the files being used through blender? If so, could this be used as a way to save things such as character stats? I have been trying to accomplish something like that using external .txt files…

It only works with fairly recent builds of blender, anything above 2.56 should be fine.
What do you mean by “the files being used through blender”? Its definitely possible to save stats to a text file, although I’m not sure how this would be used to do that. This is more about reading and displaying information.

I’ve been looking around for a dialogue system, so I don’t have to learn crazy advanced python yet (I just managed to get it to print ‘HI’), and this looks really cool!
My only question is ,can you can have it play a sound file with the speech?

Glad you managed to get it working. I have plans to make it play sounds, as well as adding in support for updating quests and updating the inventory.

If you want to go ahead and add support for you own nodes check out DialogueSystem.main, there is an if statement in there that checks the type of node and calls a corresponding function, it looks like this:

if self.current_node is None:
elif self.current_node.tag == 'conversation':
elif self.current_node.tag == 'text':
elif self.current_node.tag == 'name':
elif self.current_node.tag == 'portrait':
elif self.current_node.tag == 'option_container':
elif self.current_node.tag == 'option':
elif self.current_node.tag == 'label':
elif self.current_node.tag == 'goto':

You could add in another elif statement at the bottom:

elif self.current_node.tag == 'sound':

and than add the handle_sound function

# right at the top of the file you'll need to import aud
import aud


class DialogueSystem(bgui.System):
    def handle_sound(self):
        # play the sound
        filepath = bge.logic.expandPath(self.current_node.text)
        sound = aud.Factory.file(filepath)
        # move to the next node

And then you can add it into your dialogue tree like so:


Looks “amazing”!
Maybe I’ll start using 2.57 after all…

I apologize for not being clearer… I didn’t look at how it was set up very carefully… I was wondering if a similar setup would be efficient for storing complicated character data (lvl, exp, current HP, inventory, ect…). So, Blender writes all current game data to an XML file at a save point and loads it up at next startup…

I hope that makes more sense… I am not a programmer, so I am sorry if that didn’t come out quite right…


I was checking it out last night… and might I say, WOW.

The only problem I had was with the conversation editor, but that’s understandable as it IS early on still.
Other than that, I congratulate you on doing something that I couldn’t even imagine figuring out…
I do want to try and add that sound, thing, that you put up.
And I do believe that this should be directly incorporated into blender in some way.

Out of curiosity do you have any plans to keep this updated now that Blender has a stable API? Its would be a shame to see this one go.

somewhy this does not work with my blender 2.62 but only with my blender 2.58 version. What could be the reason for that?

bge.Buffer.list is now bge.Buffer.to_list()
dialogue_system.zip (132 KB)

Well, that was a super quick response. Ty

Updated first post with a new version.

This is a nice add-on with the latest version, thanks for sharing! :slight_smile:

As expected from the “guru”


I really wish this would work! It looks so amazing! ^-^

For some reason it runs at ~4fps and it takes like 15 seconds to move to the pyramid and then when I press space nothing happens. My computer hardware is “ok” and I can run the game I’m creating well and it has parallax mapping, fog, heaps more.

Do you guys have any idea why it won’t work? (the example *.blend) Thanks! ^-^

Fixed!! ^-^ Thanks for this amazing script!

A dialogue for adventure games. :slight_smile:

What does this mean?

theme', None))
  File "C:\Users\My world\Desktop\dialogue\dialogue\dialogue.py", line 46, in __
    self.keymap = {getattr(bge.events, val): getattr(bgui, val) for val in dir(b
ge.events) if val.endswith('KEY') or val.startswith('PAD')}
  File "C:\Users\My world\Desktop\dialogue\dialogue\dialogue.py", line 46, in <d
    self.keymap = {getattr(bge.events, val): getattr(bgui, val) for val in dir(b
ge.events) if val.endswith('KEY') or val.startswith('PAD')}
AttributeError: 'module' object has no attribute 'OSKEY'
WARNING: Legacy theming used for Scrollbar
Python script error - object 'player', controller 'dialogue':
Traceback (most recent call last):

Blender Game Engine Finished

that’s a BGUI error.

How would i fix it?