Pattern Library

🛠️ Pattern Library

30+ battle-tested code templates validated against production FS25 mods. These prevent common bugs and follow FS25 best practices.

---

🎩 Claude's Technical Tip

"Starting from a pattern is always safer than starting from scratch. Ask me for a 'pattern reference' before building any new feature." 🎩☕

---

Core Patterns

Pattern	File	What it solves
GUI Dialogs ⭐	gui-dialogs.md	MessageDialog base class, XML layout, dynamic loading
Network Events ⭐	events.md	Multiplayer sync with read/writeStream
Save / Load ⭐	save-load.md	XML-based savegame persistence
Managers	managers.md	Singleton global state across the session
Extensions	extensions.md	Hook Giants classes with appendedFunction + cleanup
Field Detection ⭐	field-detection.md	Detect player's current field reliably (4-tier + 3-tier fallback)
Data Classes	data-classes.md	OOP data containers with business logic
Message Center	message-center.md	Subscribe to HOUR_CHANGED, DAY_CHANGED, etc.
Async Operations	async-operations.md	Deferred/queued tasks without blocking
Financial Calculations	financial-calculations.md	Loans, depreciation, collateral
Physics Override	physics-override.md	Modifying vehicle/object physics
Shop UI	shop-ui.md	Custom buttons in the vehicle shop
Placeable Purchase	placeable-purchase-hooks.md	Dialog on placeable buy
Vehicle Info Box	vehicle-info-box.md	Custom HUD info panel

---

Advanced Patterns

Pattern	File	What it solves
Vehicle Specializations	vehicles.md	Full spec lifecycle: onLoad → onUpdate → readStream/writeStream
Placeables	placeables.md	Production points, interactive objects
Trigger Zones	triggers.md	Enter/leave collision callbacks
HUD Framework	hud-framework.md	Custom overlay elements (bottom-left origin!)
Animations	animations.md	TweenSequence, setAnimTrackTime, conditionals
Animal Husbandry	animals.md	AnimalHusbandryObject extension points
Production Chains	production-patterns.md	Multi-input/output PlaceableProductionPoint
Vehicle Configs	vehicle-configs.md	Wheel types, engine variants, custom configs

---

Critical Rules (Read These First)

1. Always use MessageDialog as dialog base — never DialogElement (causes white-box crash)
2. Never use onClose/onOpen as callback names — they conflict with GUI lifecycle methods
3. HUD mouseEvent must return true when consuming — or clicks fall through to the game world
4. Always uninstall appendedFunction hooks in delete() — they stack on savegame reload
5. Wrap getWorldTranslation() in pcall() — nodes can be invalidated at any time
6. g_fieldManager.fields is empty at startup — never call field detection in loadMap()

---

Community Credit

Patterns provided by @XelaNull via the FS25 AI Coding Reference — validated against an 83-file production mod (FS25_UsedPlus) with 30+ custom dialogs.

Additional patterns contributed from FS25_SoilFertilizer and FS25_NPCFavor development.