BMFont XML Parser

Common errors

• Error: Failed to parse XML

  cause The input string or Buffer provided to `parse()` does not contain well-formed XML data that conforms to the BMFont XML specification.
  fix Ensure the input data is a valid XML string or Buffer and matches the AngelCode BMFont XML format, particularly having a `<font>` root element. Validate the XML content before passing it to the parser.

• TypeError: parse is not a function

  cause This typically occurs in an ES module context when trying to import the CommonJS module using named import syntax (e.g., `import { parse } from 'parse-bmfont-xml'`) instead of the correct default import or CommonJS `require`.
  fix For ES module contexts, use `import parse from 'parse-bmfont-xml'` or `import * as parseModule from 'parse-bmfont-xml'; const parse = parseModule.default;`. For CommonJS, use `const parse = require('parse-bmfont-xml')`.

Warnings

• gotcha The package relies on `xml-parse-from-string` for browser environments. This dependency may not function correctly or at all in environments lacking full DOM API support (e.g., some canvas-only contexts like CocoonJS), potentially leading to runtime errors.
  Fix: For non-standard browser-like environments, consider pre-parsing BMFont XML on a server or a build step, or ensure a DOM-compatible environment is available. Test thoroughly in target environments.
• gotcha This package has not been updated in approximately seven years. While it may still function, it might lack support for newer JavaScript features, security patches, or compatibility fixes for recent Node.js or browser environments. There is a risk of unaddressed vulnerabilities or outdated dependencies.
  Fix: Audit the package's code and dependencies if using in a critical application. Consider alternatives if modern features or active maintenance are required. Pin specific versions to avoid unexpected dependency updates if relying on an older, stable setup.
• gotcha As a CommonJS-first module published before widespread ES module adoption, `parse-bmfont-xml` may require specific configuration or bundler setup to be used seamlessly in modern ES module-only projects.
  Fix: Use a bundler (Webpack, Rollup, Parcel) that handles CommonJS interoperability, or for Node.js ESM projects, use `import parse from 'parse-bmfont-xml'` and ensure Node.js's CJS interop is correctly configured for your environment.

Install

• npm install parse-bmfont-xml npm
• yarn add parse-bmfont-xml yarn
• pnpm add parse-bmfont-xml pnpm

Imports

• parse
  wrong:

  import parse from 'parse-bmfont-xml'

  correct:

  const parse = require('parse-bmfont-xml')

  This package is primarily a CommonJS module. Direct ES module `import` syntax will typically require a bundler or Node.js's CJS interop for compatibility.
• parse
  wrong:

  import { parse } from 'parse-bmfont-xml'

  correct:

  const parse = require('parse-bmfont-xml')

  The library exports a single function as its default (module.exports). There are no named exports.

Quickstart

This quickstart demonstrates how to read an XML BMFont file using Node.js's `fs` module and parse its content into a JavaScript object, then access key properties like font face, pages, and character data.

const fs = require('fs');
const parse = require('parse-bmfont-xml');
const path = require('path');

// Create a dummy BMFont XML file for demonstration
const dummyXmlContent = `
<font>
    <info face="Arial" size="32" bold="0" italic="0" charset="" unicode="0" stretchH="100" smooth="1" aa="1" padding="0,0,0,0" spacing="1,1" outline="0"/>
    <common lineHeight="32" base="26" scaleW="256" scaleH="256" pages="1" packed="0" alphaChnl="0" redChnl="0" greenChnl="0" blueChnl="0"/>
    <pages>
        <page id="0" file="sheet0.png"/>
    </pages>
    <chars count="1">
        <char id="65" x="0" y="0" width="20" height="28" xoffset="0" yoffset="4" xadvance="20" page="0" chnl="15"/>
    </chars>
    <kernings count="0"/>
</font>
`;

const filePath = path.join(__dirname, 'dummy.fnt');
fs.writeFileSync(filePath, dummyXmlContent);

// Read and parse the BMFont file
fs.readFile(filePath, (err, data) => {
  if (err) {
    console.error('Error reading file:', err);
    return;
  }
  try {
    const result = parse(data);
    console.log('Font Face:', result.info.face);         // Expected: "Arial"
    console.log('Pages:', result.pages);                 // Expected: [ 'sheet0.png' ]
    console.log('Number of Chars:', result.chars.length); // Expected: 1
    console.log('First Char ID:', result.chars[0].id);   // Expected: 65 (for 'A')
  } catch (parseError) {
    console.error('Error parsing BMFont XML:', parseError);
  }
});