PaintMyKI5/README.md

PaintMyKI5

A Project Zomboid Build 42 mod that lets players repaint supported KI5 vehicles in singleplayer, hosted multiplayer, and dedicated servers.

Painting vehicles

Stand outside a supported, stopped vehicle and right-click it, then choose Paint vehicle. The window shows every scanned skin, its raw texture preview, and the paint available in your carried inventory (including nested bags).

Every repaint costs exactly one full B42 paint bucket worth of material. B42 paint buckets use UseDelta = 0.1, giving 10 uses per bucket. Those 10 uses are split fractionally across the selected texture's scanned colors. A 60% gray/20% green/20% white skin therefore costs 6 gray, 2 green, and 2 white uses. Small color percentages are retained rather than rounded away.

Painting uses a networked timed action. On multiplayer servers, the server rechecks the vehicle, selected skin, distance, movement, unchanged starting skin, and the acting player's paint immediately before it consumes anything. The server then applies and broadcasts the skin. The painting action never accepts costs or inventory totals supplied by the client.

This protects the mod's normal painting flow. Build 42 also contains a generic vanilla vehicle/setSkinIndex command used by other game tooling; hardening or removing that unrelated base-game command is outside this mod's scope.

Vehicle color scanner

The scanner:

• searches D:\SteamLibrary\steamapps\workshop\content\108600 by default;
• deduplicates root and versioned mod.info files requiring damnlib;
• selects the newest installed 42.x content layer;
• identifies self-propelled cars from their vehicle scripts;
• maps each skin texture to its exact in-game ID, such as Base.92nissanGTR; and
• discovers the 15 full paint buckets from the installed B42 game data;
• prints pixel-derived percentages using exact item IDs such as Base.PaintGreen, Base.PaintGrey, and Base.PaintWhite; and
• writes the exact proportional use requirements consumed by the in-game menu.

The tool reads the authoritative palette from ISPaintMenu.lua and verifies each entry against the bucket definitions in drainable.txt. Empty buckets and spray paint are excluded. Pixels are matched to the nearest paint color in perceptual Lab color space.

The development tool and its tests live under scanner/. Install Python 3.11 or newer, then run it from the repository root:

python -m pip install -r scanner/requirements.txt
python -m scanner --quiet

By default it writes the complete runtime data table to:

42.20/media/lua/shared/PaintMyKI5/PaintMyKI5VehiclePaintData.lua

The in-game menu reads PaintMyKI5.VehiclePaintData. The generated table contains the palette, 10-use bucket capacity, exact vehicle IDs, zero-based skin indices, texture references, Workshop/mod metadata, paint item IDs, percentages, and proportional uses. It excludes local absolute paths and timestamps, so identical inputs produce identical Lua.

To scan another Steam library:

python -m scanner --quiet --workshop-root "E:\SteamLibrary\steamapps\workshop\content\108600"

If Project Zomboid itself is installed elsewhere, pass both locations:

python -m scanner --quiet `
  --game-root "E:\SteamLibrary\steamapps\common\ProjectZomboid" `
  --workshop-root "E:\SteamLibrary\steamapps\workshop\content\108600"

Run the tests with:

python -m unittest discover -s scanner/tests -v

The headless Lua logic and syntax checks use Lupa without adding a runtime dependency to the mod:

uv run --with lupa python scanner/tests/run_lua_tests.py