Skip to main content

Klump Files

Version History​

Build VersionChange DateChange TypeDescription
6760422025-06-21stableCurrent version

Overview​

The klump_files module is an auto-generated registry that contains a list of encrypted klump files available for loading. This module is generated by the klump.py build script and serves as a manifest for the klump loading system.

File Structure​

--Autogenerated by klump.py
return {
    -- List of klump file paths
}

Current State​

The file currently returns an empty table {}, indicating no klump files are registered in the current build.

Usage Example​

-- Load all registered klump files
local klump_files = require("klump_files")

for _, file in pairs(klump_files) do
    local klump_file = string.gsub(file, "klump/", "")
    local is_strings = string.sub(klump_file, 1, 8) == "strings/"
    
    if is_strings then
        klump_file = string.gsub(klump_file, "strings/", "")
    end
    
    local cipher = Profile:GetKlumpCipher(klump_file)
    if cipher ~= nil then
        if is_strings then
            LoadKlumpString(klump_file, cipher, true)
        else
            LoadKlumpFile(klump_file, cipher, true)
        end
    end
end

File Format​

Standard Klump Files​

return {
    "klump/images/quagmire_food_inv_images_potato.tex",
    "klump/images/quagmire_food_inv_images_hires_potato.tex", 
    "klump/anim/dynamic/potato.dyn",
    -- Additional asset files...
}

String Klump Files​

return {
    "klump/strings/STRINGS.NAMES.POTATO",
    "klump/strings/STRINGS.RECIPE_DESC.POTATO_SOUP",
    -- Additional string entries...
}

Generation Process​

Build Script Integration​

The klump.py script scans for encrypted assets and generates this file during the build process:

  1. Asset Discovery: Scans designated directories for .klump encrypted files
  2. Path Processing: Generates standardized paths with klump/ prefix
  3. File Generation: Creates the Lua module with the complete file list
  4. Build Integration: Updates the file as part of the automated build pipeline

File Categories​

Asset Files:

  • images/ - Texture and image files
  • anim/dynamic/ - Animation data files
  • sounds/ - Audio files (if applicable)

String Files:

  • strings/ - Localized text data
  • Format: strings/STRINGS.CATEGORY.ITEM_NAME

Integration with Klump System​

Loading Process​

  1. Module Import: require("klump_files") returns the file list
  2. Path Processing: Removes klump/ prefix for internal handling
  3. Type Detection: Identifies string files by strings/ prefix
  4. Cipher Resolution: Retrieves decryption keys from player profile
  5. Conditional Loading: Only loads files with valid ciphers

Festival Event Context​

The klump_files registry is primarily used during festival events:

  • Quagmire Festival: Contains food-related assets and strings
  • Event Activation: Files are loaded when festivals become active
  • Dynamic Content: Enables secure distribution of event-specific content

File Path Conventions​

Asset Path Format​

klump/[category]/[subcategory]/[filename].[extension]

Examples:

  • klump/images/quagmire_food_inv_images_potato.tex
  • klump/anim/dynamic/potato.dyn

String Path Format​

klump/strings/[string_hierarchy]

Examples:

  • klump/strings/STRINGS.NAMES.POTATO
  • klump/strings/STRINGS.RECIPE_DESC.POTATO_SOUP

Security Considerations​

Encrypted Content​

  • File Encryption: All listed files are encrypted klump assets
  • Cipher Dependency: Files cannot be loaded without valid decryption keys
  • Access Control: Player profiles control which ciphers are available

Content Distribution​

  • Secure Distribution: Encrypted files can be distributed without exposing content
  • Progressive Unlocking: Content becomes available as players earn ciphers
  • Event-Based Access: Ties content availability to festival participation

Performance Impact​

Loading Optimization​

  • Batch Processing: Enables efficient loading of multiple related files
  • Conditional Loading: Only attempts to load files with available ciphers
  • Progress Tracking: Used with IsKlumpLoaded() to prevent duplicate operations

Memory Considerations​

  • Registry Size: File list is kept minimal to reduce memory overhead
  • On-Demand Loading: Files are loaded only when needed during events
  • Cleanup Potential: Registry could support unloading unused content

Debugging and Development​

Empty Registry State​

The current empty state return {} indicates:

  • No encrypted assets are currently registered
  • Development/testing environment without klump content
  • Possible build configuration excluding encrypted content

Development Workflow​

-- Check available klump files during development
local files = require("klump_files")
print("Available klump files:", #files)
for i, file in ipairs(files) do
    print(i, file)
end
  • klump: Main encrypted file loading system
  • json: Used for parsing encrypted string data
  • events: Festival event system that triggers klump loading
  • Profile: Stores cipher keys for decryption

Build System Integration​

Automated Generation​

  • Script: klump.py generates this file automatically
  • Timing: Updated during build process before asset packaging
  • Dependencies: Requires access to encrypted asset directories
  • Output: Overwrites existing klump_files.lua with current asset list

Validation​

  • Asset Verification: Build script validates that listed files exist
  • Path Consistency: Ensures all paths follow established conventions
  • Cipher Compatibility: Verifies that encryption keys are properly generated

Future Considerations​

Potential Enhancements​

  • Categorization: Group files by event or content type
  • Metadata: Include file size, version, or dependency information
  • Validation: Add checksums or integrity verification data

Scalability​

  • Multiple Events: Support for various festival events beyond Quagmire
  • Version Management: Handle multiple versions of encrypted content
  • Selective Loading: More granular control over which files to load