Go to file
Alexander Yakovlev 28df4f1f93 Updated npm packages 2016-06-28 12:55:30 +07:00
devel Document sections change 2015-05-13 21:54:11 -03:00
docs Add documentation for situation.markdown 2015-10-20 23:10:44 -07:00
lib 2-element arrays are fine too 2015-12-01 17:40:49 +07:00
spec Add sections feature 2015-05-13 21:31:30 -03:00
.gitignore Add package.json, set up for npm 2015-04-10 18:18:44 -03:00
CHANGES Updated changelog 2015-10-21 11:05:35 -02:00
LICENSE add LICENSE 2015-04-07 21:56:20 -03:00
README.md README 2015-04-14 18:31:06 -03:00
karma.conf.js Add racontest 2015-04-18 13:31:43 -03:00
mkdocs.yml Document qualities.js 2015-05-04 13:26:49 -03:00
package.json Updated npm packages 2016-06-28 12:55:30 +07:00
raconteur.sublime-project Version 2015-04-14 01:37:14 -03:00



Raconteur makes writing interactive hypertext fiction with Undum straightforward and perhaps even fun. It's a wrapper library that bundles oft-needed functionality and a new, cleaner, CoffeeScript-friendly, DSL-inspired API for defining Undum stories.

situation 'west_of_house',
  content: (character, system, from) -> 
    # West of House

    You are standing in an open field west of a white house, with a boarded
    up front door.

    #{roomContents(character, system)}

Raconteur is still in active development towards its 1.0 release.

Implemented Features

  • DSL-like syntax for defining situations.
  • A powerful situation prototype that bundles a lot of commonly-used functionality.
  • Shorthand for defining common hypertext interactions such as text replacement or insertion, similar to popular Twine extensions.
  • Most properties of situations can be either functions or strings, making it easy to turn a simple situation into a complex one.
  • An interface that is specifically designed to be used with ECMAScript 6 via Babel, or CoffeeScript.
  • Markdown, rather than raw HTML, as the format for most text content using markdown-it.
  • A tool bundle of iterators that makes it easy to define adaptive text snippets.
  • Based on CommonJS principles (Using undum-commonjs), allowing all game code to be bundled using Browserify.
  • An advanced game template that sets up a complete development environment for authors: A build system (gulp), CSS preprocessing (Less), and dependency management (Browserify + npm).

Planned features

  • A complete code refactoring of Undum and Raconteur itself with testability in mind, allowing the use of testing frameworks with Undum stories.


Raconteur can be added as a dependency to a package.json file and installed from git. Or, you can use the scaffold.

Raconteur itself doesn't contain any command-line tools or anything that needs to be installed globally. You just need npm to be working on your system. Raconteur is a set of CommonJS modules designed to work with Browserify and a build system like Grunt or Gulp.

Code examples

Those examples all use CoffeeScript.

Defining a simple situation in Raconteur:

situation 'raconteur_example',
  content: """
  This is an example of a situation using Raconteur's API. It supports
  Markdown in text, so the content of a simple situation can just be
  written out without explicit HTML.

Using text snippets:

situation 'variations',
  content: (character, system) ->
    # content can be either a function or a simple string, transparently
    color = oneOf(['bright purple', 'sickly green', 'brilliant white'])
      .randomly(system) # We pass the system object so that random results
                        # will always be the same across different runs of
                        # the same saved game.

      # Reflecting Pool
      You find yourself in an underground, flooded cave. Light shimmers on
      the walls, #{color}.


In short: You can use, modify, or redistribute Raconteur and Undum, for any purpose, as long as this license document is kept with copies of it. See LICENSE for legalese.

Undum is copyright (c) 2009-2015 I D Millington, and released under the MIT license.

Raconteur itself is copyright (c) 2015 Bruno Dias, and released under the same MIT license.