Validation & debugging

Work from a baseline

Keep an untouched starter ZIP, use an extracted folder for edits, and make one change at a time. Test on a clean Fabric API + Sodium + Sulkan instance.

The mod’s parser smoke fixture uses sulkan_smoke:* selectors. Those are test interfaces, not gameplay terrain programs. Use the independent starter for your first gameplay effect.

Reload your snapshot

Packs are immutable snapshots. Save files, then disable and reselect the pack. File edits are not watched automatically.

Settings changes compile a candidate before replacement. A failed candidate retains the existing generation. Retired GPU resources survive until completion, so reloads can briefly hold both generations.

Read the first error

Open logs/latest.log in the active instance. Look for the first Sulkan validation/GLSL failure and its pass or source name. Includes preserve numeric source IDs and line information.

Error	Correction
Unknown field	Follow this version’s manifest fields
Missing file	Correct case and manifest-root-relative path
No producer	Add a writer for the referenced resource
Multiple writers	Give successive outputs separate names
Cycle / feedback	Separate current outputs from inputs; use history
Unequal outputs	Match a graphics pass’s output dimensions
Reserved binding	Rename custom samplers/buffers
Invalid choice	Include the default in finite numeric values
Device/format error	Use supported formats and smaller allocations

Memory and device limits

budgetMiB covers active image resources, history pairs, custom textures, buffers, requested snapshots, and shadows. Mips and volume depth count. Allocation overhead is additional.

It is an active-generation budget, not a global VRAM cap; two generations can coexist during reload. The runtime also checks texture size, storage formats, buffer ranges, descriptors, workgroups, and graphics-queue compute support.

Keep compute bounds checks even when your current viewport divides evenly by workgroup size.

Check more than one view

Test resize, weather/day/night, camera angles, water, dimension changes, and pack switching. For history, test teleporting and FOV changes. Keep performance comparisons tied to hardware, driver, resolution, and settings.

Share a useful report

Share a minimal failing pack and full log for pack problems. For loader issues include versions, GPU/driver, OS, and steps on GitHub Issues. Ask pack-development questions on Discord.

Support connects the community, issue tracker, and troubleshooting checklist.