Download the PHP package cartograph/minecraft-text without Composer

Minecraft Text

A pure-PHP library for parsing and rendering Minecraft chat text in every format the live ecosystem uses: JSON text components, SNBT text components, legacy §/&-coded strings, MiniMessage, and HTML.

Features

• Five input formats: JSON text components, SNBT text components, legacy §/&-coded strings (with the BungeeCord and Essentials hex extensions), and MiniMessage; readers are permissive by default with an opt-in strict mode
• Five output formats: JSON, SNBT, legacy, MiniMessage, and HTML; the HTML renderer is configurable for inline styles, CSS classes, or a hybrid, with a bundled reference stylesheet
• Dialect-targeted rendering: pick the Minecraft schema generation (1.20, 1.20.5, 1.21.4, 1.21.5, 26.1) and the JSON/SNBT renderers emit the canonical wire shape — correct event-key casing, allowed click and hover actions, shadow_color support, and show_item payload form
• Round-trip integrity: unknown click actions survive as CustomClickEvent; MiniMessage gradient/rainbow/transition tags round-trip verbatim through the MiniMessage renderer (other renderers lower them to plain text spans)
• Diagnostics, not exceptions: lossy and non-canonical inputs record a Diagnostic against the parse or render result rather than throwing, with stable dotted codes (parse.minimessage.unknown-tag, render.legacy.translate-dropped, render.html.url-scheme-blocked, ...) suitable for programmatic filtering
• Six native component types (Text, Translate, Keybind, Score, Selector, NBT) plus three MiniMessage-native transformations (Gradient, Rainbow, Transition)
• Style inheritance matching vanilla Minecraft semantics, with a tri-state Decorations record so children can suppress an inherited decoration (<!bold>)
• Fluent builder (TextBuilder) and a static facade (Text) for programmatic construction without manual AST assembly
• Translation resolution via a caller-supplied locale source, with a printf-style placeholder helper (%s / %1$s / %%)
• HTML safety: every text leaf is HTML-escaped, URL schemes in OpenUrl are validated against a configurable allowlist (default http/https/mailto), and obfuscated text is exposed via a data-mc-text attribute for client-side animation
• PHPStan level max with full generic annotations; 100% mutation score under Infection (all surviving mutants documented as observationally equivalent)

Requirements

• PHP 8.5 or newer
• cartograph/minecraft-nbt ^1.0 (resolved automatically by Composer)

No PHP extensions are required.

Installation

Install via Composer:

Quick start

Parse a legacy MOTD and render it as themed HTML:

That's a complete, runnable example. The bundled reference stylesheet (Html::referenceStylesheet()) defines the default mc-color-* and mc-bold rules so the output drops straight into any page.

Build a tree programmatically and serialise it as JSON for Minecraft:

Concepts

Minecraft chat text is a tree of typed components. Each component carries some content (literal text, a translation key, a keybind, a score reference, a selector, or an NBT path) plus an optional style (colour, decorations, font, shadow colour, click/hover events, insertion text) and an "extra" list of child components that inherit the parent's effective style.

Vanilla Minecraft serialises this tree in three main ways:

• JSON text components, the wire format used by chat, signs, written books, advancement descriptions, and the SLP status response
• SNBT text components, the same shape encoded as stringified NBT for use in commands and data packs
• Legacy §-codes, the pre-1.7 wire format still emitted by plugins, written into pre-1.13 worlds, and used by SLP MOTDs

The community uses two more:

• MiniMessage, a tag-language popularised by the Adventure library (Paper, Velocity), with native syntax for gradients, rainbows, and click/hover events
• HTML, for displaying chat on websites

This library reads, writes, and converts between all five. A shared, immutable Component AST sits between the readers and the renderers, so any input format can be re-rendered to any output format.

Output that targets Minecraft's JSON/SNBT wire format is dialect- driven: a Profile for the target Minecraft generation decides which fields are valid, which click/hover actions are allowed, what casing event keys use (clickEvent vs click_event), and whether shadow_color and the legacy NBT-string show_item payload are supported. Fields the dialect cannot represent record a Diagnostic and drop, or throw ProfileMismatchException under strict mode.

Lossy conversions (rendering a KeybindComponent to legacy, an unresolved TranslateComponent to HTML, an unknown <wibble> tag in MiniMessage) record dotted diagnostics on the result rather than silently failing.

Usage

Parse JSON, SNBT, legacy, or MiniMessage

Every reader has two facade entry points: a one-shot version returning just the parsed Component, and a *Result version returning a ParseResult bundling the component with any diagnostics raised.

Parsers are permissive by default — bare strings, list-as-component, both clickEvent and click_event casings, both legacy and modern show_item payloads, and unknown click actions all parse without throwing. Pass new JsonOptions(strict: true) (or the per-format equivalent) to reject non-canonical shapes.

Render to JSON, SNBT, legacy, MiniMessage, or HTML

The JSON and SNBT renderers take a JsonOptions / SnbtOptions with a dialect field — pick the Minecraft schema generation you're targeting:

Build trees programmatically

Two equivalent APIs:

The Text facade has a static factory for every component type:

TextBuilder is a fluent, immutable helper for chained construction:

Resolve translations

TranslationResolver walks a tree replacing every TranslateComponent with its resolved text. The package ships no locale data — implement the Translator interface against your own locale source:

The HtmlRenderer accepts an optional Translator via HtmlOptions and runs the resolution pass automatically before walking the tree.

Interpret legacy codes inside text fields

JSON, SNBT, and MiniMessage parsers leave §/& codes inside a text field as raw characters — that matches vanilla Minecraft's own behaviour but doesn't help with the very common ecosystem case of a JSON MOTD or SNBT block carrying legacy-coded text:

Text::interpretLegacyInText() walks a tree and expands every legacy-coded TextComponent in place via LegacyReader. The wrapping node's own style and trailing children are preserved; the legacy-parsed styled runs are spliced in as the first children of a rewrapped TextComponent carrying the original style:

The transform is opt-in (the parsers themselves never run it automatically) and lossy in one direction: once codes have been expanded into styled runs, the original raw text is gone, so a tree transformed this way will no longer re-serialise byte-identically back to its source wire format. Pass a LegacyOptions to enable & interpretation, Essentials &#RRGGBB hex, or BungeeCord §x§R§R§G§G§B§B hex (the last is on by default):

Customise HTML rendering

By default, any component that would render as a <span> carrying no class, inline style, click/hover data, insertion, or obfuscation payload is emitted as bare body text — so plain text renders as hi, not <span>hi</span>, and the empty-text root container that comes out of LegacyReader and LegacyInterpreter no longer prepends a stray <span></span>. An <a href> envelope from an OpenUrl click is kept and wraps the body directly. Pass omitUnstyledSpans: false if your consumer needs a stable one-span-per-leaf DOM for CSS hooks or position-indexed JS.

The bundled reference stylesheet (Html::referenceStylesheet()) defines the default mc-color-*, mc-bold, mc-italic, etc. classes plus a CSS-only animation for mc-obfuscated.

Class overview

The public surface splits into the AST (Component namespace), the five readers, the five renderers, the dialect/profile system, and a small set of supporting types.

Entry point

Component AST (Cartograph\Text\Component)

Readers and renderers

Profiles and diagnostics

Extension points

Compatibility

• Minecraft Java versions: parsers accept every JSON/SNBT shape emitted between 1.20 and 26.1 (Minecraft Java's current major). Renderers target the same range via JsonDialect; pick the dialect matching the server/client you're talking to.
• Legacy codes: classic § plus &, with BungeeCord §x§R§R§G§G§B§B hex (opt-in default-on) and Essentials &#RRGGBB hex (opt-in)
• MiniMessage: the vanilla tag vocabulary — colours and aliases, decorations with <!negation> form, click/hover/insertion/font, content tags (<lang>, <key>, <score>, <selector>, <nbt>), transformations (<gradient>, <rainbow>, <transition>), plus <reset/> and <newline/>. Custom tags pluggable via TagHandler.
• HTML: emits semantic markup with configurable styling mode, scheme-allowlisted click handlers, and a data-mc-* attribute convention for consumer-side JavaScript

Bedrock Edition's text format variants are not supported.

Contributing

Bug reports, feature requests, and pull requests are welcome at github.com/cartographgg/minecraft-text. See CONTRIBUTING.md for development setup and the required checks (tests, static analysis, code style, and mutation testing). Each check has a Composer script: composer test, composer static, composer style, and composer mutation.

License

Released under the MIT License. © Cartograph contributors.

Maintained as part of Cartograph, a Minecraft server directory and monitoring platform. The library is self-contained and has no Cartograph-specific behaviour; use it anywhere you need to work with Minecraft chat text in PHP.