Export formats

An export format adds an item to the Export dialog. Hammer gives your plugin the story, and your plugin returns the file's bytes.

Every request is a JSON object. It includes locale, the BCP 47 tag of Hammer's UI language (such as fr-CA), or null; write your messages in this language. Don't confuse it with the project's language, which is the language the story is written in. Every request also includes settings, with the current value of each setting your plugin declares. Every key is present. See the manifest.

Like every export, export takes no arguments and returns an i32: 0 for success, anything else for failure. A call also fails if it traps. Either way, the writer sees the message your plugin set with error_set. See the host functions.

#Manifest

[[exporters]]
format = "wordfreq.csv"
extension = "csv"
mime = "text/csv"
label = "Word frequency (CSV)"
input = "prose"

Hammer won't install a plugin that declares a format twice, gives an unknown input or output, or sets cover without images.

A plugin can declare several formats. A single export function renders all of them and tells them apart by the request's format.

Your formats are also available in other places, with no extra code:

• through the project.export operation
• on the command line, as hammer project export --format plaintext.txt
• through the MCP plugin

If a project has turned your plugin off, it doesn't list your formats, and project.export rejects them in that project.

#Request

{"format": "wordfreq.csv", "projectName": "Storm", "language": "en",
 "topLevelAsChapters": true,
 "chapters": [{"name": "Chapter 1", "scenes": ["Rain fell *hard*.", "..."], "prose": []}],
 "images": [], "coverImageId": null,
 "settings": {"min_length": 3}, "locale": "en-GB"}

#Prose input

With input = "prose", each scene arrives already parsed into blocks by Hammer's own markdown parser. The built-in formats render from this same parse, so your plugin doesn't need a markdown parser of its own, and it reads the text exactly as they do. A chapter's prose is a list with one entry per scene, and each entry is a list of blocks.

{"name": "Chapter 1", "scenes": [], "prose": [
  [{"type": "heading", "level": 2, "spans": [{"text": "Morning"}]},
   {"type": "paragraph", "spans": [{"text": "Rain fell "}, {"text": "hard", "italic": true}, {"text": "."}]},
   {"type": "blank"},
   {"type": "rule"}]
]}

Each block has a type:

Any other project image, such as one inside a line, one whose file Hammer couldn't read, or any image when the format doesn't set images, arrives as its name, as text. An image without a name is left out.

A span is a run of text in a single style: {"text": "...", "bold": true, "italic": true, "strikethrough": true, "code": true, "link": "https://..."}. Styles that are off are left out, and so is a missing link, so a plain span is just {"text": "..."}.

#Images

A format that sets images = true gets, in images, each project image the story refers to whose file Hammer could read, sorted by id:

{"id": 5, "name": "Map", "extension": "png", "mimeType": "image/png", "content": "iVBORw0KGgo..."}

These are the same keys image.get returns, plus mimeType. With cover = true as well, the cover is among images, and coverImageId is its id.

In scenes, an image is a line of its own, ![image](hammer://image/<id>). Only Hammer can resolve that destination, so your plugin looks the id up in images. The alt text means nothing: Hammer shows the image's current name wherever alt text would appear. Hammer builds images from every reference it finds, including one in a code span or a bare link.

Hammer sends every image the story refers to, and the cover, not a selection. An image can be up to 8 MiB, and base64 adds a third. See Rules for what that means for memory.

#Reply

With output = "file", the default, your plugin's output is the file's bytes, exactly as they should be written. Don't wrap them in JSON.

#Archives

With output = "archive", your plugin returns a list of files as UTF-8 JSON, and Hammer zips them, in order, into the export file. Your plugin doesn't need any zip code. The manifest still gives the format's extension and mime; zip and application/zip suit it.

{"files": [{"path": "story.md", "text": "# Storm\n\n![Map](images/5.png)"},
           {"path": "images/5.png", "image": 5}]}

Each file has a path and exactly one of these:

A path is relative, with / between its segments:

• It isn't empty and doesn't start with /.
• It has no \, no empty segment (so no // and no trailing /), and no . or .. segment.
• It's valid Unicode, and at most 65,535 bytes as UTF-8, the zip format's limit on an entry name.
• No two files have the same path.

The reply needs at least one file. Hammer checks the whole reply before it writes any of it. A reply that isn't this JSON, or that breaks a rule, fails the export with a message naming your plugin and the path or problem. The kits' archive builders check the same path rules as each file is added, apart from the length and Unicode rules.

#Rules

• Exports run on a background thread, not the UI thread. If your plugin is removed or replaced while an export is running, that export finishes on the old version of the plugin.
• If an export fails, Hammer shows the message set with error_set. In the C kit, extism_error_set_buf_from_sz sets it; the Kotlin and Rust kits set it through their error handling. See the host.
• The request contains the whole story, and its images. It counts against what each call can pass to and from Hammer: 256 MiB, or a sixteenth of the JVM's heap if that's less (16 MiB on a 256 MB Android heap). No manifest key raises that cap. The reply counts too, beside the request. A request that doesn't fit fails the export before your plugin runs, and a reply that doesn't fit fails it with an allocation error. See the host.
• An image entry in an archive adds only its path to the reply, so an exporter that packages the story's images that way holds them once. Bytes your plugin sends in content cost 4/3 of their size. In a language that uses linear memory (C, Rust, Zig, AssemblyScript, Go), raise [limits] memory. The copy of the request, the decoded images, and the output are live at once, so plan for about three and a half times the size of the story's images; an exporter that writes image entries needs only the request copy and its own text. A Kotlin/Wasm plugin keeps its objects in the interpreter's heap instead, where [limits] memory doesn't apply.

#In each kit

Here's the same export in each kit: a text file listing each chapter and how many scenes it has.

import hammer.ExportRequest
import hammer.exporter
import kotlin.wasm.WasmExport

fun helloExport(request: ExportRequest): String = buildString {
    appendLine(request.projectName)
    request.chapters.forEach { appendLine("${it.name}: ${it.scenes.size} scenes") }
}

@WasmExport
fun export(): Int = exporter { helloExport(it).encodeToByteArray() }

use hammer::export::Request;

#[unsafe(no_mangle)]
pub extern "C" fn export() -> i32 {
    hammer::run(|| {
        let request: Request = hammer::input_json()?;
        let mut text = format!("{}\n", request.project_name);
        for chapter in &request.chapters {
            text += &format!("{}: {} scenes\n", chapter.name, chapter.scenes.len());
        }
        Ok(text)
    })
}

#define HAMMER_IMPLEMENTATION
#include "hammer.h"
#include "hammer_json.h"
#include "hammer_out.h"

int32_t EXTISM_EXPORTED_FUNCTION(export) {
  hammer_alloc_reset();
  uint64_t size = extism_input_length();
  char *input = hammer_must_alloc(size);
  extism_load_input(0, input, size);

  HammerBuffer out = {0};
  HammerJson json;
  const char *name;
  uint64_t name_length;
  if (hammer_json_find(input, size, "projectName", &json) && hammer_json_string(&json, &name, &name_length)) {
    hammer_reserve(&out, name_length);
    out.length += hammer_json_unescape(name, name_length, out.data + out.length);
  }
  hammer_put_char(&out, '\n');
  extism_output_buf(out.data, out.length);
  return 0;
}