Early Input Guard

A small client-side NeoForge mod that stops a class of startup crash in large modpacks: a mouse click or key press (or an automatic per-tick event) being dispatched to another mod's input/tick listener before that mod has registered its keybinds — so the listener dereferences a null KeyMapping and the game hard-crashes.

• Minecraft: 1.21.1
• Loader: NeoForge (21.1.x)
• Side: client only

The problem

In heavily-modded packs the client renders frames and polls input while the loading screen is still up, and FML may finish loading in a degraded state. Two things can leave a mod's keybind fields null when its listeners run:

1. During the loading screen — input is polled before every mod's RegisterKeyMappingsEvent handler has run.
2. In a broken mod state — if any mod fails to construct, FML "cowardly refuses" to fire the client registration events (including RegisterKeyMappingsEvent) for the rest of the session, so keybinds are never assigned, yet NeoForge keeps dispatching input and per-tick events.

A single click in either situation reaches a listener like Quark's HotbarChangerModule or Arknights Endfield's KeyInputHandler and crashes with:

java.lang.NullPointerException: Cannot invoke "net.minecraft.client.KeyMapping.isDown()"
because "...changeHotbarKey" is null

What it does

It mixes into NeoForge's ClientHooks and short-circuits the relevant dispatch hooks while it is unsafe to deliver events to mod listeners:

Hook	Guarded
onMouseButtonPre / onMouseButtonPost	mouse clicks
onMouseScroll	scroll
onKeyInput	key presses
fireClientTickPre / fireClientTickPost	per-tick mod events

Suppression conditions:

• Input is dropped when mod loading has errored (ModLoader.hasErrors()) or a LoadingOverlay is active.
• Ticks are dropped when mod loading has errored. Suppressing ticks during a healthy loading screen is opt-in via config (see below), since some mods legitimately tick during loading.

This does not hide problems: NeoForge's loading-error screen still renders and its buttons still work (they dispatch through Screen.mouseClicked, a different path), so you can read the errors and quit cleanly instead of being thrown into a crash report. It also has no effect on a healthy, fully-loaded game — by then nothing is suppressed.

Config

config/earlyinputguard-client.toml:

Option	Default	Effect
suppress_ticks_during_loading_screen	false	Also suppress client tick dispatch while a loading screen is active, not just in a broken mod state.

Building

Requires JDK 21.

./gradlew build

The mod jar is written to build/libs/.

License

MIT