Fundamentals Utilities Overview

Build Information

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

System Purpose

The Fundamentals Utilities category provides essential helper functions and utility systems that serve as the foundation for all DST game mechanics. These utilities offer standardized solutions for common programming tasks including mathematical calculations, string processing, table manipulation, vector operations, performance monitoring, and specialized game-related functionality.

Key Responsibilities

• Provide mathematical utility functions for calculations and vector operations
• Handle string manipulation, formatting, and character speech generation
• Offer table manipulation and data structure utilities
• Support performance monitoring and profiling capabilities
• Enable file system operations and persistent data management
• Facilitate entity finding, position validation, and simulation helpers
• Supply debugging and development support utilities

System Scope

This category includes foundational utility functions used across all game systems but excludes specific gameplay mechanics (handled by Game Mechanics) and high-level component systems (handled by Core Systems).

Architecture Overview

System Components

The utilities are organized into specialized modules that provide focused functionality while maintaining loose coupling between different utility types. Each module serves specific domains while sharing common patterns for error handling and parameter validation.

Data Flow

Game Systems → Utility Functions → Low-Level Operations → Results
     ↓              ↓                    ↓                ↓
User Input → Helper Functions → Math/String/Table Ops → Game State

Integration Points

• All Core Systems: Utilities are used throughout the entire codebase
• Component Systems: Provide foundational operations for component logic
• Entity Systems: Support entity manipulation and state management
• Performance Systems: Enable monitoring and optimization capabilities

Recent Changes

Build	Date	Component	Change Type	Description
676042	2025-06-21	All Utilities	stable	Current stable versions

Core Utility Modules

General Utilities

Comprehensive collection of helper functions for common programming tasks.

Module	Status	Description	Key Features
Utility Functions	stable	Table manipulation, string processing, math calculations	Data structures, random selection, debugging

Mathematical Utilities

Mathematical functions for calculations, interpolation, and vector operations.

Module	Status	Description	Key Features
Math Utilities	stable	Sine waves, interpolation, rounding, distance calculations	Wave generation, lerp functions, angle operations

Vector Mathematics

Object-oriented and functional vector operation systems.

Module	Status	Description	Key Features
Vector3	stable	Object-oriented 3D vector class with operator overloading	Vector math, operator support, object methods
Vec3Util	stable	High-performance 3D vector utility functions	Performance-optimized, no object creation
VecUtil	stable	2D vector utilities for XZ plane operations	2D calculations, plane operations

String Processing

String manipulation, character speech, and text formatting capabilities.

Module	Status	Description	Key Features
String Utilities	stable	Character speech, string formatting, text manipulation	Character dialogue, special speech effects

Performance Monitoring

Performance analysis, profiling, and diagnostic utilities.

Module	Status	Description	Key Features
Performance Utilities	stable	Entity monitoring, profiling, debugging diagnostics	Entity counting, server statistics, mod analysis

Simulation Helpers

Core utility functions for entity finding, position validation, and game simulation.

Module	Status	Description	Key Features
Simulation Utilities	stable	Entity searching, position validation, vision checking	Entity finding, walkable positions, atlas management

Component Helpers

Utility functions supporting gameplay mechanics and entity management.

Module	Status	Description	Key Features
Component Utilities	stable	Entity state management, world manipulation, specialized systems	Bridge construction, inventory management, combat utilities

File Operations

File system utilities for persistent data operations.

Module	Status	Description	Key Features
File Utilities	stable	Asynchronous file operations, existence checking	Bulk file deletion, platform-specific optimizations

Common Usage Patterns

Mathematical Operations

-- Interpolation between values
local result = Lerp(start_value, end_value, progress)

-- Sine wave generation for animations
local wave = GetSineVal(frequency, absolute_value, entity_instance)

-- Distance calculations
local distance_sq = distsq(pos1, pos2)

Vector Operations

-- Object-oriented vector math
local direction = (target_pos - start_pos):GetNormalized()
local scaled_vector = direction * speed

-- Performance-optimized vector operations
local x, y, z = Vec3Util_Add(x1, y1, z1, x2, y2, z2)
local norm_x, norm_y, norm_z = Vec3Util_Normalize(x, y, z)

String Processing

-- Character-specific dialogue
local dialogue = GetString(character_inst, "DESCRIBE", "TREE")

-- String formatting and manipulation
local formatted_time = str_seconds(elapsed_time)
local capitalized = FirstToUpper(text_string)

Entity and Simulation Utilities

-- Find entities with specific criteria
local entity = FindEntity(inst, radius, filter_function, must_tags, cant_tags)

-- Position validation
local offset = FindWalkableOffset(position, angle, radius, attempts)

-- Performance monitoring
CountEntities()
local metadata = GetProfilerMetaData()

System Dependencies

Required Systems

• System Core: Engine integration and low-level operations
• Data Management: Persistent data access for file utilities

Optional Systems

• User Interface: Atlas management and UI utilities
• World Systems: Position validation and entity finding
• Networking: Performance monitoring in multiplayer

Performance Considerations

Optimization Strategies

• Mathematical Operations: Use squared distance calculations to avoid expensive square root operations
• Vector Operations: Choose between object-oriented Vector3 class and performance-optimized Vec3Util functions based on use case
• Entity Searching: Utilize tag-based filtering and radius limitations to minimize search overhead
• String Operations: Cache frequently accessed character dialogue and use efficient string manipulation functions
• File Operations: Leverage asynchronous file operations and platform-specific optimizations

Memory Management

• Vector utilities avoid object creation overhead for high-frequency calculations
• String utilities implement efficient caching mechanisms for character speech
• Performance utilities use circular buffers and controlled data collection
• Table utilities provide in-place operations where possible

Scaling Considerations

• Entity finding functions scale well with proper tag usage and radius constraints
• Performance monitoring adapts to server size and player count
• Mathematical utilities maintain consistent performance regardless of game state
• File operations handle large datasets through asynchronous processing

Development Guidelines

Best Practices

• Use appropriate utility functions for each domain (math, string, vector, etc.)
• Choose between object-oriented and functional approaches based on performance requirements
• Validate inputs to utility functions to ensure robustness
• Leverage caching mechanisms where available to improve performance
• Use squared distance calculations for proximity checks when exact distance isn't needed
• Apply consistent error handling patterns across utility usage

Common Pitfalls

• Creating unnecessary Vector3 objects in performance-critical loops
• Using exact string matching instead of utility functions for character speech
• Ignoring platform-specific optimizations in file operations
• Performing expensive calculations repeatedly instead of caching results
• Not validating entity existence before applying utility operations

Testing Strategies

• Test mathematical utilities with edge cases (zero, negative, infinity)
• Verify vector operations maintain mathematical correctness
• Validate string utilities with different character types and special cases
• Test performance utilities under various load conditions
• Ensure file utilities handle missing files and permission errors gracefully

Utility Integration Workflows

Mathematical Calculations

1. Basic Operations: Use mathutil for interpolation, rounding, and wave generation
2. Vector Math: Choose Vector3 for readability or Vec3Util for performance
3. Distance Checks: Employ squared distance functions for efficiency
4. Angle Operations: Apply normalization functions for consistent angle handling

Entity Operations

1. Entity Finding: Use simutil functions with appropriate tag filtering
2. Position Validation: Apply walkable position checks for placement operations
3. State Management: Leverage componentutil for entity state operations
4. Performance Monitoring: Implement perfutil for debugging and optimization

Data Processing

1. String Handling: Use stringutil for formatting and character-specific operations
2. Table Operations: Apply util functions for manipulation and data structures
3. File Management: Implement fileutil for persistent data operations
4. Memory Analysis: Use performance utilities for resource monitoring

Related Systems

System	Relationship	Integration Points
Fundamentals Core	Foundation	Entity system, class framework
Actions	Consumer	Action validation and execution
AI Systems	Consumer	Entity finding and position validation
Game Mechanics	Consumer	Mathematical calculations and utilities

Troubleshooting

Common Utility Issues

Issue	Symptoms	Solution
Vector calculations incorrect	Wrong positions or directions	Verify vector operation order and normalization
Performance degradation	Slow entity operations	Use squared distance and tag filtering
String formatting errors	Incorrect character speech	Check character type and string table existence
File operation failures	Save/load errors	Verify file permissions and path resolution

Debugging Utilities

• Use performance utilities to monitor entity counts and system load
• Apply debug printing functions to trace utility function calls
• Leverage vector utilities to validate mathematical operations
• Employ file utilities to verify persistent data integrity

Migration and Compatibility

Utility Updates

When updating utility functions:

• Maintain backward compatibility for widely-used functions
• Provide migration paths for changed APIs
• Test utility changes across all dependent systems
• Document performance impact of utility modifications

Best Practices for Updates

• Test mathematical utilities with known values to verify correctness
• Validate string utilities with all supported character types
• Ensure vector utilities maintain mathematical properties
• Verify file utilities work across all supported platforms

Contributing to Utilities

Adding New Utilities

1. Determine appropriate module for new functionality
2. Follow established patterns for parameter validation and error handling
3. Provide comprehensive examples and usage documentation
4. Consider performance implications and provide optimized alternatives when needed
5. Test across different game scenarios and edge cases

Documentation Standards

• Include clear examples for all utility functions
• Document performance characteristics and trade-offs
• Provide migration guidance for deprecated functions
• Maintain consistency with existing utility documentation patterns

Code Review Checklist

• Utility functions handle edge cases appropriately
• Performance characteristics are documented and acceptable
• Function signatures follow established patterns
• Error handling is consistent with module standards
• Examples demonstrate realistic usage scenarios
• Integration with existing systems is validated