phaser4-game-image-optimization

Phaser 4 image asset optimization

Global control integration

Control-plane boundary: may propose, may review, and may modify within the Work Item scope of the current user task, and must return to $phaser4-game-workflow-control audit and state transitions; only A4-A6 operation requests involving external writes, payment, real devices, destructive or external deletion, or release side effects request approval.

Explicit invocation only triggers a proposal and does not equal authorization to write. All inventory, candidate generation, replacement, and verification must enter phaser4-game-workflow-control; this Skill does not own global state or approval, and must not bypass diff audit and evidence gates.

Compress runtime image size while preserving visual quality, runtime behavior, and channel compatibility, and provide a reproducible optimization report.

Execution boundary

• Only when the user explicitly invokes $phaser4-game-image-optimization should a task be proposed; A0-A3 writes are directly based on the current task scope, and only A4-A6 operations with external writes, payment, real devices, destructive or external deletion, or release side effects request precise approval. Do not automatically invoke because the package size is large, it has entered the release phase, a build is executed, or tests are run.
• Treat this task as an explicitly triggered asset-domain task, and include it in A0-A3, local phases, and unified gates according to the actual actions; do not automatically add it to build scripts, Git hooks, or CI, and do not implicitly trigger it from release status.
• By default, only process PNG, JPEG, and WebP referenced by runtime code, asset manifests, or loading configuration within the project. Design source files, reference images, review evidence, screenshots, test fixtures, build artifacts, caches, and assets not referenced at runtime are out of scope.
• GIF, APNG, texture atlases, normal maps, pixel art, nine-slice images, and images with special color spaces are high-risk assets; preserve their frame, pixel grid, channel, boundary, and metadata semantics, and process them only when the corresponding verification is executable.

Optimization process

1. Determine the user-specified directories, target channels, allowed formats, quality floor, and size targets. When no directory is specified, trace the actual runtime images from asset loading code, asset manifests, and build entry points, and do not perform broad scans of paths outside the project or the entire disk.
2. Establish a pre-compression baseline, record each file's path, reference location, format, byte size, width and height, alpha channel, animation or atlas attributes, and summarize the total size. Use content hashes to identify duplicate files, but do not merge or delete them without reference analysis.
3. Generate results in a separate candidate directory; directly overwriting original files is prohibited. Record the optimization tool, pinned version, complete parameters, and exit status; prioritize reusing the project's existing tools, and do not add runtime dependencies for one-off tasks.
4. By default, preserve the original format, dimensions, orientation, and file name:
   • For PNG, prioritize lossless metadata cleanup and lossless compression; use lossy palette quantization only when the quality floor allows it and transparent edges, gradients, and pixel differences are fully verified.
   • For JPEG, process only images that do not rely on transparency, use controlled-quality progressive compression, remove unnecessary metadata, and do not change EXIF orientation presentation.
   • For WebP, first determine whether it is already near optimal; keep the original file when repeated lossy encoding has no clear benefit.
   • Convert to WebP or AVIF only when the user permits format migration and the target channels, Phaser loaders, and fallback strategies have all been verified; update references, asset manifests, and loading configurations in sync, and do not retain duplicate runtime assets that have no references.
   • Sprite sheets, texture atlases, nine-slice assets, and pixel art must not be scaled, cropped, padded, rearranged, or have their frame coordinates changed; only compression of their image containers is allowed.
5. Perform structural and visual quality validation on each candidate: successful decoding; width, height, orientation, transparency, frame count, and atlas coordinates remain consistent; lossless candidates compare decoded pixels; lossy candidates check transparent edges, gradients, text, thin lines, pixel grids, and representative enlarged differences. When evidence is insufficient, keep the original file and mark it as "unverified".
6. Actually load the affected assets in Phaser and verify at least one referencing scene; when atlases, nine-slice assets, pixel art, or animations are involved, verify the corresponding runtime state. Then run the affected tests and production build to confirm there are no loading errors, path errors, sampling anomalies, or candidate files mistakenly entering the build.
7. Replace the original file only when the candidate is smaller in size and all applicable validations pass; if any validation fails, the size does not decrease, or the benefit is insufficient to offset visual quality and compatibility risks, keep the original file. After replacement, re-check references and version control differences to ensure the scope of changes includes only approved assets and necessary references.

Results report

Write the report at the location specified by the user or in the project's existing evidence directory; if neither exists, submit it directly in the task results, and do not create long-term process documentation without authorization. The report must at least include:

• Optimization scope, exclusions, target channels, tool versions, and parameters;
• For each file, the original size, optimized size, bytes saved and ratio, and the reason for keeping or rejecting it;
• Total size before and after comparison, listing separately the actual changes in source assets and in the production build;
• Evidence for structure, visual quality, Phaser runtime, tests, and production build;
• Reference modifications resulting from format migration, unverified items, remaining risks, and rollback methods.

Do not use "command succeeded" as a substitute for visual quality and runtime validation, and do not claim size savings when the pre-compression baseline is missing.