Development Utilities Overview

Build Information

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

System Purpose

The Development Utilities category provides essential support tools and helper functions that facilitate DST development workflows. These utilities handle common development tasks such as data serialization, error management, code quality enforcement, and content organization, enabling efficient and reliable development processes.

Key Responsibilities

• Provide data serialization and dumping capabilities for debugging
• Enforce code quality through strict mode variable checking
• Manage structured error handling with user-friendly messages
• Support content organization and standardization workflows
• Enable persistent key-value storage for development settings

System Scope

This category includes general-purpose development tools and utilities but excludes specialized debugging tools (handled by Debugging Tools), performance analysis (handled by Profiling Tools), and interactive commands (handled by Console Tools).

Architecture Overview

System Components

Development utilities are designed as standalone helper modules that can be integrated into various development workflows without complex dependencies or configuration requirements.

Data Flow

Development Task → Utility Function → Processing/Validation → Result/Output
       ↓                ↓                    ↓                  ↓
   Code Quality → Strict Checking → Error Detection → Quality Assurance

Integration Points

• Code Quality: Integration with Lua runtime for strict mode enforcement
• Data Management: Serialization and storage utilities for development data
• Error Handling: Structured error reporting for user-friendly debugging
• Content Tools: File processing and organization utilities

Recent Changes

Build	Date	Component	Change Type	Description
676042	2025-06-21	Data Dumper	stable	Current data serialization system
676042	2025-06-21	Strict Mode	stable	Current strict variable checking
676042	2025-06-21	Known Errors	stable	Current structured error handling
676042	2025-06-21	Generic KV	stable	Current key-value storage system
676042	2025-06-21	Character String Fixer	stable	Current content organization tool

Core Development Modules

Data Serialization

Advanced Lua data serialization and debugging utilities.

Module	Status	Description	Key Features
Data Dumper	stable	Lua data structure serialization	Complex data dumping, circular reference handling, metatable preservation

Code Quality

Development-time code quality enforcement and validation.

Module	Status	Description	Key Features
Strict Mode	stable	Global variable access control	Undeclared variable detection, scope validation, development error prevention

Error Management

Structured error handling with user-friendly messaging.

Module	Status	Description	Key Features
Known Errors	stable	User-friendly error reporting	Structured error messages, support URL integration, development error handling

Development Storage

Persistent storage utilities for development settings and data.

Module	Status	Description	Key Features
Generic KV Store	stable	Key-value storage wrapper	TheInventory synchronization, persistent settings, development data storage

Content Organization

Content processing and standardization utilities.

Module	Status	Description	Key Features
Character String Fixer	stable	Speech file organization tool	Alphabetical sorting, content standardization, file formatting

Common Development Patterns

Data Debugging and Analysis

-- Serialize complex data structures for debugging
local complex_data = {
    player = {name = "Wilson", stats = {health = 100, hunger = 75}},
    world = {day = 15, season = "autumn"}
}

local serialized = DataDumper(complex_data, "debug_state")
print(serialized)  -- Executable Lua code for data recreation

-- Fast mode for large datasets
local fast_dump = DataDumper(large_table, "performance_data", true)

Code Quality Enforcement

-- Enable strict mode for development
require("strict")

-- Declare global variables explicitly
global("DEBUG_MODE", "LOG_LEVEL", "DEVELOPMENT_FLAGS")
DEBUG_MODE = true
LOG_LEVEL = "verbose"
DEVELOPMENT_FLAGS = {profiling = false, metrics = true}

-- Catch undeclared variable errors
-- unknownVariable = "test"  -- Error: assign to undeclared variable

Structured Error Handling

-- Use known assertions for user-friendly errors
local config_writable = CheckConfigWritePermissions()
known_assert(config_writable, "CONFIG_DIR_WRITE_PERMISSION")

-- Custom error handling with structured messages
if not has_disk_space then
    known_assert(false, "CONFIG_DIR_DISK_SPACE")
end

Development Data Storage

-- Store development settings persistently
local kv = GenericKV()
kv.save_enabled = true
kv:Load()

-- Set development preferences
kv:SetKV("debug_overlay", "true")
kv:SetKV("auto_save_interval", "300")
kv:SetKV("preferred_log_level", "debug")

Content Processing

-- Standardize character speech files (external script)
-- lua fix_character_strings.lua speech_wilson
-- lua fix_character_strings.lua speech_wendy formatted_wendy.lua

-- Alphabetically sort and format content files
-- Input: Unsorted speech data
-- Output: Standardized, sorted Lua table format

Development Utility Dependencies

Required Systems

• System Core: Lua runtime integration and core functions
• Data Management: File I/O and persistence capabilities
• Console Tools: Command-line integration for utility access

Optional Systems

• User Interface: Debug overlay integration for data visualization
• Networking: Network-aware error handling and storage

Performance Considerations

Utility Impact

• Data dumping tools have minimal runtime impact when not in use
• Strict mode adds small overhead to global variable access during development
• Error handling utilities provide fast lookup and minimal processing overhead
• Storage utilities use efficient JSON serialization and async I/O operations

Memory Usage

• Data dumper uses save buffers to prevent memory spikes during large serializations
• Strict mode maintains small declaration registry with minimal memory footprint
• Error system stores pre-computed messages for fast access
• KV storage uses incremental loading and saves to manage memory efficiently

Resource Management

• Utilities respect system resources and cleanup automatically after use
• File operations use safe, atomic writes to prevent data corruption
• Memory allocations are minimized through efficient data structures
• Background operations are designed to not interfere with game performance

Development Guidelines

Best Practices

• Use Data Dumper for complex debugging scenarios and data analysis
• Enable strict mode during development to catch variable declaration errors
• Implement structured error handling using known_assert for user-facing errors
• Utilize KV storage for persistent development settings and preferences
• Run character string fixer regularly to maintain content organization standards

Common Pitfalls

• Not enabling strict mode during development, leading to missed variable errors
• Using regular assert instead of known_assert for user-facing error conditions
• Attempting to serialize userdata or threads with Data Dumper
• Forgetting to enable save functionality for GenericKV before setting values
• Not running content organization tools before committing changes

Testing Strategies

• Test data serialization with complex nested structures and circular references
• Validate strict mode behavior with various scoping scenarios
• Verify error messages are user-friendly and actionable
• Test KV storage persistence across application restarts
• Validate content organization tools with various input formats

Development Integration Workflows

Code Quality Workflow

1. Development Setup: Enable strict mode for development builds
2. Variable Management: Use global() declarations for all global variables
3. Error Handling: Implement known_assert for user-facing error conditions
4. Quality Assurance: Validate code quality before commits

Data Analysis Workflow

1. Data Collection: Use Data Dumper to serialize complex game states
2. Analysis: Examine serialized data for debugging and optimization
3. Validation: Test data recreation to ensure serialization accuracy
4. Documentation: Use dumped data for system documentation and examples

Content Management Workflow

1. Content Creation: Create and edit character speech and content files
2. Organization: Run fix_character_strings to standardize formatting
3. Validation: Verify sorted output maintains correct data structure
4. Integration: Commit standardized files to version control

Development Utility Security

Safe Usage Guidelines

• Data dumping utilities respect memory boundaries and prevent infinite loops
• Strict mode enforces proper variable scoping without exposing sensitive data
• Error handling system doesn't leak internal implementation details
• KV storage uses safe file operations and validates input data

Access Control

• Development utilities require appropriate development mode activation
• File system access is limited to safe, designated directories
• Error reporting doesn't expose sensitive system information
• Storage operations validate data types and content before persistence

Advanced Development Features

Custom Serialization

• Framework for extending Data Dumper with custom type handlers
• Integration patterns for complex game object serialization
• Guidelines for handling circular references and deep object graphs
• Best practices for memory-efficient large data dumping

Development Environment Configuration

• Persistent development settings through GenericKV integration
• Custom error message and URL configuration for specific workflows
• Automated content organization integration with build processes
• Development-specific strict mode configurations and exclusions

Troubleshooting Development Utilities

Common Utility Issues

Issue	Symptoms	Solution
Data dumping fails	Serialization errors or incomplete output	Check for userdata or circular references
Strict mode errors	Undeclared variable assertions	Use global() to declare variables before use
Error messages unclear	Generic error messages instead of known errors	Use known_assert with appropriate error keys
KV storage not persisting	Settings lost between sessions	Enable save_enabled flag before setting values
Content formatting fails	File processing errors	Verify input file structure and Lua syntax

Development Tool Debugging

• Verify utility module loading and initialization
• Check development mode flags and configuration settings
• Review file permissions for storage and content processing utilities
• Test utilities with minimal datasets before applying to production data

Maintenance and Updates

Tool Maintenance

• Regular validation of data serialization accuracy with complex test cases
• Performance impact assessment for strict mode checking overhead
• Documentation updates for new utility features and usage patterns
• Cleanup of deprecated utility functions and outdated error messages

Tool Evolution

• Addition of new development utilities based on workflow needs
• Performance improvements for data processing and serialization utilities
• Enhanced integration with modern development tools and IDEs
• Better automation capabilities for content processing and quality assurance

Integration with Build Process

Continuous Integration

• Automated strict mode validation in CI/CD pipelines
• Content organization validation before merge requests
• Data serialization testing with known good datasets
• Error handling verification across different deployment environments

Development Automation

• Integration of content processing tools with build scripts
• Automated development environment setup with utility configuration
• Performance regression testing for utility overhead
• Documentation generation using data dumping utilities for examples