### Example *_paper_part.json File

Source: https://github.com/comunidadaylas/packsquash/wiki/Tips-and-resources-for-pack-authoring

Partial override file to be merged into the main item model.

```json
{
  "overrides": [
    { "predicate": { "custom_model_data": 2 }, "model": "item/paper_2" }
  ]
}
```

--------------------------------

### Example paper.json File

Source: https://github.com/comunidadaylas/packsquash/wiki/Tips-and-resources-for-pack-authoring

Base item model file structure containing initial overrides.

```json
{
  "parent": "item/generated",
  "textures": {
    "layer0": "item/paper"
  },
  "overrides": [
    { "predicate": { "custom_model_data": 1 }, "model": "item/paper_1" }
  ]
}
```

--------------------------------

### Example Base Item Model File

Source: https://github.com/comunidadaylas/packsquash/wiki/Tips-and-resources-for-pack-authoring

This is an example of a base item model JSON file that will be used as the foundation for merging overrides.

```json
{
  "parent": "item/generated",
  "textures": {
    "layer0": "item/paper"
  }
}
```

--------------------------------

### Apply comprehensive PackSquash configuration

Source: https://github.com/comunidadaylas/packsquash/blob/master/docs/wiki/Options-files.md

This example demonstrates the full range of available global and per-file options. Use caution as explicit settings may become obsolete in future versions.

```toml
# Lines that start with # are comments, and PackSquash ignores them.
# You can also start a comment in the middle of a line with #, that
# spans until the end of the line

# Global options
pack_directory = 'C:\path\to\pack'
output_file_path = 'C:\path\to\result\pack\zip\file\my_pack.zip'
recompress_compressed_files = true
zip_compression_iterations = 5
automatic_minecraft_quirks_detection = true
# The value of this option is ignored due to automatic quirk detection
# being enabled, but this usually does not matter
work_around_minecraft_quirks = ['grayscale_images_gamma_miscorrection', 'restrictive_banner_layer_texture_format_check', 'bad_entity_eye_layer_texture_transparency_blending', 'java8_zip_parsing', 'ogg_obfuscation_incompatibility', 'png_obfuscation_incompatibility']
automatic_asset_types_mask_detection = true
allow_mods = ['OptiFine', 'Minecraft Transit Railway 3']
skip_pack_icon = true
validate_pack_metadata_file = true
ignore_system_and_hidden_files = false
zip_spec_conformance_level = 'high'
# These two are actually ignored due to the ZIP spec conformance level
size_increasing_zip_obfuscation = true
percentage_of_zip_structures_tuned_for_obfuscation_discretion = 100
never_store_squash_times = true
# System dependent values. PackSquash automatically uses appropriate
# defaults for your system, so usually you should not need to set
# these
threads = 4
spooling_buffers_size = 128 # MiB
zip_comment = 'Created with PackSquash'

# Per-file options below

# A special silence file that for some reason must be kept exactly as-is
# (usually not the case)
['assets/craftmine/sounds/special_silence.ogg']
empty_audio_optimization = false

# Audio several hours long that would take a lot of time to transcode,
# optimize and validate
['assets/craftmine/sounds/forest_soundscape.ogg']
transcode_ogg = false
two_pass_vorbis_optimization_and_validation = false

# Other Ogg files do not get transcoded
['**/*?.ogg']
transcode_ogg = false

# Lossless music files get pitch shifted, compressed with good quality,
# and obfuscated if allowed by the target Minecraft version
['**/*?.{flac,wav}']
ogg_obfuscation = true
channels = 2
sampling_frequency = 44100
target_pitch = 1.5
bitrate_control_mode = 'VBR'
target_bitrate_control_metric = 128
```

--------------------------------

### Install PackSquash via APT

Source: https://github.com/comunidadaylas/packsquash/wiki/Getting-started

Update the package list and install the PackSquash package using the system package manager.

```shell
apt update
apt install packsquash
```

--------------------------------

### Example Override File Content

Source: https://github.com/comunidadaylas/packsquash/wiki/Tips-and-resources-for-pack-authoring

This is an example of a JSON file containing overrides that can be merged into a base item model file.

```json
{
  "overrides": [
    {
      "predicate": {
        "custom_model_data": 1
      },
      "model": "custom/ui/buttons/play_button"
    }
  ]
}
```

--------------------------------

### Example override part files

Source: https://github.com/comunidadaylas/packsquash/blob/master/docs/wiki/Tips-and-resources-for-pack-authoring.md

Individual JSON files containing specific override predicates to be merged.

```json
{
  "overrides": [
    {
      "predicate": {
        "custom_model_data": 1
      },
      "model": "custom/ui/buttons/play_button"
    }
  ]
}
```

```json
{
  "overrides": [
    {
      "predicate": {
        "custom_model_data": 12000
      },
      "model": "custom/npc/bank_piglin"
    }
  ]
}
```

--------------------------------

### Manage rustfmt code formatting

Source: https://github.com/comunidadaylas/packsquash/blob/master/CONTRIBUTING.md

Commands to install and execute the standard Rust code formatter.

```bash
rustup component add rustfmt
```

```bash
cargo fmt
```

--------------------------------

### Basic PackSquash Options File

Source: https://github.com/comunidadaylas/packsquash/wiki/Options-files

A simple options file demonstrating common global settings for PackSquash. Use this as a starting point for basic compression tasks.

```json
{
  "pack_directory": "source/",
  "output_file_path": "output.zip",
  "recompress_compressed_files": true
}
```

--------------------------------

### Manage Clippy static analysis

Source: https://github.com/comunidadaylas/packsquash/blob/master/CONTRIBUTING.md

Commands to install and execute the Clippy linter for code quality improvements.

```bash
rustup component add clippy
```

```bash
cargo clippy
```

--------------------------------

### Example Merged Item Model File

Source: https://github.com/comunidadaylas/packsquash/wiki/Tips-and-resources-for-pack-authoring

This is the resulting merged item model file after applying the jq filter to combine a base file with override files.

```json
{
  "parent": "item/generated",
  "textures": {
    "layer0": "item/paper"
  },
  "overrides": [
    {
      "predicate": {
        "custom_model_data": 1
      },
      "model": "custom/ui/buttons/play_button"
    },
    {
      "predicate": {
        "custom_model_data": 12000
      },
      "model": "custom/npc/bank_piglin"
    }
  ]
}
```

--------------------------------

### PackSquash CLI Help and Version

Source: https://context7.com/comunidadaylas/packsquash/llms.txt

Display help information or the current version of PackSquash.

```bash
packsquash --help
```

```bash
packsquash --version
```

--------------------------------

### Add PackSquash APT Repository

Source: https://github.com/comunidadaylas/packsquash/wiki/Getting-started

Run this command as root to add the PackSquash repository and its signing key to your system sources.

```shell
mkdir -p /etc/apt/keyrings && \
wget -O /etc/apt/keyrings/packsquash.key https://deb.packages.packsquash.aylas.org/public.key && \
echo 'deb [signed-by=/etc/apt/keyrings/packsquash.key] https://deb.packages.packsquash.aylas.org/debian stable main' > /etc/apt/sources.list.d/packsquash.list
```

--------------------------------

### Download and Set Up PackSquash CLI

Source: https://github.com/comunidadaylas/packsquash/wiki/Integrating-PackSquash-with-ItemsAdder

This script checks if the PackSquash command is available. If not, it downloads the appropriate CLI version based on the system architecture, extracts it, and makes it executable. It also sets up a default configuration file if one doesn't exist.

```bash
if ! command -v packsquash &> /dev/null;
then
  if [ ! -f "packsquash" ]; then
    echo "packsquash command not found, downloading CLI version..."
    wget -O packsquash-cli.zip "https://github.com/ComunidadAylas/PackSquash/releases/download/${PACKSQUASH_VERSION}/PackSquash.CLI.executable.$([[ "$(uname -m)" == "x86_64" ]] && echo "x86_64" || echo "aarch64")-unknown-linux-musl.zip"
    unzip packsquash-cli.zip
    rm packsquash-cli.zip
    chmod +x packsquash
    PACKSQUASH_COMMAND="./packsquash"
  else
    PACKSQUASH_COMMAND="./packsquash"
  fi
else
  PACKSQUASH_COMMAND="packsquash"
fi

if [ ! -f "packsquash.toml" ]; then
  echo "PackSquash config does not exist, making a default one..."
  echo -e "pack_directory = 'workdir'\noutput_file_path = 'pack.zip'" > packsquash.toml
fi
```

--------------------------------

### Execute PackSquash via command line

Source: https://github.com/comunidadaylas/packsquash/blob/master/docs/wiki/Options-files.md

Runs the PackSquash executable with a specified settings file on Windows.

```text
"C:\path\to\your\packsquash\executable\packsquash.exe" "C:\path\to\your\settings\file.toml"
```

--------------------------------

### Configure Properties and NBT File Options

Source: https://context7.com/comunidadaylas/packsquash/llms.txt

Optimize OptiFine properties files and compressed NBT structure files. Control NBT compression iterations for Zopfli.

```toml
# OptiFine properties files (requires allow_mods = ['OptiFine'])
['**/*?.properties']
MINIFY_PROPERTIES = true
```

```toml
# Compressed NBT structure files
['data/*/structures/**/*?.nbt']
nbt_compression_iterations = 15          # Zopfli iterations (0-255)
```

```toml
# Example: Maximum NBT compression
['data/*/structures/important/**/*?.nbt']
nbt_compression_iterations = 20
```

--------------------------------

### Integrate PackSquash in GitLab CI/CD

Source: https://github.com/comunidadaylas/packsquash/wiki/Getting-started

Example job configuration for running PackSquash within a GitLab pipeline using Docker-in-Docker.

```yaml
build-job:
  stage: build
  image: docker:20.10.16
  variables:
    # Comes from dind service name (e.g., docker:20.10.16-dind).
    # If you rename it to something else DOCKER_HOST variable will need to be adjusted
    DOCKER_HOST: tcp://docker:2375
    DOCKER_TLS_CERTDIR: ""
  services:
    - docker:20.10.16-dind
  before_script:
    - docker info
  script: |
    docker run -v "$(pwd)":"$(pwd)" --workdir "$(pwd)" \
    ghcr.io/comunidadaylas/packsquash:latest \
    packsquash.toml
  artifacts:
    paths:
      - pack.zip
```

--------------------------------

### Add/Replace Language Strings for All Minecraft Languages

Source: https://github.com/comunidadaylas/packsquash/blob/master/docs/wiki/Tips-and-resources-for-pack-authoring.md

Use this script to automate the process of adding or replacing language strings across all supported Minecraft languages. Ensure you have Node.js installed.

```javascript
const fs = require('fs');
const path = require('path');

const langDir = path.join(__dirname, 'assets', 'minecraft', 'lang');
const defaultLangFile = path.join(langDir, 'en_us.json');
const defaultLang = JSON.parse(fs.readFileSync(defaultLangFile, 'utf8'));

fs.readdirSync(langDir).forEach(file => {
  if (file.endsWith('.json') && file !== 'en_us.json') {
    const langFilePath = path.join(langDir, file);
    const langData = JSON.parse(fs.readFileSync(langFilePath, 'utf8'));

    for (const key in defaultLang) {
      if (!langData.hasOwnProperty(key)) {
        langData[key] = defaultLang[key];
      }
    }

    fs.writeFileSync(langFilePath, JSON.stringify(langData, null, 2));
    console.log(`Updated ${file} with missing keys from en_us.json`);
  }
});

console.log('Language string update complete.');

```

--------------------------------

### Pack File Processing Error Example

Source: https://github.com/comunidadaylas/packsquash/blob/master/docs/wiki/Troubleshooting-pack-processing-errors.md

This error message format indicates an issue encountered while processing a specific pack file. It includes the relative path to the file and a description of the error.

```text
! assets/minecraft/textures/blocks/block.png: PNG decode error: invalid signature
```

--------------------------------

### Build Pack Optimization Configuration Programmatically

Source: https://context7.com/comunidadaylas/packsquash/llms.txt

Construct `SquashOptions` programmatically to define detailed optimization settings for global and specific file types. This allows for fine-grained control over compression, transcoding, and other optimization strategies.

```rust
use packsquash::config::{
    SquashOptions, GlobalOptions, FileOptions,
    AudioFileOptions, PngFileOptions, JsonFileOptions,
    ZipSpecConformanceLevel, ColorQuantizationTarget,
    AudioBitrateControlMode, MinecraftQuirk
};
use std::path::PathBuf;
use std::num::NonZeroUsize;
use indexmap::IndexMap;
use enumset::EnumSet;

fn build_options() -> SquashOptions {
    // Configure global options
    let mut global_options = GlobalOptions::default();
    global_options.output_file_path = PathBuf::from("output.zip");
    global_options.zip_compression_iterations = 15;
    global_options.zip_spec_conformance_level = ZipSpecConformanceLevel::High;
    global_options.threads = NonZeroUsize::new(4).unwrap();
    global_options.recompress_compressed_files = true;
    global_options.automatic_minecraft_quirks_detection = true;

    // Configure per-file options with glob patterns
    let mut file_options = IndexMap::new();

    // Audio file options
    let audio_opts = AudioFileOptions {
        transcode_ogg: true,
        two_pass_vorbis_optimization_and_validation: true,
        empty_audio_optimization: true,
        channels: Default::default(),
        bitrate_control_mode: AudioBitrateControlMode::Cqf,
        target_bitrate_control_metric: Some(0.25),
        sampling_frequency: None,
        target_pitch: 1.0,
        ogg_obfuscation: false,
        ..Default::default()
    };
    file_options.insert(
        "**/*?.ogg".to_string(),
        FileOptions::AudioFileOptions(audio_opts)
    );

    // PNG file options
    let png_opts = PngFileOptions {
        image_data_compression_iterations: 10,
        color_quantization_target: ColorQuantizationTarget::Auto,
        skip_alpha_optimizations: false,
        downsize_if_single_color: true,
        png_obfuscation: false,
        ..Default::default()
    };
    file_options.insert(
        "**/*?.png".to_string(),
        FileOptions::PngFileOptions(png_opts)
    );

    // JSON file options
    let json_opts = JsonFileOptions {
        minify: true,
        delete_bloat: true,
        always_allow_comments: true,
        sort_object_keys: true,
    };
    file_options.insert(
        "**/*?.json".to_string(),
        FileOptions::JsonFileOptions(json_opts)
    );

    SquashOptions {
        pack_directory: PathBuf::from("/path/to/pack"),
        global_options,
        file_options,
    }
}

```

--------------------------------

### ZIP File Generation Error Example

Source: https://github.com/comunidadaylas/packsquash/blob/master/docs/wiki/Troubleshooting-pack-processing-errors.md

This error message format indicates an issue encountered during the ZIP file generation phase, rather than with a specific pack file. The path is replaced with a description of the error phase.

```text
Pack processing error: Error while performing a ZIP file operation: I/O error: Access is denied. (os error 5)
```

--------------------------------

### Configure Legacy Language and Command Function Files

Source: https://context7.com/comunidadaylas/packsquash/llms.txt

Optimize legacy .lang files and .mcfunction command files. Options include removing comments, empty lines, and BOM characters.

```toml
# Legacy language files (Minecraft 1.12.2 and older)
['**/*?.lang']
minify_LEGACY_LANGUAGE = true            # Remove comments and empty lines
STRIP_LEGACY_LANGUAGE_BOM = true         # Remove BOM from file start
```

```toml
# Command function files (data packs)
['data/*/functions/**/*?.mcfunction']
MINIFY_COMMAND_FUNCTION = true           # Remove comments and empty lines
```

--------------------------------

### Configure Shader File Options

Source: https://context7.com/comunidadaylas/packsquash/llms.txt

Control GLSL shader source transformation and minification. Choose between 'minify', 'prettify', or 'keep_as_is' strategies.

```toml
# Match all shader files
['**/*?.{vsh,fsh,glsl}']
# Transformation strategies: 'minify', 'prettify', 'keep_as_is'
shader_source_transformation_strategy = 'minify'
```

```toml
# Example: Preserve shader formatting
['assets/*/shaders/debug/**/*?.{vsh,fsh}']
shader_source_transformation_strategy = 'keep_as_is'
```

--------------------------------

### Running PackSquash with Options

Source: https://github.com/comunidadaylas/packsquash/blob/master/docs/wiki/Integrating-PackSquash-with-ItemsAdder.md

Execute PackSquash with a specified options file to compress and optimize the resource pack. The `pack_directory` and `output_file_path` in the options file are crucial.

```bash
packsquash --options packsquash.toml
```

--------------------------------

### Configure JSON File Options

Source: https://context7.com/comunidadaylas/packsquash/llms.txt

Manage minification, validation, and key sorting for JSON, MCMETA, and model files. Options include whitespace removal and comment handling.

```toml
# Match all JSON files
['**/*?.{json,jsonc,mcmeta,mcmetac}']
minify_JSON = true                       # Remove whitespace (default: true)
delete_bloat_keys = true                 # Remove superfluous metadata keys
always_allow_json_comments = true        # Allow comments in all JSON files
sort_json_object_keys = true             # Sort keys for better compression
```

```toml
# Example: Preserve formatting for specific files
['assets/*/blockstates/debug.json']
minify_JSON = false
delete_bloat_keys = false
```

```toml
# OptiFine model files (requires allow_mods = ['OptiFine'])
['**/*?.{jem,jemc,jpm,jpmc}']
minify_JSON = true
delete_bloat_keys = true
```

```toml
# BlockBench models (requires allow_mods = ['Minecraft Transit Railway 3'])
['**/*?.{bbmodel,bbmodelc}']
minify_JSON = true
```

--------------------------------

### Configure PackSquash Options

Source: https://context7.com/comunidadaylas/packsquash/llms.txt

Define optimization settings, compatibility, and performance parameters in a TOML file.

```toml
# PackSquash Options File - Complete Example
pack_directory = '/path/to/my_pack'
output_file_path = '/output/my_pack_optimized.zip'

# Global optimization settings
recompress_compressed_files = true
zip_compression_iterations = 20
zip_spec_conformance_level = 'high'
never_store_squash_times = false

# Minecraft compatibility
automatic_minecraft_quirks_detection = true
automatic_asset_types_mask_detection = true
allow_mods = ['OptiFine']

# Pack metadata
skip_pack_icon = false
validate_pack_metadata_file = true
ignore_system_and_hidden_files = true

# Performance
threads = 8
spooling_buffers_size = 512
zip_comment = 'Optimized with PackSquash v0.4.1'

# Audio: Default settings for all sound files
['assets/*/sounds/**/*?.{ogg,oga,mp3,wav,flac}']
transcode_ogg = true
two_pass_vorbis_optimization_and_validation = true
channels = 2
sampling_frequency = 40050
bitrate_control_mode = 'CQF'
target_bitrate_control_metric = 0.25
empty_audio_optimization = true

# Audio: High-quality music
['assets/*/sounds/music/**/*?.{ogg,flac}']
sampling_frequency = 44100
target_bitrate_control_metric = 0.5
```

--------------------------------

### `percentage_of_zip_structures_tuned_for_obfuscation_discretion` Option

Source: https://github.com/comunidadaylas/packsquash/wiki/Options-files

Configuration for tuning ZIP structures for obfuscation discretion.

```APIDOC
## `percentage_of_zip_structures_tuned_for_obfuscation_discretion`

### Description
If `zip_spec_conformance_level` is set to `disregard`, this option sets the approximate probability for each internal generated ZIP file structure to be stored in a way that favors additional discretion of the fact that protection techniques were used, as opposed to a way that favors increased compressibility. This option is ignored for other conformance levels.

- **0 (minimum value)**: Every ZIP record is stored favoring increased compressibility.
- **100 (maximum value)**: Every ZIP record is stored favoring increased discretion.
- **Other values**: Combine increased discretion and compressibility.

### Type
[Integer](https://toml.io/en/v1.0.0#integer) in the [0, 100] interval

### Default Value
`0`

### Example
```toml
percentage_of_zip_structures_tuned_for_obfuscation_discretion = 100
```
```

--------------------------------

### PackSquash CLI Basic Usage

Source: https://context7.com/comunidadaylas/packsquash/llms.txt

Execute PackSquash with a TOML options file. Options can also be read from standard input.

```bash
packsquash /path/to/options.toml
```

```bash
cat options.toml | packsquash -
```

--------------------------------

### Unzipping ItemsAdder Resource Pack

Source: https://github.com/comunidadaylas/packsquash/blob/master/docs/wiki/Integrating-PackSquash-with-ItemsAdder.md

Use the `unzip` command to extract the ItemsAdder generated resource pack. Ensure the command is available in your system.

```bash
unzip plugins/ItemsAdder/output/generated.zip
```

--------------------------------

### Custom Files: Force Include

Source: https://context7.com/comunidadaylas/packsquash/llms.txt

Forces the inclusion of specific custom files, such as README.txt, into the pack. Use for ensuring essential documentation or metadata files are always present.

```toml
['**/README.txt']
force_include = true
```

--------------------------------

### Implement VirtualFileSystem in Rust

Source: https://context7.com/comunidadaylas/packsquash/llms.txt

Create a custom filesystem by implementing the VirtualFileSystem trait to read pack files from non-standard sources.

```rust
use packsquash::vfs::{
    VirtualFileSystem, VfsFile, VfsPackFileIterEntry,
    VfsPackFileMetadata, IteratorTraversalOptions
};
use packsquash::RelativePath;
use tokio::io::AsyncRead;
use std::io;
use std::fs::FileType;
use std::path::{Path, PathBuf};
use std::time::SystemTime;

// Example: In-memory filesystem implementation
struct MemoryFileSystem {
    files: std::collections::HashMap<PathBuf, Vec<u8>>,
}

impl VirtualFileSystem for MemoryFileSystem {
    type FileRead = std::io::Cursor<Vec<u8>>;
    type FileIter = std::vec::IntoIter<Result<VfsPackFileIterEntry, io::Error>>;

    fn file_iterator(
        &self,
        root_path: &Path,
        _options: IteratorTraversalOptions
    ) -> Self::FileIter {
        let entries: Vec<_> = self.files.keys()
            .filter(|p| p.starts_with(root_path))
            .map(|path| {
                let relative = path.strip_prefix(root_path)
                    .unwrap()
                    .to_string_lossy()
                    .into_owned();
                Ok(VfsPackFileIterEntry {
                    relative_path: RelativePath::from_inner(
                        std::borrow::Cow::Owned(relative)
                    ),
                    file_path: path.clone(),
                })
            })
            .collect();
        entries.into_iter()
    }

    fn open<P: AsRef<Path>>(&self, path: P) -> Result<VfsFile<Self::FileRead>, io::Error> {
        let data = self.files.get(path.as_ref())
            .ok_or_else(|| io::Error::new(
                io::ErrorKind::NotFound,
                "File not found"
            ))?
            .clone();

        let size = data.len() as u64;
        Ok(VfsFile {
            file_read: std::io::Cursor::new(data),
            file_size_hint: size,
            metadata: VfsPackFileMetadata {
                modification_time: Some(SystemTime::now()),
            },
        })
    }

    fn file_type<P: AsRef<Path>>(&self, path: P) -> Result<FileType, io::Error> {
        // Return appropriate file type based on path
        unimplemented!("Return FileType for the path")
    }
}
```

--------------------------------

### Configure PNG File Options

Source: https://context7.com/comunidadaylas/packsquash/llms.txt

Control image compression, color quantization, and obfuscation for PNG textures. Adjust Zopfli iterations, dithering, and size limits.

```toml
# Match all PNG textures
['**/*?.png']
image_data_compression_iterations = 5    # Zopfli iterations (0-255)

# Color quantization targets: 'none', 'auto', 'one_bit_depth',
#                             'two_bit_depth', 'four_bit_depth', 'eight_bit_depth'
color_quantization_target = 'auto'
color_quantization_dithering_level = 0.85  # 0.0-1.0

# Size limits and optimizations
maximum_width_and_height = 8192
skip_alpha_optimizations = false
downsize_if_single_color = false

# Obfuscation (requires compatible Minecraft version)
png_obfuscation = false
```

```toml
# Example: Lossless compression for shader data textures
['assets/*/textures/shader_data/**/*?.png']
color_quantization_target = 'none'
skip_alpha_optimizations = true
```

```toml
# Example: Aggressive compression for large textures
['assets/*/textures/landscape/**/*?.png']
image_data_compression_iterations = 15
color_quantization_target = 'eight_bit_depth'
color_quantization_dithering_level = 1.0
```

--------------------------------

### Per-File Options: Shader Files

Source: https://github.com/comunidadaylas/packsquash/wiki/Options-files

Options specific to optimizing shader files.

```APIDOC
## Per-File Options: Shader Files

### shader_source_transformation_strategy
- **Type**: string
- **Description**: Strategy for transforming shader source code.

### is_top_level_shader
- **Type**: boolean
- **Description**: Indicates if the shader is a top-level shader.
```

--------------------------------

### Minimal PackSquash TOML Configuration

Source: https://context7.com/comunidadaylas/packsquash/llms.txt

A minimal TOML configuration file for PackSquash. Only 'pack_directory' is mandatory; others use defaults.

```toml
# Minimal options file - only pack_directory is required
pack_directory = '/path/to/my/resource_pack'

# Optional: Specify output file (default: pack.zip in current directory)
output_file_path = '/path/to/output/optimized_pack.zip'
```

--------------------------------

### Force inclusion of custom files

Source: https://github.com/comunidadaylas/packsquash/blob/master/docs/wiki/Options-files.md

Enables copying of custom files to the output ZIP without optimization.

```toml
force_include = true
```

--------------------------------

### Per-File Options: Custom Files

Source: https://github.com/comunidadaylas/packsquash/wiki/Options-files

Options for handling custom files.

```APIDOC
## Per-File Options: Custom Files

### force_include
- **Type**: boolean
- **Description**: Forces the inclusion of a custom file, even if it would normally be excluded.
```

--------------------------------

### Configure PackSquash for extreme compression

Source: https://github.com/comunidadaylas/packsquash/blob/master/docs/wiki/Options-files.md

This configuration increases compression iterations and enables specific optimizations for PNG and NBT files to achieve the smallest possible output size.

```toml
pack_directory = 'C:\path\to\pack'

recompress_compressed_files = true
zip_compression_iterations = 30
zip_spec_conformance_level = 'balanced'
skip_pack_icon = true

['**/*?.png']
image_data_compression_iterations = 15

['**/*?.nbt']
nbt_compression_iterations = 20
```

--------------------------------

### Per-File Options Configuration

Source: https://github.com/comunidadaylas/packsquash/blob/master/docs/wiki/Options-files.md

This section details how to use TOML tables to define custom compression options for files matching specific glob patterns. It covers the syntax for table names and how PackSquash applies these configurations.

```APIDOC
## Per-file Options

PackSquash supports customizing how several pack file types are compressed, on a per-file basis, via [tables](https://toml.io/en/v1.0.0#table). Tables represent a group of options that are applied to the files whose relative path matches a [extended glob pattern syntax](https://docs.rs/globset/0.4.8/globset/index.html#syntax) contained in the table name.

For matching, the path component separator is normalized to a forward slash (/), so the configuration files are operating system agnostic. Also, the `*` and `?` metacharacters can never match a path separator. The backslash character may be used to escape special characters.

**Example Glob Patterns:**
```glob
**/{music,ambience}/?*.{og[ga],mp3,wav,flac}
assets/*/sounds/{music,ambience}/?*.{og[ga],mp3,wav,flac}
```

**Note on Special Characters:** If your pattern contains a dot or characters that are not ASCII letters, ASCII digits, underscores, and dashes (A-Za-z0-9_-), you will need to put them in a string (i.e., between single quotes, like `'this'`) when writing the table name in the options file.

**Configuration Application:** PackSquash detects the file type on the fly. If several patterns match a single file, PackSquash will use the first one that customizes options appropriate for the file type. If no pattern is appropriate or no pattern matches, default options are used.
```

--------------------------------

### Automate PackSquash optimization with a shell script

Source: https://github.com/comunidadaylas/packsquash/wiki/Integrating-PackSquash-with-ItemsAdder

A bash script to automate the extraction and optimization of an ItemsAdder-generated resource pack. Ensure the script is made executable with chmod +x before running.

```bash
#!/bin/bash

# Path to the ItemsAdder generated ZIP file. Change accordingly
IA_RESOURCEPACK="plugins/ItemsAdder/output/generated.zip"

PACKSQUASH_VERSION=v0.4.0

# Set to true when using self-host hosting to replace the IA
# generated ZIP file with the result of PackSquash, to make IA
# automagically host the pack generated by PackSquash
AUTO_WRITEBACK=false

# Check unzip command is available
if ! command -v unzip &> /dev/null; then
  echo "Can't find unzip command!"
  exit 1
fi

# Check wget command is available
if ! command -v wget &> /dev/null; then
  echo "Can't find wget command!"
  exit 1
fi

# Check the resource pack path is set
if [ -z "${IA_RESOURCEPACK}" ]; then
  echo "Missing resource pack path!"
  exit 1
fi
```

--------------------------------

### Configuration: percentage_of_zip_structures_tuned_for_obfuscation_discretion

Source: https://github.com/comunidadaylas/packsquash/blob/master/docs/wiki/Options-files.md

Sets the probability for ZIP structures to favor obfuscation discretion over compressibility.

```APIDOC
## percentage_of_zip_structures_tuned_for_obfuscation_discretion

### Description
If zip_spec_conformance_level is set to disregard, this option sets the approximate probability for each internal generated ZIP file structure to be stored in a way that favors additional discretion of the fact that protection techniques were used.

### Parameters
- **percentage_of_zip_structures_tuned_for_obfuscation_discretion** (Integer) - Optional - Default: 0 (Range: 0-100)

### Request Example
```toml
percentage_of_zip_structures_tuned_for_obfuscation_discretion = 100
```
```

--------------------------------

### Per-File Options: Properties Files

Source: https://github.com/comunidadaylas/packsquash/wiki/Options-files

Options specific to optimizing properties files.

```APIDOC
## Per-File Options: Properties Files

### minify_properties
- **Type**: boolean
- **Description**: Minifies properties files.
```

--------------------------------

### Configure recompress_compressed_files

Source: https://github.com/comunidadaylas/packsquash/blob/master/docs/wiki/Options-files.md

Enables additional compression for already compressed file types like Ogg and PNG.

```toml
recompress_compressed_files = true
```

--------------------------------

### JSON: All JSON Files Optimization

Source: https://context7.com/comunidadaylas/packsquash/llms.txt

Enables optimization for all JSON, JSONC, MCMETA, and MCMETAC files. Includes minification, bloat key deletion, comment allowance, and key sorting.

```toml
['**/*?.{json,jsonc,mcmeta,mcmetac}']
minify_JSON = true
DELETE_BLOAT_KEYS = true
ALWAYS_ALLOW_JSON_COMMENTS = true
SORT_JSON_OBJECT_KEYS = true
```

--------------------------------

### Configure output_file_path

Source: https://github.com/comunidadaylas/packsquash/blob/master/docs/wiki/Options-files.md

Defines the destination path for the generated optimized ZIP file.

```toml
output_file_path = 'C:\path\to\result\pack\zip\file\my_pack.zip'
```

--------------------------------

### Global Options

Source: https://github.com/comunidadaylas/packsquash/wiki/Options-files

These options apply globally to the PackSquash process.

```APIDOC
## Global Options

### pack_directory
- **Type**: string
- **Description**: Specifies the directory containing the pack to be squashed.

### output_file_path
- **Type**: string
- **Description**: Sets the path for the output squashed file.

### recompress_compressed_files
- **Type**: boolean
- **Description**: If true, PackSquash will attempt to recompress files that are already compressed.

### zip_compression_iterations
- **Type**: integer
- **Description**: Number of iterations for ZIP compression. Higher values increase compression but take longer.

### automatic_minecraft_quirks_detection
- **Type**: boolean
- **Description**: Enables automatic detection of Minecraft-specific quirks.

### work_around_minecraft_quirks
- **Type**: boolean
- **Description**: Enables workarounds for detected Minecraft quirks.

### automatic_asset_types_mask_detection
- **Type**: boolean
- **Description**: Enables automatic detection of asset types.

### allow_mods
- **Type**: boolean
- **Description**: Allows PackSquash to process files associated with mods.

### skip_pack_icon
- **Type**: boolean
- **Description**: Skips processing the pack icon file.

### validate_pack_metadata_file
- **Type**: boolean
- **Description**: Validates the pack's metadata file.

### ignore_system_and_hidden_files
- **Type**: boolean
- **Description**: Ignores system and hidden files during processing.

### zip_spec_conformance_level
- **Type**: integer
- **Description**: Sets the ZIP specification conformance level.

### size_increasing_zip_obfuscation
- **Type**: boolean
- **Description**: Enables ZIP obfuscation techniques that may increase file size.

### percentage_of_zip_structures_tuned_for_obfuscation_discretion
- **Type**: float
- **Description**: Percentage of ZIP structures to tune for obfuscation discretion.

### never_store_squash_times
- **Type**: boolean
- **Description**: Prevents PackSquash from storing modification times within the ZIP archive.

### threads
- **Type**: integer
- **Description**: Number of threads to use for processing.

### spooling_buffers_size
- **Type**: integer
- **Description**: Size of spooling buffers in bytes.

### zip_comment
- **Type**: string
- **Description**: Adds a comment to the ZIP archive.
```

--------------------------------

### Optimize Resource Pack with PackSquash

Source: https://github.com/comunidadaylas/packsquash/wiki/Integrating-PackSquash-with-ItemsAdder

This script cleans the working directory, copies the resource pack, extracts its contents, optimizes it using PackSquash with the specified configuration, and optionally copies the optimized pack to the ItemsAdder output directory.

```bash
echo "Clean up workdir..."
rm -r workdir &> /dev/null

echo "Copy IA resource pack into current directory..."
cp "$IA_RESOURCEPACK" .

echo "Extract contents..."
unzip "$IA_RESOURCEPACK" -d "workdir"

echo "Optimize pack..."
$PACKSQUASH_COMMAND packsquash.toml

if [ "$AUTO_WRITEBACK" = true ]; then
  echo "Copying result to ItemsAdder output directory..."
  cp -r pack.zip "$IA_RESOURCEPACK"
fi

echo "Done!"
```

--------------------------------

### Run Rust tests

Source: https://github.com/comunidadaylas/packsquash/blob/master/CONTRIBUTING.md

Executes all unit tests within the project.

```bash
cargo test
```