Changelog

All notable changes to tilttek/generator will be documented in this file.

Updates should follow the Keep a CHANGELOG principles.

0.1.0-alpha - 2026-11-12

Added

• The definitions: Entry with its text, weight, fields and tags, read like an array; EntryList; Template; TextBody with its filters, ObjectBody with TemplateField and GenerateField, GridBody with MapLayout square or hex, GraphBody with fixed or rolled nodes and extra passages; GeneratorDefinition with its variables and language and its state of StateValues, start and next templates, at most 32 by names that a variable or a field of the generator does not take; MarkovChain with its order, its lengths and whether entries come out; EntryList that invents words by a chain; Catalog by name, refusing duplicates.
• Reader and FileLoader: YAML and JSON documents, one or many lists and generators by file, a list as a sequence of entries or as a map of its entries and its markov chain, a generator's state, directories searched in depth in the order of their paths, and each error with its place; Reader::isName(), which a name with a line break after it does not pass.
• Generator: every template, a state's included, compiled in Twig's sandbox when the catalog is built, and every problem listed in one InvalidCatalog — syntax, tags, filters, functions and tests outside the sandbox, the range operator, unknown lists, tags and generators, unknown languages and filters, dice expressions that do not parse.
• The templates' functions: pick by weight, by tag, several without duplicates, with exclusions, the entries of a list filtered on the same tags kept from one pick to the next with their running weights, up to 64 filters by list; generate, once or several times without duplicates; roll on tilttek/dice; variables shared by a result; structured results whose fields see the earlier ones; text with its spaces made one.
• The grammars and their filters elide, article, agree, plural and upper_first: French elision, forms before a vowel, contraction, aspirated h, articles, feminine and plural with their exceptions; English a and an, articles and plural with its irregular words; Spanish el before a stressed a, del and al, articles with the neuter lo, feminine and plural with their written accents; German nominative articles by gender, contractions of a preposition and the article, plural by ending with its irregular words; Italian articles by the next sound, elision, articulated prepositions and partitive, feminine and plural with their irregular words; Portuguese articles, contractions with de, em, a and por, feminine and plural with their irregular words, and the count 0 of Brazil and of Portugal; the mark Grammar::KEEP (^) that keeps a word and the word before it as written; the Grammar port, documented, by which an application adds or replaces a language; Grammars by locale, usual form of the locale or language.
• Markov lists: a pick invents a word letter by letter from the runs of letters the chain learnt of the entries, counted by their weight, filtered by the tags of the pick, which the word carries; capitalised when every entry is; within the shortest and the longest length; never an entry unless the chain allows it; several without duplicates and none excluded, compared without regard to case; 50 attempts by word, each counted as a pick, then ExhaustedList; the chain learnt once by list and tags.
• Tables with a memory: a generator's state, each value given by its start template when the previous state lacks it, by its next template otherwise, or kept, its templates seeing previous and state, then the variables and the body seeing both; threaded through the results of a draw, a unique draw dropping a repeated result and the state it left; a value longer than 1024 characters stops the draw; another generator calling it starts it again.
• Random tables in tables/, each a file standing alone under table.<name>: encounters by terrain, magic items, loot with unidentified items, shops with their merchant and stock, adventure hooks, rumours of a place, a solo play oracle weighing the odds and a chaos factor, and fortunes from cards or tables; written in English in tables/en/ and in French in tables/fr/, the two versions of a table with the same lists, generators, state values and fields; Tables with their names, languages, and the directory and files of each language.
• The maps: square cells with x and y, hexagons with offset and axial coordinates, graphs whose nodes are all reachable, with extra passages, in order.
• Draws: Draw with a count, uniqueness, a seed and the previous state, at most 32 names to texts of at most 1024 characters, in UTF-8, DrawResult that says when it is short and carries the state a generator with a memory is left in, unique results within a bounded number of attempts, seeded draws on Xoshiro256StarStar, and Limits on depth, picks, time of a result, attempts, results, cells and time of the whole draw, the times checked at each pick and before each template is rendered, with Timer and SystemTimer; nothing of a draw kept for the next one but the entries filtered by tag, so that a long-running process can serve one draw after another.
• Exceptions under GeneratorException: InvalidDefinition, InvalidCatalog with its Problems, UnknownGenerator, UnknownList, UnknownTag, ExhaustedList, LimitExceeded, GenerationFailed; an exception of the library thrown inside a template reaches the caller unwrapped.
• Neutral examples: syllabic names, names invented by a Markov chain, a yes-or-no oracle, an inn in French, a village, a dungeon, and three tables with a memory — the weather as a hex flower, a journey and a hexcrawl.
• The documentation in doc/, one file per topic, indexed by the README.
• CONTRIBUTING.md, SECURITY.md and CODE_OF_CONDUCT.md.