**Title:** Name Generator

**Description:** 

**Details:**
LuaNameGen is a tool to quickly generate random names for characters, objects and places. It is useful for both table-top games (run the script, grab the name) or to be used as a library for game development. This mod exposes the LuaNameGen API for other Minetest mods to use.

This script is shamelessly inspired by the great `libtcod's namegen`, written by Dominik "Mingos" Marczuk. It even uses its syntax for .cfg files, aiming to provide compatibility with its existing sets.

# Basic usage

To get a dwarf name and surname, using default sets, just do:

	name_generator.parse_lines(io.lines(modpath.."/data/creatures.cfg")) -- loads the config file that includes dwarf names

	local name = name_generator.generate("dwarf male")  --  Dolin
	local surname = name_generator.generate("dwarf surname")  --  Steelcutter
	
# Like-a-boss usage

To get whatever you want, call for a name set with the rule you want:

    local syllable_a = name_generator.generate_custom("orc female 2", "$A$10B")  --  Bragluk
    local syllable_b = name_generator.generate_custom("giant female", "$B$10B")  --  tuhli
    local syllable_c = name_generator.generate_custom("infernal 1", "-$B$B")  -- -mozraz
    print("It's alive!!!", syllable_a .. syllable_b .. syllable_c)  -- It's alive!!!   Bragluktuhli-mozraz

# How does it work?

Each set file (also plain text files) follows a simple syntax (libtcod's syntax, so any .cfg file from it can be used), and may contains multiple sets. This is an example of a basic set:

	name "dwarf male" {
		syllablesStart  = "Do, Due"
		syllablesEnd = "lin, rin"
		rules = "$s$e"
	}

This set with its only rule would generate names such as:

* Dolin
* Dorin
* Duelin
* Duerin

# Syllable Groups

Every syllable group has a matching symbol (used rules, `s` and `e` in the previous example) that matches it, and will, after parsed, be stored under a specific key on the parser data table:

|   symbol | group name          |parser field               |
|----------|:--------------------|:-------------------------:|
|   s      | syllablesStart      |parser_data["start"]       |
|   m      | syllablesMiddle     |parser_data["middle"]      |
|   e      | syllablesEnd        |parser_data["end"]         |
|   P      | syllablesPre        |parser_data["pre"]         |
|   p      | syllablesPost       |parser_data["post"]        |
|   v      | phonemesVocals      |parser_data["vocals"]      |
|   c      | phonemesConsonants  |parser_data["consonants"]  |
|   A      | customGroupA        |parser_data["cga"]         |
|   B      | customGroupB        |parser_data["cgb"]         |
|   ...    | ...                 |...                        |
|   N      | customGroupN        |parser_data["cgn"]         |
|   O      | customGroupO        |parser_data["cgo"]         |
|   ?      | phonemesVocals/     |parser_data["vocals"]/     |
|          | phonemesConsonants  |parser_data["consonants"]  |

# Rules

Considering the basic example above, if you replace its rule for "$e$s", that would swap syllables in the generated names.

It is possible to set a chance of adding a syllable. The rule "$s$e$50e" would have fifty percent chance of adding a third syllable from `syllablesEnd` group (or the matching group of the letter you pass).

If you want to have multiple rules for a same set, simply separate them with a comma:

    rules = "$e$s, $s$e"

Each rule would have an equal chance to be used at each generation. If desired, you can give specific chances for each rule (by default they all have the same chance of being used):

    rules = "%50$e$s, $s$e"

Instead of each rule having 1/2 chance to be used, the first one would have 1/2*50% chance.


**Tags:** library
**Repository:** https://github.com/FaceDeer/name_generator
**License:** MIT