Version: 1.18.1 | Requires: Project Zomboid Build 42.14.0+
Players: Subscribe on Steam Workshop — this mod is required by Phobos' Industrial Pathways: Biomass.
Modders & Developers: Full API reference in docs/. Bug reports and feature requests via GitHub Issues.
A shared utility library for Project Zomboid mods (Build 42 focused).
Used by: Phobos' Industrial Pathways: Biomass (Workshop) — 301-recipe industrial chemistry and biomass processing suite
- Provide stable, reusable helpers (sandbox vars, API probing, world scan, fluid helpers, etc.)
- Reduce duplicated Lua glue code across mods
- Improve resilience to minor B42 API changes through safe wrappers
| Module | Description |
|---|---|
| PhobosLib_Util | General-purpose utilities: safe method calling, API probing, keyword-based item search, modData helpers, player speech bubbles |
| PhobosLib_Fluid | Build 42 fluid container helpers with multi-strategy API fallbacks for add/drain/query operations |
| PhobosLib_World | World-scanning: tile iteration, object keyword search, generator detection, vehicle proximity checks |
| PhobosLib_Sandbox | Safe sandbox variable access with defaults, runtime mod detection, yield multiplier application, persistent one-shot flag consumption, mod-owned callback table creation for OnTest/OnCreate |
| PhobosLib_Quality | Generic quality/purity tracking: 0-100 scoring, tier lookup, equipment factors, severity scaling, yield penalties |
| PhobosLib_Hazard | PPE detection, respiratory protection assessment, mask filter degradation, EHR disease dispatch with vanilla stat fallback |
| PhobosLib_Skill | Perk existence checks, safe XP queries and awards, one-shot XP mirroring, persistent cross-skill XP mirror registration via Events.AddXP |
| PhobosLib_Reset | Generic inventory/recipe/skill reset utilities: deep inventory traversal, modData stripping, recipe removal, XP reset, item removal by module |
| PhobosLib_Validate | Startup dependency validation: register expected items/fluids/perks at load time, validate during OnGameStart, log missing entries with requesting mod ID |
| PhobosLib_Trading | Generic wrapper for Dynamic Trading mod API: lazy runtime detection, custom tag/archetype/item registration, batch item registration — all functions are no-ops when DynamicTrading is not installed; all DT calls are pcall-wrapped for mid-save safety |
| PhobosLib_Migrate | Versioned save migration framework: semver comparison, version tracking in world modData, migration registration with guard keys, incompatible version handler with skip/reset/abort policies, idempotent execution — mods register migration functions that run once per version upgrade |
| PhobosLib_Debug | Centralised debug logging: PhobosLib.debug(modId, ...) prints tagged messages when a mod's EnableDebugLogging sandbox option is true. Lazy per-mod caching |
| PhobosLib_Fermentation | Fermentation registry and progress tracking for items using ReplaceOnRotten as positive curing. Register items with label/totalHours, query progress (percent, remaining days, completion), stamp/read game dates, format short date strings |
| PhobosLib_RecipeFilter | (client) Crafting menu recipe visibility filter: register filter functions to hide/show craftRecipe entries based on sandbox settings or runtime conditions. Supports vanilla list view, vanilla grid view, and Neat Crafting mod compatibility |
| PhobosLib_Tooltip | (client) Generic tooltip line appender: register provider callbacks that append coloured text lines below the vanilla item tooltip for matching items. Uses full render replacement of ISToolTipInv.render() with expanded dimensions |
| PhobosLib_LazyStamp | (client) Lazy container condition stamper: register stampers that set item condition on unstamped items when the player opens a container. Useful for mods that repurpose item condition as a metadata channel (purity, charge level) |
| PhobosLib_VesselReplace | (client) Empty vessel replacement: register mappings that replace empty FluidContainer items with vanilla vessels (EmptyJar, Bucket, etc.) when the player opens a container. Supports bonus items (e.g. JarLid for jar-type vessels). MP-synced |
| PhobosLib_FarmingSpray | (client) Farming spray registration: register custom spray items that cure vanilla plant diseases (Mildew, Flies, Aphids, Slugs). Monkey-patches ISFarmingMenu and CFarming_Interact once on first registration. pcall-wrapped |
| PhobosLib_Power | (client) Powered workstation support: grid/generator/custom power detection, CraftBench UI gating (greyed craft button with tooltip), time-based generator fuel drain. Extensible via registerPowerSource() for alternative power mods |
| PhobosLib_Popup | (client) Generic popup system: first-time welcome guide with "Don't show again" checkbox, version-based "What's New" popup on major.minor bumps. Queue-based display, per-character persistence with MP sync |
| PhobosLib_WorkstationLabel | (client) Workstation label filter: removes untranslated tags (like CannotBeResearched) from crafting window "Requires: ..." text. Vanilla + Neat Crafting compatible |
| PhobosLib_WorldAction | (client) Generic world object context menu system: register custom right-click actions on world objects with requirement checks. Unavailable actions shown in red with reason tooltips |
| PhobosLib_EntityRebind | (server) Server-side entity rebinding for pre-existing world objects. Ensures workstations placed before a mod update get their new entity scripts applied on game load |
| PhobosLib_Moodle | (client) Moodle Framework soft dependency wrapper: register custom moodles, set/get moodle levels, detect Moodle Framework at runtime. No-op when Moodle Framework is not installed |
Usage: require "PhobosLib" loads all 13 shared modules into the global PhobosLib table. The 11 client/server-side modules (RecipeFilter, Tooltip, LazyStamp, VesselReplace, FarmingSpray, Power, Popup, WorkstationLabel, WorldAction, EntityRebind, Moodle) are loaded automatically by PZ from client/ and server/.
- As a dependency: your mod can require PhobosLib and call its helpers.
- As a vendored snippet source: small snippets may be copied with attribution, but depending on the library is preferred.
Public functions in PhobosLib should be treated as API surface. Changes should:
- avoid breaking signatures
- remain backwards compatible where possible
- include migration notes when breaking changes are unavoidable
- Module Overview & API Reference — All modules with function signatures, parameters, and descriptions
- Getting Started (for mod developers) — Add PhobosLib as a dependency, key modules, quick examples
- For Players — What PhobosLib is and why you have it
- FAQ — Common questions
See docs/README.md for the full index.
- LICENSE
- PROJECT_IDENTITY.md
- MODDING_PERMISSION.md
- CONTRIBUTING.md
After each intermediate or major version bump, verify:
- All
PhobosLib_*.luamodules load without errors inconsole.txt -
[PhobosLib:Validate]log lines appear when dependent mods register expectations -
PhobosLib.perkExists()correctly returns true/false for known/unknown perks -
PhobosLib.isModActive()correctly detects active mods - World modData strip/get functions work (test via EPR cleanup or manual)
- Recipe filters work:
[PhobosLib:RecipeFilter]log lines confirm UI overrides installed (vanilla or Neat Crafting) - Tooltip providers work:
[PhobosLib:Tooltip]log line confirms ISToolTipInv.render hook installed; hover over registered items to verify extra lines appear - Lazy stamper works:
[PhobosLib:LazyStamp]log line confirms OnRefreshInventoryWindowContainers hook installed - Migration framework works:
[PhobosLib:Migrate]log lines show version check and migration execution on game start - Vessel replacement works:
[PhobosLib:VesselReplace]log line confirms OnRefreshInventoryWindowContainers hook installed; empty FluidContainers replaced with vessels on container open - Farming spray works:
[PhobosLib:FarmingSpray]log line confirms ISFarmingMenu patch installed; registered sprays appear in "Treat Problem" submenu on diseased plants - Power module works:
[PhobosLib:Power]log line confirms hooks installed; powered entities grey out craft button when no power - Popup system works:
[PhobosLib:Popup]log lines confirm guide/changelog registrations; popups display on game start - Workstation label works:
[PhobosLib:WorkstationLabel]log line confirms hooks installed; no raw IGUI_CraftingWindow_ keys in workstation labels - No
nilorNullPointerExceptionerrors referencing PhobosLib in logs
- See CHANGELOG.md
- See VERSIONING.md