Grid & Flow

Grid & Flow is a Project Zomboid mod focused on rebuilding late-game infrastructure through industrial pumps, finite water reserves, utility substations, water plants, and power facilities.

The player goal is to move from local survival to civil restoration: first keeping a base supplied, then restoring water and electricity to zones, towns, and eventually the wider map.

The current primary gameplay target is Build 41. A separate Build 42 layout is now included in the same package for port validation: Build 41 uses the root mod.info + media/, while Build 42 uses 42/mod.info + 42/media/.

Current Features

• Industrial water pump item, components, crafting chain, placement cursor, timed install action, and pump UI.
• Flow Micro now uses the pump as a local building water-service machine: a placed, powered, primed, active pump links to a nearby building and lets vanilla water fixtures consume that building's finite 50000 water-unit reserve while global water is shut off.
• Priming a building service consumes one vanilla bucket of water and returns an empty bucket.
• Building water reserve belongs to the building service, not the pump item; disassembling or reinstalling the pump does not carry or reset reserve water.
• Only one pump can be active for the same linked building at a time.
• Industrial water filter housings and consumable filter cartridges are implemented. Unfiltered or exhausted-filter service provides contaminated water; a valid cartridge provides clean water.
• Looted filter housings generate an internal cartridge state between 20% and 100% when installed. Crafted cloth cartridges provide 2500 clean units or 5 active days; crafted cotton cartridges provide 5000 clean units or 10 active days.
• Dedicated Grid & Flow crafting category for all current mod recipes.
• The old Flow Micro pipe-network gameplay is removed from active scripts/runtime/assets: pipe recipes, pipe items, pipe loot injection, build-menu access, pipe placement commands, valve toggles, and custom outlet behavior are not registered.
• Placed pumps can be disassembled with the matching wrench, returning their item.
• Placed pumps expose condition and can be repaired with a wrench plus basic repair material.
• Custom first-pass inventory icons and packed world sprites exist for current Grid & Flow items.
• Translation folders for EN, ES, AR, PTBR, PT, IT, DE, FR, RU, CN, CH, KO, TR, PL, UA, TH, CS, and JP; Project Zomboid selects the matching folder automatically from the active game language.
• Expanded localization based on Project Zomboid player/review statistics while staying within vanilla-supported language folders.
• Server-authoritative pump state changes with distance, type, power, argument, and command-rate validation for multiplayer compatibility.
• Defensive placement/action checks for pumps so normal gameplay paths revalidate tools, materials, position, and occupied squares before creating world objects.
• Pump maintenance now only keeps local service state sane, deactivating pumps that lose power or lose access to a building reserve instead of refilling networks.
• Defensive loot injection into vanilla procedural distribution tables.
• Development safety gate: all Grid & Flow runtime Lua systems currently return early unless Project Zomboid is running with debug mode enabled.
• Macro facility framework skeleton: known utility facility definitions, local facility state, control-panel anchors, development PDC diagnostics, selected component repairs, facility startup, service-zone state, and industrial generator placement/connection/removal.
• Industrial generators now fuel macro facilities when upstream grid power is absent; restored upstream grid power turns connected industrial generators into backup power instead of consuming fuel.
• Facility diagnostics now show functional component names, component profiles, first-pass repair requirements, and a capped recent event log.
• Facility workflow now includes selected-component calibration before startup, plus first-pass degraded/failed health states and low-frequency degradation scaffolding disabled by default.
• Legacy Flow Micro piping work is archived only in an ignored local reference/ backup for future design reference; active runtime code no longer ships pipe-network objects, assets, menus, or commands.
• A narrow vanilla water fixture adapter exists for the local Flow Micro building reserve. Global vanilla adapters remain disabled by default; the water adapter can write WaterShutModifier only when explicitly enabled, using full restored-grid state in Build 41 and physical water-plant zone state in Build 42, while the electricity adapter remains scaffolded.
• Debug/admin facility tools can print, force online/offline, and reset facility state during development.
• Local-only aggregate usage counters for development reporting. Grid & Flow currently sends no telemetry or external analytics.

Planned Systems

Flow Micro

Local water infrastructure for bases and small installations:

• Pumps placed next to a building.
• Local finite building reserve with 50000 water units.
• Power-gated activation similar to a generator.
• Initial building-line priming before first activation.
• Reusable filter housing plus consumable cartridge for clean water.
• Contaminated local-service water when no valid cartridge is installed.
• One active pump per linked building.
• Vanilla fixture interactions from sinks and similar outlets inside the linked building while global water is off.
• Pipe networks, valves, reducers, caps, tees, custom outlets, pressure, buffers, leaks, and building couplings are removed from the active Flow Micro loop unless intentionally redesigned later.

Flow Macro

Public water restoration through physical water treatment plants:

• Control panels for facility diagnosis.
• Up to five damaged components selected from predefined facility locations.
• Multi-stage repairs, calibration, startup, and maintenance.
• Public water can run from restored grid power or from connected industrial generators.
• If local industrial generators run out of fuel before upstream grid power is restored, public water shuts down again.
• Build 42 uses Rosewood Water Plant as the first physical water-treatment loop for non-Louisville public water.
• Build 41 uses a restored-grid public-water fallback instead of requiring a physical water-treatment plant.

Grid Mid-Level

Zone-level electrical restoration through substations and relays:

• Control panels can be powered by upstream grid power or by a vanilla generator for diagnosis.
• Substations require one critical repair, industrial generator placement/connection when upstream power is absent, and activation.
• Restores electricity to assigned towns or map zones.
• Industrial generators become backup power after upstream grid power is restored.

Grid Macro

Regional electrical restoration through the Louisville Power Plant:

• Large facility repair loop with control panel, up to five damaged components, industrial generation if required, startup, and maintenance.
• Once online, downstream substations/relays and water plant panels can operate without local industrial generators.
• Restored grid power makes water restoration more stable and less fuel-dependent.

Planned Utility Locations

• Louisville Power Plant: X:12119 Y:1617
• Louisville South Substation: X:14764 Y:4085
• Muldraugh Substation: X:10382 Y:10091
• Riverside Relay: X:4849 Y:6284
• Irvington Substation: X:2190 Y:13894
• Rosewood Water Plant: X:8044 Y:15358

Coordinates are planning anchors and need in-game verification.

Development Notes

• ROADMAP.md tracks implemented and planned phases. Phase 1 covers the current Flow Micro feature loop, Phase 2 covers security hardening, and Phase 3 covers performance/optimization gates before macro systems begin.
• CHANGELOG.md must be updated with every implementation/content change.
• AGENTS.md stores the repo-specific workflow rules for Codex/automation, including no commits without user approval, validation commands, localization policy, licensing, and privacy rules.
• English is the source language for current active development; supported translation folders are kept in key parity with EN during approved localization sweeps.
• Shared Lua is split by responsibility: GridAndFlow_Core.lua for definitions/helpers, GridAndFlow_LocalWaterService.lua for the active building-reserve model, GridAndFlow_PumpFilter.lua for pump filter housing/cartridge state, GridAndFlow_Security.lua for validation/security gates, and GridAndFlow_State.lua for optimized state mutation.
• assets/source/ stores editable/source art and references for item icons, tile sprites, and future texture-pack rebuilds.
• tools/generate_gridandflow_textures.py regenerates the current icons, world sprites, atlas, and GridAndFlowPack.pack.
• docs/SECURITY.md tracks the current multiplayer/security posture, mitigated exploit classes, and residual limitations.
• docs/PERFORMANCE.md tracks current hot paths, optimization rules, and manual performance validation.
• docs/WORKSHOP.md tracks the local Steam Workshop package workflow and current development-preview warnings.
• docs/MODDING_API.md documents the current experimental helper surface for third-party facility and service-zone definitions.
• docs/MIGRATION.md tracks save-facing ids, schema markers, and future migration rules.
• docs/COMMAND_AUDIT.md, docs/FACILITY_VERIFICATION_TEMPLATE.md, docs/RELEASE_CHECKLIST.md, docs/BUG_REPORT_TEMPLATE.md, docs/COMPATIBILITY_REPORT_TEMPLATE.md, docs/BUILD42_PORT_NOTES.md, and docs/BUILD42_TEST_CHECKLIST.md keep the autonomous roadmap scaffolds testable.
• Build 42 has its own versioned script copy. Its item definitions mirror the B41 active item set, but recipes use the B42 craftRecipe format so B42 does not parse the B41 root recipe blocks.
• tools/prepare_workshop.ps1 builds a lean Workshop folder under Zomboid/Workshop/GridAndFlow.
• PRIVACY.md documents current local-only counters and the rule that future external analytics must be opt-in.
• reference/ is intentionally ignored by git and may contain local Project Zomboid reference files.
• The current build is debug-only. Outside debug mode, Grid & Flow menus, timed actions, loot injection, server commands, and pump maintenance do not register. Project Zomboid still loads static media/scripts definitions and texture packs before Lua can gate them.
• Change GridAndFlow.DEBUG_ONLY_RUNTIME in media/lua/shared/GridAndFlow_Core.lua to false if you need the runtime to load outside debug mode during local testing.
• Pump rotation art cleanup, final facility control-panel UI, verified zone bounds, zone restoration adapters, and macro public-service integration are planned after the local building water loop and facility skeleton have been validated in-game.

License

Grid & Flow uses a custom non-commercial mod license. See LICENSE for the full terms and NOTICE.md for the short distribution summary.

In short:

• Personal non-commercial Project Zomboid use is allowed.
• Free modpack and Steam Workshop collection inclusion is allowed when Grid & Flow is unmodified, credited, linked, and not used to charge for access.
• Voluntary donations to the author are allowed, but donations cannot unlock exclusive mod access, content, items, gameplay, support priority, or other benefits.
• Selling, paywalling, standalone reuploading, mirroring, commercial use, public forks, ports, translations, compatibility rewrites, or asset/code reuse require prior written permission.

Validation

Current static validation:

$files = Get-ChildItem -Path media\lua -Recurse -Filter *.lua | ForEach-Object { $_.FullName }; luac -p $files
git diff --check