CatalystFX
- By
# 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.
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](https://fabricmc.net/use/) 0.17.3 or newer for Minecraft 1.21.10.
2. Download and install [Fabric API](https://modrinth.com/mod/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
---
## 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:
CatalystFX Team
