Writing API

Functions for saving character cards and lorebooks to various formats.

writeCardToPng()

Embed a character card into a PNG image.

Signature:

function writeCardToPng(
  card: CharacterCard,
  imageBytes: Uint8Array,
  options?: WritePngOptions
): Uint8Array

Parameters:

Returns: Uint8Array — PNG bytes with embedded card data.

Example:

import { writeCardToPng } from '@motioneffector/cards'

const pngWithCard = writeCardToPng(card, baseImageBytes)

// With options
const pngV3Only = writeCardToPng(card, baseImageBytes, {
  includeV2Chunk: false,
  serializeDecorators: true
})

Throws:

• Error — When imageBytes is not a valid PNG

writeCardToJson()

Serialize a character card to JSON string.

Signature:

function writeCardToJson(card: CharacterCard): string

Parameters:

Returns: string — Pretty-printed JSON string.

Example:

import { writeCardToJson } from '@motioneffector/cards'

const json = writeCardToJson(card)
// Returns formatted JSON with 2-space indentation

writeCardToCharx()

Create a CHARX (ZIP container) with the card and optional assets.

Signature:

function writeCardToCharx(
  card: CharacterCard,
  options?: WriteCharxOptions
): Uint8Array

Parameters:

Returns: Uint8Array — ZIP file bytes.

Example:

import { writeCardToCharx } from '@motioneffector/cards'

// Without assets
const charx = writeCardToCharx(card)

// With assets
const charx = writeCardToCharx(card, {
  assets: [
    { type: 'icon', name: 'main', data: iconBytes, ext: 'png' },
    { type: 'emotion', name: 'happy', data: happyBytes, ext: 'png' }
  ]
})

writeLorebookToPng()

Embed a standalone lorebook into a PNG image.

Signature:

function writeLorebookToPng(
  lorebook: Lorebook,
  imageBytes: Uint8Array
): Uint8Array

Parameters:

Returns: Uint8Array — PNG bytes with embedded lorebook data (uses naidata chunk).

Example:

import { writeLorebookToPng } from '@motioneffector/cards'

const lorebookPng = writeLorebookToPng(lorebook, baseImageBytes)

writeLorebookToJson()

Serialize a standalone lorebook to JSON string.

Signature:

function writeLorebookToJson(lorebook: Lorebook): string

Parameters:

Returns: string — Pretty-printed JSON string with lorebook_v3 wrapper.

Example:

import { writeLorebookToJson } from '@motioneffector/cards'

const json = writeLorebookToJson(lorebook)
// Returns: {"spec":"lorebook_v3","data":{...}}

Types

WritePngOptions

interface WritePngOptions {
  includeV2Chunk?: boolean
  serializeDecorators?: boolean
}

WriteCharxOptions

interface WriteCharxOptions {
  assets?: AssetData[]
}

AssetData

interface AssetData {
  type: string
  name: string
  data: Uint8Array
  ext: string
}