Skip to content

✒️ Markov process-based procedural name and word generator library

License

Notifications You must be signed in to change notification settings

Tw1ddle/markov-namegen-lib

Repository files navigation

Markov Namegen logo

License Badge Build Status Badge

Markov Namegen is a Markov chain-based word generator library written in Haxe, made for procedural name generation. Run the demo here.

Screenshot

Features

  • Hundreds of customizable/combinable training data presets.
  • Katz backoff using high order models - look up to "n" characters back.
  • Sort and filter generated strings by length, start, end, content and regex matching.
  • Damerau-Levenshtein distance similarity sorting option.
  • Dirichlet prior parameter.

Usage

See the demo code for a complete worked example. Also see the library documentation.

Library Setup

Get the Markov Namegen library from GitHub or through haxelib.

Include it in your .hxml

-lib markov-namegen

Or add it to your Project.xml:

<haxelib name="markov-namegen" />

You can also transpile the library for use with different target languages by running the following from the root of the repository, and then checking the generated code in the bin folder:

haxe build.hxml

How It Works

The markov-namegen haxelib uses Markov chains to procedurally generate original words.

Using a set of words as training data, the library calculates the conditional probability of a letter coming up after a sequence of letters chosen so far. It looks back up to "n" characters, where "n" is the order of the model.

The generator can use several orders of models, each with memory n. Starting with the highest order models (models with bigger memories), it tries to get a new character, falling back to lower order models if necessary - an approach known as Katz's back-off model.

A Dirichlet prior is used to add a constant probability that any letter may be picked as the next letter. This acts as an additive smoothing factor and adds a bit more "randomness" to the generated output.

Countless words are generated, and are then filtered and sorted according to several tweakable criteria like length, start and end characters, similarity to a target word, and so on.

Markov Namegen Ports

Some users have ported and extended the Markov Namegen library to different programming languages. See:

Tips

  • The generator works by using Markov chains, and requires training data to build them. A hundred or more words within your chosen category is usually sufficient for good results.
  • Sort words by similarity to preferred "good words" using an edit distance metric, and pick the most similar and suitable results. There are a few edit distance measures provided in EditDistanceMetrics.hx.
  • To get best results the training dataset, model order and prior will need to be tweaked for the type of words you want to generate. If possible, keep the prior parameter low or zero. Filter words to suit: look at length, beginning, end, contents, edit distance limits and regex. Some of this done for you in NameGenerator.hx. If you prefer to do it your own way, subclass the Generator class.

Notes

  • Many of the concepts used for the generator were suggested in this article by Jeffrey Lund.
  • The haxelib is written in plain Haxe and so supports every Haxe target.
  • If you have any questions or suggestions then get in touch or open an issue.

License

  • Most of the training data bundled in the haxelib comes from sites like Wikipedia and census data sources over many years. CC-BY-SA 3.0 as a derivative from Wikipedia content will cover most of the content if you wish to use these for other purposes, but I provide no guarantee.
  • The haxelib code is provided under the MIT license.