simple-dialogue
v1.0.1
Published
A dead simple, zero-dependency, branching dialogue system written in javascript for RPG and visual novel games
Downloads
3
Maintainers
Readme
simple-dialogue
A dead simple, zero-dependency, branching dialogue system written in javascript for RPG and visual novel games
Purpose
After trying out a few different libraries that do similar branching dialogue
for npc conversations and reading some material(1) about various approaches
to this (hub and spoke, waterfall models), I wanted to write something that allowed
flexibility. Specifically I wanted a couple lifecycle hooks
(this is where pre
and post
come in), and I also wanted dialogue system itself
to not concern itself with managing as little state internally as it could to provide
the basics.
Install
From your project directory on the commandline/terminal:
npm install --save simple-dialogue
Setup
As es6 module:
import { loadDialogue, interactWith, clearDialogue } from 'simple-dialogue'
As node/es5:
const { loadDialogue, interactWith, clearDialogue } = require('simple-dialogue')
As browser script:
<script src="https://cdn.jsdelivr.net/gh/bpkennedy/[email protected]/dist/compiled.browser.js"></script>
Usage
A Dialogue means a single "unit" of dialogue, spoken by either an npc or the player, in a larger conversation (many Dialogues). If you could break a conversation down into "turns speaking", then each turn would be a Dialogue.
A Dialogue has an interface like this:
{
id: 1, // required, unique number
message: '', // required, string
choices: [1,2,3],
next: 1,
pre: () => {},
preId: 1,
post: () => {}
}
| | | | |
| ------------- | ----------- | ----------------- | ----------------------------------------------------------------------------- |
| id
| number | required | a unique id |
| message
| string | required |any string, template literals are supported |
| choices
| number[] | optional | array of other dialogue id
's |
| next
| number | required/optional | the next dialogue id
to go to. optional, but required if choices
is empty or omitted |
| pre
| function | optional | your callback function. Must return truthy or falsy. Will not go to next
if pre
fails |
| preId
| number | required/optional | if pre
fails, this is the dialogue id
to redirect to. optional, but required if pre
is used |
| post
| function | optional | your callback function. No return needed, does not effect whether going to next
or not | |
Lifecycle hooks
pre
(prerequisite):
will be run when it's dialogue is being processed by the npc. By returning a falsy or truthy value, you can control the conversation branching to one dialogue or another (or not moving forward at all).
const isHighEnoughLevel = () => somePlayer.someProperty === 'somePrerequisiteValue'
{id: 1, message: `Would you like to take my quest?`, choices: [2]},
{id: 2, message: `Sure, I'll take it.`, pre: isHighEnoughLevel, preId: 5, next: 4},
When the npc presents the message "Would you like to take my quest?", and your choice is
"Sure, I'll take it.", the isHighEnoughLevel
callback that you
provided is evaluated - perhaps it's based on some attribute or item of your player - and if truthy, the next
dialogue is loaded for the npc next. If it is falsy, then the preId
dialogue is loaded.
post
(postrequisite):
will be run after the npc has processed and loaded the next dialogue. The return of this function is not used by the npc (or this library). It's purely for your code to use for setting your own state and game logic at specific points during the conversation.
const takeQuest = () => somePlayer.someStatus = 'acceptedChickenQuest'
{id: 1, message: `Will you catch my runaway chickens?!`, choices: [2]},
{id: 2, message: `Sure, I'll get'em.`, post: takeQuest, next: 3},
Ending and Restarting conversation
To indicate that a conversation is complete, set a dialogue's next
to be null or undefined. This can be done on
either a player choice kind of dialogue or a npc response kind of dialogue. When the npc processes a dialogue with
next
set as null/undefined, it will default to using the last dialogue that it had responded with.
In this way, you may have flexibility in that an npc end conversation in waterfall style fashion (i.e. player only gets the last thing that an npc said and cannot 'retry' the conversation):
// ------a player choice ending a conversation--------
{id: 1, message: 'You doing alright?', choices: [2,3]},
{id: 2, message: 'Yea', next: null},
{id: 3, message: 'No', next: null},
interact('guy')
// provides: You doing alright?
// provides choice #2: Yea
// provides choice #3: No
interact('guy', 2)
interact('guy') // provides: You doing alright?
// -------an npc ending the conversation---------
{id: 1, message: `Will you catch my runaway chickens?!`, choices: [2]},
{id: 2, message: `No, I hate chickens, and I hate you.`, next: 3},
{id: 3, message: `You are such a disappointment`, next: null}
interact('guy')
// provides: Will you catch my runaway chickens?
// provides choice #2: No, I hate chickens, and I hate you.
interact('guy', 2) // provides: You are such a disappointment.
interact('guy') // provides repeat: You are such a disappointment.
or you can retry an npc conversation in the hub-and-spoke style (i.e. player can retry conversation to explore other choices) by setting a previous dialogue id rather than null to loop your conversation:
{id: 1, message: `Will you catch my runaway chickens?!`, choices: [2,3]},
{id: 2, message: `No, I hate chickens, and I hate you.`, next: 4},
{id: 3, message: `Yes.`, next: 5},
{id: 4, message: `Huh, come back when you're ready to help`, next: 1}, // routes back to beginning
{id: 5, message: `Thanks for taking my quest! Come see me when you have it finished!`, next: null},
interact('guy')
// provides: Will you catch my runaway chickens?!
// provides choice #2: No, I hate chickens, and I hate you.
// provides choice #3: Yes.
interact('guy', 2) // provides: Huh, come back when you're ready to help
interact('guy') // provides reset: Will you catch my runaway chickens?!
Development
Want to contribute? Great! To fix a bug or enhance a feature, follow these steps:
- Fork the repo
- Create a new branch (
git checkout -b improve-feature
) - Make the appropriate changes in the files
- Ensure that linting and tests pass, and that coverage is at 100%.
npm run prepull
- Add changes to reflect the changes made
- Commit your changes (
git commit -am 'Improve feature'
) - Push to the branch (
git push origin improve-feature
) - Create a Pull Request
Bug / Feature Request
If you find a bug, kindly open an issue here.
If you'd like to request new functionality or feature, feel free to do so by opening an issue here. Please describe the functionality or feature you'd like to see.
To-do
- Add non-literal dialogue choices:
{id: 1, message: `Will you catch my runaway chickens?!`, choices: [2]},
{id: 2, mask: '[Angry Negative]', message: `No, I hate chickens, and I hate you.`, next: 4},
// the 'mask' property could be what is displayed to the player, but the message is the literal line
// as they'll see it - providing interest and color in their player "coming alive".
License
MIT © Brian Kennedy