File formats for importing

What a D&D module JSON, a builder system JSON and a book as text or PDF carry inside, with downloadable examples and how to write them so they read well.

Roliando reads three kinds of outside file to create content: the JSON of a D&D module (the one you export yourself), the JSON of a system from the builder, and the text or PDF of a book (Markdown, TXT, PDF, Homebrewery). This guide says what each one holds and how to write a text so the importer understands it the first time. Every format has an invented example you can download and open in any text editor.

D&D module as JSON

Where: on the New module form, the Import module (.json) button creates a new private module with everything in the file. Inside an open module, More, Import module (.json) adds the file's entries to that module (the ones you already have are left alone). Next to the file picker there is a Download example link.

The file is the same one More, Export the module (JSON) or a single category's export downloads, so it works for keeping copies, moving a module to another account or editing it by hand.

Shape of the file

{
  "format": "roliando-module",
  "version": 1,
  "category": "feat",
  "module": { "name": "…", "edition": "2024" },
  "entries": [ { "category": "feat", "name": "…", "data": {} } ]
}

What does not travel and is set on import: ids, owner, dates, module_id, price and publication. An imported module is always born private and unpublished; publishing it is your call afterwards. Entry slugs are regenerated with the destination module's prefix (they are unique across the whole app) and references between entries are updated.

Fields of each entry

Tip: don't write data from scratch. Create the entry in the editor, export it and use that JSON as a template; or start from the example, which has one of each: a feat, a spell, a magic item, a species and a subclass.

Builder system as JSON

Where: in the system builder, The whole system, Import a system (the same file is what Download file gives you). You can paste the text or bring the file, and a summary of what will come in is shown before applying it; you can add to what is there or replace it.

Download the minimal example: sistema-ejemplo-en.json (Spanish: sistema-ejemplo.json). It has three rollable attributes, a calculated defence, a health pool and the roll rules.

Main blocks

Calculated fields use formulas over other fields' keys: "derived_formula": "8 + arm + FLOOR(eye / 2)". A pool (resource) carries max_formula. Whatever the importer does not understand is dropped with a warning, never silently, and repeated keys are renamed.

Book text and PDF (Markdown, TXT, PDF, Homebrewery)

Where: inside a module, More, Import homebrew. It takes an .md, .txt or .pdf file, pasted text, or a search-and-fetch from Homebrewery. Before saving anything, the importer shows what it recognised and you can change the type, rename or discard each entry.

Import as… If you open it from the Bazaar (the search outside Roliando, Import button on a Homebrewery result) or outside a module, the importer suggests what the book is and lets you change it before continuing: D&D module, Adventure (one chapter per heading, with linked images, tables and recognised creatures, in the adventure creator), World for a campaign (places, factions, history and quests as World Book entries, and characters as NPCs) or Document (one World Book chapter per section). World and document are imported hidden. A world also gets the relations between entries (a place inside another, who lives where, faction members, who serves whom), names of other entries become [[links]], and if the campaign has a map the places enter it as pins to place (no invented coordinates: you drag them). Images are copied to your storage (checked by default; any that cannot be copied stay linked), creatures with a stat block can also be saved as NPCs in your library, and roll tables in your library.

The importer does not trust section names: it classifies by what is inside them. Download the example, which uses exactly these cues: modulo-ejemplo.md.

How it recognises each type

The cues are in English (the game terms the books are based on), but the text inside can be in any language.

Writing it so it reads well

• Headings build the sections. One # for the book, ## for each chapter (Species, Feats, Spells…) and ### or #### for each entry. The heading path is kept as the entry's location.
• Each entry under its own heading. A feat or a spell is a section; its paragraphs and bullets go below.
• Bold labels with a colon: Casting Time: 1 action.
• A loose intro paragraph under the book's title is read as one more rule. If you don't want it, remove it or move it to its own chapter and discard it in the review.
• Tables in Markdown (| a | b |) are kept.
• TXT is the same as MD: it is read the same way, just without the Markdown extension. A .txt exported from Homebrewery works as it is.

Which format works best

1. Homebrewery (text/.txt) or your own Markdown. It keeps bold, italics and headings, which is exactly what the importer relies on. The most reliable.
2. PDF with text. It is read in your browser (the file never leaves your computer), rebuilding headings and bold from font size and style. It works, but a PDF with complex layout (columns, boxes, backgrounds) loses structure.
3. Scanned or image-only PDF: it does not work. If you can't select the text with the mouse, there is no text to read and the importer does not do OCR.

You import material you already own. What you import stays in a private module. Do not share or publish third-party content unless you have the right to.

See also

Importing a system: JSON, package, tables and Roll20, Importing books and homebrew: file, text and Homebrewery, Importing content, Module builder, System Builder: first steps.

All Roliando guides