Catalyst FX

A lightweight Fabric mod for Minecraft 1.21.10 that measures client startup time and applies a small, verified tweak to resource-loading thread allocation.

---

Background

Minecraft's client startup involves loading and preparing a large amount of data — textures, block/item models, sounds, language files — before you reach the main menu. This process runs on a background thread pool managed by the game's Util class. Catalyst FX was built by decompiling and reading that actual class (not guessing from memory or documentation) to understand exactly how thread allocation works, then making a small, targeted adjustment based on what the real source code showed.

---

Features

1. Startup timing measurement

On client init, the mod records a timestamp. When Minecraft fires its CLIENT_STARTED lifecycle event (the game has finished loading and reached the main menu), it logs the elapsed time in milliseconds: This gives a concrete, reproducible number for startup duration on your specific device — useful as a baseline before/after testing other performance mods, rather than relying on subjective impressions.

2. Background thread pool adjustment

Vanilla Minecraft calculates its resource-loading worker thread count as (CPU core count - 1), clamped between 1 and a configurable maximum (max.bg.threads system property, default 255). Catalyst FX uses a Mixin (@ModifyConstant) to change that formula so the pool uses all available cores instead of reserving one for the main thread. On multi-core devices this can shave a small amount off the resource-loading phase of startup.

---

Installation

1. Install Fabric Loader 0.17.3 or newer for Minecraft 1.21.10.
2. Download and install Fabric API — this is a required dependency, the mod will fail to load without it.
3. Download catalystfx-<version>.jar from the Versions tab on this page.
4. Place the .jar file in your mods folder.
5. Launch the game with the Fabric profile.

---

Honest scope and limitations

• The measured improvement is genuinely small (typically a few percent), because vanilla already allocates threads close to the CPU core count by default — there wasn't much headroom left to optimize.
• On devices with few CPU cores, or where the main render thread competes heavily for CPU time, the difference may be negligible.
• This is not a substitute for established performance mods like Sodium or FerriteCore — Catalyst FX targets one narrow, specific piece of the startup process, nothing more.
• Testing so far has been done primarily on a single mobile device (Termux + PojavLauncher build environment). Broader compatibility across different hardware and mod combinations hasn't been extensively verified yet. Treat this as an alpha/experimental release.

---

FAQ

Does this work on servers? No. This is a client-only mod — install it on the client, not the server. It has no server-side logic.

Will this make my game load dramatically faster? No — see the "Honest scope and limitations" section above. It's a small, measured tweak, not a silver bullet.

Is it compatible with Sodium / Iris / other performance mods? It should be, since it only touches Minecraft's own Util class and doesn't overlap with rendering-focused mods. Not exhaustively tested with every combination yet — feel free to report issues.

Why does the log show timing info even if I don't care about it? The timing log is intentionally left in so anyone testing the thread pool change can verify the actual before/after numbers on their own hardware, rather than trusting a marketing claim.

---

Changelog

0.1.0 — Initial alpha release. Startup timing measurement + background thread pool adjustment.

---

Requirements

Requirement	Version
Minecraft	1.21.10
Fabric Loader	0.17.3+
Fabric API	Required
Java	21+

Side support

• Client: Required
• Server: Unsupported

---

License

MIT — see the LICENSE file bundled in the jar.

Author

nguyenquochuy