Neo Font Render

NFR can only run in CleanroomMC.
Please USE JAVA25 to launching game.

The 1.7.10 branch is nearly complete.

core jar is enough widely, full jar contains core + Skia + noto color emoji, skia jar contains core + Skia. resources jar + skia jar + core jar = full.

A modern font rendering enhancement mod for Minecraft 1.12.2. It combines a configurable AWT atlas renderer with Skia and COSMIC Text paragraph renderers for advanced shaping and emoji. COSMIC Text is now the recommended option.

Overview

Neo Font Render replaces the old bitmap font path in Minecraft 1.12.2 with a configurable text stack that is much closer to a modern UI renderer.

Current Highlights

• Custom system fonts and external TTF files with fallback chains
• Built-in font resources, including bundled Sarasa UI SC and Noto Color Emoji
• COSMIC Text paragraph rendering for ligatures, kerning, fallback, BiDi, complex scripts, and emoji (recommended)
• Skia paragraph rendering as an alternative renderer
• Automatic fallback to the AWT atlas renderer when the primary renderer is unavailable or initialization fails
• Advanced rendering controls for oversample, adaptive raster scale, mipmap, interpolation, shader compensation, and texture edge handling
• IME / non-BMP input fix so surrogate pairs and emoji are no longer truncated by the legacy input path
• Sign editor paste patch with line wrapping across all 4 lines
• In-game config GUI, emoji test screen, hotkeys, and diagnostic commands

COSMIC Text Support (Recommended)

Neo Font Render now supports a COSMIC Text-based renderer, offering the best performance among the available engines.

• Built-in fonts for COSMIC Text now have their own separate packages
• COSMIC resolves font families by weight — e.g. MiSans Demibold resolves as family MiSans at weight 600; the main font list hides exposed variants such as MiSans Bold
• Use font.cosmic.* for explicit face overrides when needed
• Variable fonts support the wght axis and named weight instances; other axes currently use their font defaults
• If the current runtime is incompatible, the mod logs the reason and falls back to the AWT atlas renderer instead of dropping all the way back to vanilla

undefined

Skia Support

Neo Font Render also supports a Skia-based renderer through SkijaTextRenderer.

• Skia mode requires Java 9 or newer
• Embedded native packages are shipped for Windows x64, Linux x64, Linux arm64, macOS x64, and macOS arm64
• If the current runtime is incompatible, the mod logs the reason and falls back to the AWT atlas renderer instead of dropping all the way back to vanilla

This means Java 8 users can still run the mod through the legacy AWT path, while Java 9+ users can opt into COSMIC Text or the full Skia paragraph renderer.

Current Patches and Features

The current codebase includes more than just font replacement:

• Full-string Skia / COSMIC Text rendering path in the FontRenderer mixin for advanced shaped text
• AWT glyph atlas fallback with configurable rasterization and filtering
• Unicode IME fix in GUI input handling for emoji and other non-BMP characters
• Ctrl+V paste support in the sign editor with width-aware wrapping
• Configurable built-in fonts, including bundled Sarasa UI SC and emoji resources
• Runtime texture filter overrides for custom font textures
• In-game emoji test screen and font diagnostics command surface

Controls and Commands

Default Client Hotkeys

Available Commands

• /neofontrender info
• /neofontrender fonts
• /neofontrender reload
• /neofontrender test
• /neofontrender gui

Configuration

The main config file is created at:

.minecraft/config/neofontrender.toml

External font files can be placed in:

.minecraft/neofontrender/fonts/

font.name and font.fallbacks accept either system font names or TTF file paths. Below is a full sample config aligned with the current default values and first-load comments:

# Enable/disable the entire font replacement pipeline.
enabled = true

# Font selection and rasterization settings.
[font]
# Primary font name or TTF file path. Comma/semicolon-separated font family lists are also supported.
name = "neofontrender:fonts/sarasa_ui_sc_regular.ttf"
# Fallback font names or TTF file paths queried after font.name when a glyph is missing.
fallbacks = ["Serif", "Monospaced"]
# Font style: 0=Plain, 1=Bold, 2=Italic, 3=Bold+Italic.
style = 0
# Font size in pixels. 8.0 is close to vanilla 1.12 UI text height.
size = 10.0
# Rasterization oversampling factor. Raster resolution is size * oversample.
oversample = 12.0
# Align each font's measured AWT baseline to the Minecraft reference baseline before manual shift.
autoBaseline = true
# Additional vertical glyph shift in Minecraft pixels after automatic baseline alignment. Positive moves glyphs down.
baselineShift = 0.0
# Minecraft-space baseline used by autoBaseline. Vanilla 8px UI text is approximately 7.0.
referenceBaseline = 7.0
# Enable AWT anti-aliasing during glyph rasterization.
antialias = true
# AWT text anti-aliasing mode: off, on, gasp, lcd_hrgb, lcd_hbgr, lcd_vrgb, lcd_vbgr.
antialiasMode = "on"
# Enable fractional font metrics for more precise positioning.
fractionalMetrics = true
# Always append bundled fonts, such as Noto Color Emoji, to the fallback family.
builtinFallbacks = true

# COSMIC Text face overrides. Leave empty to derive variants from font.name.
[font.cosmic]
regular = ""
bold = ""
italic = ""
boldItalic = ""

# Text shadow rendering options.
[shadow]
# Shadow offset distance in pixels.
length = 1.0
# Shadow opacity multiplier (0.0–1.0).
opacity = 0.25

# OpenGL texture rendering options.
[rendering]
# Text renderer engine: vanilla, sfr, skia, or cosmic.
engine = "cosmic"
# In Skia mode, render full formatted strings as one paragraph so shaping, ligatures, kerning, emoji ZWJ, and BiDi can work across the whole text.
skiaAdvancedStringMode = true
# Use GL_LINEAR texture filtering instead of GL_NEAREST.
interpolation = false
# Enable mipmapping for font textures.
mipmap = true
# Cap SFR/Skia rasterization scale to the current GUI pixel scale and avoid over-downsample blur.
adaptiveRasterScale = true
# Use a dedicated straight-alpha text draw pipeline. Keep this OFF for color emoji.
enhancedTextPipeline = false
# Use a tiny compatible shader to compensate thin anti-aliased glyph edges.
shaderTextPipeline = false
# Text edge compensation strength used by the enhanced shader pipeline.
brightness = 0.0
# Fill fully-transparent Skia text pixels with neighboring RGB to prevent black fringes.
textureEdgeBleed = false

# Performance tuning options.
[performance]
# Initialize font rasterization on a background thread.
asyncInit = true
# Pre-bake common Basic Latin and Latin-1 glyphs before enabling replacement rendering.
prewarmBasicLatin = true

# Input behavior tweaks.
[input]
# Allow Ctrl+V paste in the vanilla sign editor. This is intentionally config-file only.
allowSignPaste = true

# Debug logging options.
[debug]
# Log IME input fix details to game log.
imeInput = false

Practical Notes

• rendering.engine supports vanilla, sfr, skia, and cosmic
• font.builtinFallbacks = true appends bundled fonts such as Noto Color Emoji to the fallback chain
• COSMIC resolves MiSans Demibold as family MiSans at weight 600. The main font list hides exposed variants such as MiSans Bold; use font.cosmic.* only for explicit overrides.
• Variable fonts support the wght axis and named weight instances; other axes currently use their font defaults.
• input.allowSignPaste is intentionally config-file only
• debug.imeInput = true can help diagnose IME / emoji input issues

Example: Use COSMIC Text with a custom primary font and emoji fallback

[font]
name = "Microsoft YaHei UI"
fallbacks = [
  "Noto Sans",
  "./neofontrender/fonts/MyExtraFallback.ttf"
]
builtinFallbacks = true

[rendering]
engine = "cosmic"
adaptiveRasterScale = true
mipmap = true

Example: Use Skia with a custom primary font and emoji fallback

[font]
name = "Microsoft YaHei UI"
fallbacks = [
  "Noto Sans",
  "./neofontrender/fonts/MyExtraFallback.ttf"
]
builtinFallbacks = true

[rendering]
engine = "skia"
adaptiveRasterScale = true
mipmap = true

Example: Force the legacy renderer for Java 8 or troubleshooting

[rendering]
engine = "sfr"

[input]
allowSignPaste = true

Runtime Notes

• Target game: Minecraft 1.12.2 / Forge 14.23.5.2847
• Default renderer preset: COSMIC Text with adaptive raster scale enabled
• Build target: Java 8 bytecode
• COSMIC Text / Skia runtime requirement: Java 9+

Known Performance Bottleneck: Per-Quad GL Blend Queries

Anti-aliased replacement fonts require GL_BLEND to composite correctly, but Minecraft 1.12.2 turns blend off in many code paths (e.g. Gui.drawRect). To guarantee correct rendering, FontRenderPipeline currently captures and restores blend state around every single glyph quad via:

• glIsEnabled(GL_BLEND)
• 3x glGetInteger for blend func factors
• enableBlend() + tryBlendFuncSeparate()
• Restore on close()

This means tens to hundreds of synchronous GPU queries per frame when a lot of text is on screen. We attempted a string-level blend guard (once per drawString / renderStringAtPos), but Minecraft's GL state is mutated in too many undocumented places (other mods, vanilla GUI code, etc.) for this to be reliable — text ends up corrupted in buttons, books, and other UI elements.

If you have ideas for a robust string-level or batch-level blend optimization that doesn't break when MC secretly pollutes state, PRs are very welcome. See docs/blend-architecture.md for the current design.

Architecture

The current text renderer is organized by actual renderer responsibility:

src/main/java/neofontrender/core/font/
├── FontManager.java          # renderer selection, lifecycle, and fallback
├── backend/                  # renderer-facing backend abstraction
├── awt/                      # legacy AWT atlas renderer and glyph model
├── skia/                     # Skia renderer, runtime checks, and debug utilities
├── cosmic/                   # COSMIC Text renderer and integration
├── support/                  # shared rendering utilities and GL helpers
└── layout/                   # future-facing layout seam, not forced into the current hot path

Development Environment

This project uses CleanroomMC's TemplateDevEnv with RetroFuturaGradle.

• Gradle wrapper + RetroFuturaGradle 2.0.2
• Forge 14.23.5.2847 for Minecraft 1.12.2
• Azul Java 8 toolchain for compilation
• CoreMod + MixinBooter integration

Building

./gradlew build

Build and Deploy produces COSMIC Text natives for Windows x86_64/ARM64 and for x86_64, AArch64, and LoongArch64 Linux, with separate GNU/glibc and musl builds. Universal packages select the matching architecture and libc at runtime. For a local prebuilt bundle, pass -PcosmicNativeBundleDir=/path/to/cosmic-natives. Linux host-only builds default to GNU; use -PcosmicLinuxLibc=musl when building on a musl host.

Running

./gradlew runClient

Links

• Website: https://sirrus.cc
• Author: AndreaFrederica BakaGourd
• Chinese README: README.zh-CN.md

License

MIT License — see LICENSE for details.