threejs-game-image-optimization

three.js image asset optimization

Global control integration

Control plane boundaries: may propose, may review, may modify within the Work Item scope of the current user task, and must return to $threejs-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 require approval.

Explicit invocation only triggers a proposal and does not equal authorization to write. All inventory, candidate generation, replacement, and verification must enter threejs-game-workflow-control; this Skill does not own global state or approvals, 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 boundaries

• Only when the user explicitly invokes $threejs-game-image-optimization should a task be proposed; A0-A3 writes are based directly on the current task scope, and only A4-A6 operations with external writes, payment, real devices, destructive or external deletion, or release side effects require precise approval. Do not automatically invoke due to a large package size, entering the release phase, executing a build, or running tests.
• Treat this task as an explicitly triggered asset-domain task, and incorporate it into 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 can be executed.

Optimization workflow

1. Determine the user-specified directory, target channels, allowed formats, quality floor, and size target. When no directory is specified, trace back from asset loading code, asset manifests, and build entry points to the actual runtime images, and do not perform broad scans of paths outside the project or the entire disk.
2. Establish a pre-compression baseline, recording per file the path, reference location, format, byte count, 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 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; prefer reusing existing project tools, and do not add runtime dependencies for a one-off task.
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 verification of transparent edges, gradients, and pixel differences is complete.
   • For JPEG, process only images that do not depend on transparency, use controlled-quality progressive compression and remove unnecessary metadata, without changing EXIF orientation presentation.
   • For WebP, first determine whether it is already close to optimal; when repeated lossy encoding has no clear benefit, keep the original file.
   • Convert to WebP or AVIF only when the user permits format migration and the target channel, ThreeJS loader, and fallback strategy have all been verified; update references, the asset manifest, and loading configuration in sync, and do not retain unreferenced duplicate runtime assets.
   • Sprite sheets, texture atlases, nine-slice images, and pixel art must not be scaled, cropped, padded, rearranged, or have their frame coordinates changed; only compression of their image container is allowed.
5. Perform structural and image-quality verification on each candidate: successful decoding; consistent width, height, orientation, transparency, frame count, and atlas coordinates; for lossless candidates, compare decoded pixels; for 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 "unverified".
6. Actually load the affected assets in ThreeJS and verify at least one referencing scene; when atlases, nine-slice images, pixel art, or animations are involved, verify the corresponding runtime state. Then run the affected tests and the 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 verifications pass; if any verification fails, the size does not decrease, or the benefit is insufficient to offset image-quality and compatibility risks, keep the original file. After replacement, recheck references and version control differences to ensure the scope of changes includes only the approved assets and necessary references.

Results report

Write the report to the location specified by the user or 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 include at least:

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

Do not substitute "command succeeded" for image-quality and runtime verification, and do not claim size savings when a pre-compression baseline is missing.