Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/phobos-dthorga/mod-pz-phobos-lib

Shared utility library for Project Zomboid Build 42 mods — sandbox access, fluid helpers, quality tracking, hazard systems, and reset tools.
https://github.com/phobos-dthorga/mod-pz-phobos-lib

build-42 game-mod library lua mod-framework modding project-zomboid project-zomboid-mod

Last synced: 6 days ago
JSON representation

Shared utility library for Project Zomboid Build 42 mods — sandbox access, fluid helpers, quality tracking, hazard systems, and reset tools.

Awesome Lists containing this project

README 

          





  PhobosLib




# PhobosLib



![CI](https://github.com/phobos-dthorga/mod-pz-phobos-lib/actions/workflows/ci.yml/badge.svg)



**Version:** 1.18.1 | **Requires:** Project Zomboid Build 42.14.0+



> **Players:** Subscribe on [Steam Workshop](https://steamcommunity.com/sharedfiles/filedetails/?id=3668598865) — this mod is required by [Phobos' Industrial Pathways: Biomass](https://steamcommunity.com/sharedfiles/filedetails/?id=3668197831).

>

> **Modders & Developers:** Full API reference in [docs/](docs/). Bug reports and feature requests via [GitHub Issues](https://github.com/phobos-dthorga/mod-pz-phobos-lib/issues).



A shared utility library for Project Zomboid mods (Build 42 focused).



**Used by:** [Phobos' Industrial Pathways: Biomass](https://github.com/phobos-dthorga/mod-pz-chemistry-pathways) ([Workshop](https://steamcommunity.com/sharedfiles/filedetails/?id=3668197831)) — 301-recipe industrial chemistry and biomass processing suite



## Goals

- 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





  PhobosLib Modules




## Modules



| 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/`.



## Intended usage

- 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.



## Stability promise

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



## Documentation



- [Module Overview & API Reference](docs/architecture/diagrams/module-overview.md) — All modules with function signatures, parameters, and descriptions

- [Getting Started (for mod developers)](docs/guides/getting-started.md) — Add PhobosLib as a dependency, key modules, quick examples

- [For Players](docs/guides/for-players.md) — What PhobosLib is and why you have it

- [FAQ](docs/guides/faq.md) — Common questions



See [docs/README.md](docs/README.md) for the full index.



## Files to read

- LICENSE

- PROJECT_IDENTITY.md

- MODDING_PERMISSION.md

- CONTRIBUTING.md



## Verification Checklist



After each intermediate or major version bump, verify:



- [ ] All `PhobosLib_*.lua` modules load without errors in `console.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 `nil` or `NullPointerException` errors referencing PhobosLib in logs



## Release notes

- See CHANGELOG.md

- See VERSIONING.md