Disclosure: This draft was generated with AI and checked against the cited primary sources, with a separate AI editorial review. It was prepared for the FrameSprite team, which has a commercial interest in FrameSprite. Proposed examples are not executed tests unless explicitly identified as recorded fixture results.
Validate every filename component against destination platforms before publishing an asset ZIP. An archive may store names that normal Windows tools cannot create as intended. Reserved device names and trailing characters need a portability check separate from image validity.
Key Takeaways
- Check directory components as well as PNG basenames.
- Rename through a recorded mapping and update consumers.
- Test extraction with the platforms and tools you support.
A valid archive is not a portable folder
Microsoft's file naming documentation describes Windows name restrictions. A reserved device basename is not made ordinary by adding a PNG extension. A directory component can also cause trouble.
Do not infer portability from successful upload or an archive listing. Those show that a service accepted the container, not that a recipient can create all entries. Separately hosted preview images can conceal the issue if upload software renamed them.
Audit names before assembling the release
Define the recipient platforms, then list every archive member and inspect its components. Keep the policy conservative enough for those recipients. A package does not need every name accepted by an unusual filesystem namespace.
Use path utilities for path handling, while keeping explicit platform validation separate. Generic normalization is not a complete Windows-name validator. Check reserved names, trailing spaces or periods, and project-specific restrictions.
Maintain a source-to-delivery map. An internal source can keep an established name while its public export uses a portable identifier. Update the manifest, examples, and documentation together so they agree on the output name.
Example: the console prop
A communications-terminal prop is exported as CON.png. The ZIP inventory looks ordinary, but a Windows recipient cannot extract that member normally. A sample level then lacks the terminal while neighboring props appear correctly.
Rename the delivery to terminal-console.png, update references, rebuild the archive, and validate that assembled package. Do not depend on a special extraction workaround for ordinary supported use.
This is different from letter-case mismatch. Capitalizing or lowercasing the reserved basename is not a complete portability repair. The naming audit should explain which mechanism rejected a member so the artist can fix the source naming rule.
Verify extraction and content separately
The Python ZIP documentation provides archive inspection interfaces. Use a listing to catch suspicious names before extraction, then test with actual recipient tools because their handling and error reporting may differ.
Accept the package when its names satisfy the declared policy, references resolve to the renamed outputs, and clean extraction produces the complete inventory. Check for silently skipped members as well as visible errors.
Keep the mapping and naming policy with the release. Otherwise a later regeneration can reintroduce the old name even though one manually corrected ZIP worked.
This is a proposed portability check. The example was not extracted on Windows for this article, and it does not establish support for every filesystem or archive program.
Related workflow
See sprite assets case sensitive path export for the adjacent failure. Keep the animation handoff checklist with the package and record visual decisions in the art reference board.
Prepared by the FrameSprite Workflow Team. Editorial method · Corrections. Primary documentation checked 2026-10-20.
Top comments (0)