Nutcracker Fire Warning

Nutcracker Fire Warning is a client-side BepInEx plugin for Lethal Company that adds readable shotgun timing warnings for Nutcracker enemies.

The plugin does not change enemy behavior, shotgun damage, networking, or game balance. It only displays local visual warnings based on the Nutcracker's current combat state and the game's firing timing.

Features

• World-space vertical warning bar beside each Nutcracker.
• Clear countdown while a Nutcracker is aiming.
• Red-white pulse during the predicted fire window.
• Recommended Nutcracker model state tint: white while chasing, red during the final fire window.
• Optional extra fire-window overlay for red-white pulse, clone shell, or screen-space fallback.
• Optional screen-space fallback rectangle.
• Yellow pre-aim danger indicator when the local player is in a risky shotgun line.
• Configurable warning distance, fire-window timing, pulse strength, and scan intervals.
• English config descriptions by default, with automatic Simplified Chinese descriptions when LC Chinese Project is detected.

Fire Timing

The warning follows the Nutcracker's in-game shotgun timing:

• 0.5s when the Nutcracker has enemyHP <= 1
• 1.3s when the held shotgun has one shell loaded
• 1.75s otherwise

The final fire-window warning activates shortly before the predicted shot. This window is configurable.

Configuration

The config file is created after first launch:

BepInEx/config/aueser.lethalcompany.nutcrackerfirewarning.cfg

Main options:

• EnableMod: Enables Nutcracker Fire Warning as a whole. When disabled, warning UI, model warnings, and fallback scans stop running.
• EnableUiFireWindow: Enables the world-space side warning bar, including countdown, fire-window pulse, reload bar, and pre-aim danger bar.
• EnableModelStateTint: Enables the recommended model state warning. Default: true. The model turns white while chasing a target and red during the final fire window.
• EnableModelOutlineFireWindow: Enables an extra fire-window-only model overlay. Default: false. Use it only when you also want the old red-white pulse, clone shell, or screen-space fallback.
• ModelOutlineMode: Selects model warning mode. MeshSilhouette uses model-based warning behavior; ScreenBox uses a screen-space fallback rectangle.
• ModelPulseMode: Selects SourcePulse, CloneShell, or Both.
• ModelPulseIntensity: Controls red-white pulse emission intensity.
• ModelPulseAlpha: Controls pulse color alpha.
• ModelChaseTintAlpha: Controls white chase-state model tint alpha.
• ModelChaseTintIntensity: Controls white chase-state model tint emission intensity.
• ModelFireWindowTintAlpha: Controls red fire-window model tint alpha.
• ModelFireWindowTintIntensity: Controls red fire-window model tint emission intensity.
• ModelWarningMaxDistance: Limits model warnings by distance. Set to 0 or lower to disable distance filtering.
• ModelWarningRequireCameraVisible: Requires the Nutcracker to be inside the local camera view before showing the model warning.
• ModelOutlineWidth: Controls ScreenBox line width and CloneShell expansion width.
• MeshOutlineScale: Extra scale multiplier for CloneShell mode.
• FireWindowSeconds: Seconds before the predicted shot when final warnings activate.
• PreAimMaxDistance: Maximum distance for the yellow pre-aim danger bar. Set to 0 or lower to disable the pre-aim bar.
• MonitorActiveScanInterval: Fallback scan interval while Nutcrackers are present. Default: 0.5.
• MonitorIdleScanInterval: Fallback scan interval while no Nutcrackers are present. Default: 2.0.
• EnableDebugLogs: Enables diagnostic logging.
• DumpModelAudit: Logs Nutcracker renderer and mesh information when model warning data is built.

Debug options are intended for troubleshooting and should normally remain disabled during regular play.

Config Language

Config entry names remain stable in English to avoid duplicate sections after upgrades. Descriptions are written in English by default.

When LC Chinese Project is installed, new config files and newly added config entries use Simplified Chinese descriptions. Detection uses the stable plugin GUID cn.codex.v81testchn or the installed V81TestChn.dll path and does not depend on the localization mod version number.

Installation

Install through a mod manager, or place the plugin folder under:

BepInEx/plugins/

Expected manual install layout:

BepInEx/plugins/NutcrackerFireWarning/NutcrackerFireWarning.dll

Compatibility Notes

This plugin is client-side and visual-only. Each player who wants the warning needs to install it locally.

SourcePulse is the recommended model warning mode. Some Unity game meshes are not readable at runtime, so shell-based mesh outlines may be less reliable on unmodified game assets.

License

Licensed under the MIT License.

Changelog

1.0.6

• Changed the default model warning setup so EnableModelStateTint is enabled and EnableModelOutlineFireWindow is disabled for newly generated configs.
• Clarified config descriptions: EnableModelStateTint is the recommended white-chase/red-fire model warning, while EnableModelOutlineFireWindow is an optional extra fire-window overlay.

1.0.5

• Added optional model state tint warnings: white while a Nutcracker is chasing a target, red during the final fire window.
• Kept the existing world-space UI warning and red-white model pulse/outline warning available through config.
• Added EnableModelStateTint, chase tint alpha/intensity, and fire-window tint alpha/intensity config entries.
• Added automatic Simplified Chinese config descriptions when LC Chinese Project is detected.
• LC Chinese Project detection uses the stable plugin GUID or installed DLL path and does not depend on version numbers.

1.0.4

• Added EnableMod as a default-on master enable option.
• Reduced idle overhead by delaying warning object creation until aiming, reloading, or pre-aim danger tracking is relevant.
• Replaced per-frame reflection value reads with cached Harmony field references.
• Removed GetType().Name renderer checks and switched to strong renderer type checks.
• Reduced pre-aim danger checks by throttling line-of-sight tests and using cheaper angle filtering.
• Reduced countdown text allocations by caching countdown labels.
• Cached eligible model renderers for screen-box bounds and mesh warning updates.
• Increased fallback monitor defaults to reduce scan frequency.

1.0.3

• Fixed EnableUiFireWindow=false so it hides the entire world-space side warning bar instead of only disabling the final red-white pulse.
• Allowed PreAimMaxDistance=0 or lower to disable the yellow pre-aim danger bar.
• Updated config descriptions to match the actual UI behavior.

1.0.2

• Renamed the mod to Nutcracker Fire Warning.
• Added configurable Nutcracker model fire-window warnings.
• Added model warning mode selection with SourcePulse, CloneShell, and Both.
• Added configurable model pulse intensity and alpha.
• Added distance and camera-visibility filters for model warnings.
• Added configurable fallback scan intervals.
• Added configurable pre-aim warning distance.
• Improved material restoration when warning states end, components are disabled, or enemies are removed.
• Changed the default model warning path to SourcePulse for better reliability with runtime game assets.

1.0.1

• Added the world-space Nutcracker shotgun warning bar.
• Added final fire-window UI pulse and countdown.
• Added Nutcracker model fire-window warning support.
• Added debug logging and renderer audit output.
• Added fallback monitoring for Nutcracker combat state.

1.0.0

• Initial internal implementation.