Assets Overview

Build Information

Current documentation based on build version: 676042 Last updated: 2025-06-21

System Purpose

The Assets infrastructure category provides fundamental file loading, data processing, and audio management capabilities for Don't Starve Together. These systems handle the low-level operations that enable secure content distribution, efficient audio playback, and data serialization throughout the game.

Key Responsibilities

• Secure encrypted file loading and decryption for festival content
• JSON data serialization and deserialization for game state persistence
• Audio file preloading and mix configuration management
• Asset registry maintenance for encrypted content distribution
• File format processing and data validation

System Scope

This infrastructure category includes all asset loading, file processing, and audio management systems but excludes high-level game content and user-facing functionality.

Architecture Overview

System Components

Assets infrastructure is organized around secure file handling, with encrypted content management, efficient audio processing, and robust data serialization forming the core technical foundation.

Data Flow

Asset Request → File Loading → Decryption/Processing → Memory Management
      ↓              ↓               ↓                     ↓
Content Access → Security Check → Data Validation → System Integration

Integration Points

• Data Management: Core file operations and save system integration
• System Core: Engine-level file loading and memory management
• User Interface: Asset loading for UI elements and audio feedback
• Networking: Secure content distribution and validation

Recent Changes

Build	Date	Component	Change Type	Description
676042	2025-06-21	JSON	stable	Current JSON processing system
676042	2025-06-21	Klump	stable	Encrypted file loading system
676042	2025-06-21	Audio Systems	stable	Audio mix and preloading systems

Core Asset Modules

JSON Processing

JSON encoding and decoding support for Lua data structures.

Module	Status	Description	Key Features
JSON	stable	Data serialization system	Game encoding, compliant encoding, decoding

Technical Capabilities:

• Game-specific string encoding for internal data persistence
• Standards-compliant encoding for external service integration
• Robust JSON parsing with comment support and error handling
• Null value handling for associative arrays

Encrypted Content Management

Secure file loading system for festival events and special content.

Module	Status	Description	Key Features
Klump	stable	Encrypted file loading system	Cipher-based decryption, asset loading
Klump Files	stable	Auto-generated asset registry	File manifest, build automation

Technical Capabilities:

• AES-encrypted asset protection with cipher key management
• Dynamic content loading based on festival event activation
• Automated asset registry generation during build process
• Secure localized string distribution and loading

Audio Management

Audio file preloading and mix configuration for optimized sound performance.

Module	Status	Description	Key Features
Mixes	stable	Audio mix configurations	Predefined mix states, priority system
Preload Sounds	stable	Sound file preloading system	Batch loading, DLC support

Technical Capabilities:

• Comprehensive audio mix definitions for different game states
• Priority-based audio mixing with automatic fallback handling
• Efficient sound file preloading with conditional DLC support
• FMOD integration for high-performance audio processing

Common Infrastructure Patterns

Secure Asset Loading

-- Load encrypted festival content
local cipher = Profile:GetKlumpCipher("images/special_asset.tex")
if cipher then
    LoadKlumpFile("images/special_asset.tex", cipher, false)
end

Data Serialization

-- Internal game data persistence
local game_data = {health = 100, items = {"axe", "berries"}}
local encoded = json.encode(game_data)
local decoded = json.decode(encoded)

-- External service communication
local api_data = {player = "Wilson", score = 1000}
local compliant_json = json.encode_compliant(api_data)

Audio State Management

-- Dynamic audio mixing based on game state
TheMixer:PushMix("normal")     -- Standard gameplay
TheMixer:PushMix("high")       -- Combat situation  
TheMixer:PushMix("death")      -- Player death
TheMixer:PopMix("death")       -- Respawn
TheMixer:PopMix("high")        -- Combat ends

Infrastructure Dependencies

Required Systems

• System Core: Engine integration for file I/O and memory management
• Data Management Core: Base data persistence and file system operations

Optional Systems

• Networking: Secure content distribution and validation
• User Interface: Asset loading for UI elements and feedback

Performance Considerations

System Performance

• Encrypted file loading optimized with cipher caching and batch operations
• JSON processing uses efficient string building and memory management
• Audio preloading reduces runtime loading overhead with strategic file batching
• Asset registry operations minimize file system access through build-time generation

Resource Usage

• Memory usage optimized through lazy loading and efficient caching strategies
• Encrypted content loaded only when festival events are active
• Audio files preloaded based on DLC availability and world configuration
• JSON operations use minimal memory allocation during encoding/decoding

Scaling Characteristics

• Klump system scales with number of active festival events
• JSON processing handles arbitrarily large data structures efficiently
• Audio preloading adapts to available DLC content and system capabilities
• Asset registry supports unlimited encrypted content files

Development Guidelines

Best Practices

• Always validate cipher availability before attempting encrypted file loading
• Use game-specific JSON encoding for internal data, compliant encoding for external APIs
• Preload audio files during initialization to prevent runtime loading delays
• Implement proper error handling for all file operations and data validation

Common Pitfalls

• Using compliant JSON encoding for internal game data persistence
• Loading encrypted content without checking festival event activation status
• Mixing audio priority levels incorrectly causing audio state conflicts
• Bypassing asset security validation for development convenience

Testing Strategies

• Test encrypted content loading with valid and invalid cipher combinations
• Verify JSON encoding/decoding with edge cases and malformed data
• Validate audio mix transitions under various game state scenarios
• Test asset loading performance under different memory and storage constraints

Related Systems

System	Relationship	Integration Points
Data Management	Parent Category	File operations, save system integration
System Core	Engine Integration	Low-level file I/O, memory management
Game Mechanics	Content Consumer	Festival events, achievement data
User Interface	Asset Consumer	UI elements, audio feedback

Troubleshooting

Common Infrastructure Issues

Issue	Symptoms	Solution
Encrypted files not loading	Missing festival content	Verify cipher availability and event activation
JSON parsing failures	Data corruption or load errors	Check data format and validate input
Audio mix conflicts	Incorrect audio levels	Review mix priority and stack management
Asset registry errors	Build-time loading failures	Regenerate klump_files.lua manifest

Debugging Infrastructure

• Use debug output in klump loading to trace cipher resolution and file access
• Validate JSON data structures using decode/encode round-trip testing
• Monitor audio mix stack state using TheMixer debug functions
• Check file system permissions and path accessibility for asset loading

Security Considerations

Asset Protection

• Encrypted content uses AES encryption with server-distributed cipher keys
• Cipher storage secured through player profile system with validation
• Asset loading restricted to authorized festival content only
• File system access limited to designated game directories

Data Integrity

• JSON encoding includes validation for supported data types
• Encrypted file loading verifies cipher validity before decryption
• Audio file loading includes format validation and error handling
• Asset registry maintains integrity through automated generation

Performance Monitoring

Key Metrics

• Encrypted file loading time and cipher resolution performance
• JSON encoding/decoding throughput for large data structures
• Audio preloading completion time and memory usage
• Asset registry loading performance during game initialization

Optimization Strategies

• Cache frequently accessed cipher keys to reduce profile lookups
• Batch related asset loading operations to minimize I/O overhead
• Use streaming audio loading for large sound files when appropriate
• Optimize JSON string building operations for large data structures

Future Development

Extensibility Design

• Klump system supports additional encryption methods and content types
• JSON processing can be extended with custom data type handlers
• Audio system accommodates new mix configurations and priority levels
• Asset registry supports multiple content distribution methods

Integration Planning

• New asset types should leverage existing security and loading infrastructure
• Content distribution systems should integrate with klump encryption framework
• Audio processing should maintain compatibility with existing mix priority system
• Data serialization should consider both internal and external format requirements