Mod Support Overview

Build Information

Current documentation based on build version: 676042 Last updated: 2025-01-22

System Purpose

The Mod Support category provides comprehensive infrastructure for all aspects of mod and DLC management in Don't Starve Together. This system enables the game's extensibility through both community-created modifications and official downloadable content, forming the foundation for the game's vibrant modding ecosystem.

Key Responsibilities

• Core mod loading, registration, and environment management
• DLC discovery, enablement, and content integration
• Configuration management and persistence for both mods and DLC
• Version compatibility and upgrade handling across content types
• Error handling and crash recovery for extended content
• String localization and formatting for international content

System Scope

This category encompasses all mod and DLC infrastructure but excludes core game systems that mods interact with (handled by their respective categories) and user-facing content creation tools.

Architecture Overview

System Components

The mod support system is organized into two primary subsystems that work together to provide comprehensive content extensibility: Core Mod Support handles community modifications while DLC Support manages official downloadable content.

Data Flow

Content Discovery → Registration → Configuration → Loading → Integration
        ↓               ↓              ↓           ↓           ↓
   File/Store Scan → Content Index → Settings → Environment → Game Systems
                                ↑
                           Compatibility Check

Integration Points

• All Core Systems: Mods and DLC can extend virtually any game system
• Asset Loading: Custom content assets and resources
• Networking: Multi-player content synchronization
• User Interface: Content management and configuration screens
• Save System: Content state and configuration persistence

Recent Changes

Build	Date	Component	Change Type	Description
676042	2025-01-22	Core Mod Support	stable	Current core mod infrastructure
676042	2025-01-22	DLC Support	stable	Current DLC management system

System Categories

Core Mod Support

Foundation infrastructure for community-created mod content.

System	Purpose	Key Components
Core Mod Support	Community mod infrastructure	Mod loading, registry, utilities, compatibility

Core Modules:

• Mods System: Foundation mod loading and environment management
• Mod Index: Registry and information management for installed mods
• Mod Utilities: Essential development utilities and environment setup
• Mod Compatibility: Version upgrade and compatibility handling

Key Capabilities:

• Community mod discovery and loading
• Sandboxed mod execution environments
• Mod configuration and dependency management
• Version compatibility and upgrade systems

DLC Support

Infrastructure for official downloadable content management.

System	Purpose	Key Components
DLC Support	Official DLC infrastructure	DLC management, strings, world generation, purchase flow

Core Modules:

• DLC Support: Core DLC management and character list handling
• DLC Support Strings: Specialized string handling with prefix/suffix management
• DLC Support Worldgen: World generation integration with DLC parameters
• Upsell System: Demo version management and purchase flow

Key Capabilities:

• Official DLC registration and enablement
• DLC-aware character and content management
• Localized string construction for DLC content
• Demo version limitations and purchase integration

Common Mod Support Patterns

Content Status Checking

-- Check if any mods are enabled
if AreAnyModsEnabled() then
    print("Community mods are active")
end

-- Check specific mod status
if KnownModIndex:IsModEnabled("workshop-12345") then
    -- Mod-specific functionality
end

-- Check DLC status
if IsDLCEnabled(REIGN_OF_GIANTS) then
    print("Reign of Giants DLC is enabled")
end

Configuration Management

-- Mod configuration access (within mod environment)
local mod_setting = GetModConfigData("difficulty_level")

-- DLC-aware character management
local characters = GetActiveCharacterList()
local selectable = GetSelectableCharacterList()

Content Integration

-- Add mod character
AddModCharacter("mycharacter", "FEMALE", {
    { type = "normal_skin", play_emotes = true },
    { type = "ghost_skin", anim_bank = "ghost" }
})

-- DLC string construction
local item_name = ConstructAdjectivedName(inst, "meat", "wet")
-- Result: "wet meat" or "meat wet" based on language configuration

Version Compatibility

-- Check game version for mod compatibility
if CurrentRelease.GreaterOrEqualTo("R35_SANITYTROUBLES") then
    -- Use newer game features
end

-- Upgrade legacy mod data
local upgraded_level = modcompatability.UpgradeModLevelFromV1toV2(mod, level_data)

System Dependencies

Required Systems

• System Core: Engine integration and file system access
• Data Management: Content configuration and save data persistence
• Fundamentals: Basic entity, component, and action systems

Optional Systems

• Character Systems: Character integration and customization
• User Interface: Content management and configuration screens
• World Systems: World generation and content placement
• Networking: Multi-player content synchronization
• Development Tools: Enhanced debugging and profiling tools

Performance Considerations

Memory Usage

• Mod environments use isolated memory spaces to prevent conflicts
• DLC content loaded on-demand based on enablement state
• Configuration data cached to minimize file system access
• Content registry maintains efficient lookup structures

Performance Optimizations

• Lazy loading of content configuration and assets
• Efficient content discovery using cached directory scans
• Optimized loading order based on dependency analysis
• DLC state checking optimized for frequent world generation calls

Scaling Considerations

• System supports dozens of concurrent mods without performance degradation
• DLC support scales efficiently with multiple content packages
• Memory usage scales linearly with enabled content count
• String construction performance independent of content volume

Development Guidelines

Best Practices

• Always check content enablement before accessing specific features
• Use appropriate utility functions for error handling and debugging
• Follow established patterns for content registration and configuration
• Handle version compatibility gracefully across different game builds
• Use proper dependency declaration in content metadata

Common Pitfalls

• Accessing content-specific features without checking enablement status
• Bypassing content loading systems for custom initialization
• Not handling compatibility across different API versions
• Assuming content installation equals enablement
• Not using proper error handling functions for debugging context

Testing Strategies

• Test content with various combinations of other mods and DLC
• Verify configuration persistence across save/load cycles
• Test compatibility with different game versions and builds
• Validate error handling with corrupted or missing content data
• Test localization with different language configurations

Quick Start Guide

For comprehensive modding tutorials, please see the Getting Started Guide, which includes:

• Step-by-Step Tutorial: Complete walkthrough for creating your first mod
• Common Scenarios: Character creation, custom recipes, world modifications
• Steam Workshop Integration: Publishing and maintaining your mods
• Debugging Tools: Essential troubleshooting techniques
• Performance Optimization: Best practices for efficient modding

The Getting Started guide covers all practical aspects of mod development, while this section focuses on the underlying infrastructure that makes modding possible.

---

Content Integration Patterns

With Character Systems

Mod support integrates with character systems to:

• Register mod-defined characters with appropriate metadata
• Handle DLC-specific character availability and unlocking
• Manage character-specific assets and customization options
• Support character progression and skill system integration

With World Generation

Content systems coordinate with world generation to:

• Enable content-specific world features and biomes
• Provide parameter-driven content state management
• Handle content-specific prefab and resource placement
• Support multiple world generation contexts and configurations

With Asset Loading

Mod support works with asset systems to:

• Load content-specific assets and resources on demand
• Handle asset conflicts between multiple content packages
• Provide fallback mechanisms for missing content assets
• Enable hot-reloading during development and testing

With Localization

Content support enhances localization through:

• Intelligent string construction based on language rules
• Content-specific string handling and formatting
• Function-based dynamic naming for complex localization needs
• Integration with translation systems for international content

---

Debugging and Troubleshooting Guide

Essential Debugging Tools

Console Commands for Mod Development

Source Reference: dst-scripts/debugcommands.lua

-- Basic mod debugging commands
c_give("myitem", 1)                    -- Give item to player
c_spawn("myitem", 10)                  -- Spawn items at cursor
c_find("myitem")                       -- Find all instances in world
c_sel()                                -- Select entity under mouse
c_reset()                              -- Reset selected entity

-- Advanced debugging
c_findnext("myitem")                   -- Find next instance
c_gonext("myitem")                     -- Teleport to next instance
c_regenerateworld()                    -- Regenerate world with mods
c_dumptable(inst.components)           -- Dump component data

Mod-Specific Debug Functions

Source Reference: dst-scripts/components/modutil.lua

-- Error handling and debug output
modprint("Debug message:", variable)   -- Debug-only print
moderror("Error occurred!")            -- Mod error reporting
modassert(condition, "Must be true")   -- Mod assertion

-- Configuration debugging
local config = GetModConfigData("setting_name")
print("Config value:", config)

-- Component inspection
local function DebugEntity(inst)
    print("Entity:", inst.prefab)
    print("Valid:", inst:IsValid())
    print("Components:", table.concat(inst.components, ", "))
    
    if inst.components.health then
        print("Health:", inst.components.health.currenthealth)
    end
end

Common Mod Issues and Solutions

Issue 1: Mod Not Loading

Symptoms:

• Mod doesn't appear in mod list
• No debug output from mod
• Game behaves as if mod doesn't exist

Diagnostic Steps:

-- Check modinfo.lua syntax
print("Checking mod info...")

-- Verify mod directory structure
local mod_path = "../mods/your_mod_name/"
print("Mod path exists:", TheSim:GetFileExists(mod_path .. "modinfo.lua"))

-- Check for syntax errors in modmain.lua
-- Look for error messages in log files

Solutions:

1. Fix modinfo.lua syntax: Ensure all required fields are present
2. Check file permissions: Ensure mod files are readable
3. Verify directory structure: Follow exact naming conventions
4. Review console errors: Look for Lua syntax errors

Issue 2: Items Not Spawning/Working

Symptoms:

• c_give() command fails
• Items appear but have no functionality
• Recipe exists but can't be crafted

Diagnostic Approach:

-- Verify prefab registration
print("Prefab exists:", Prefabs["myitem"] ~= nil)

-- Check recipe registration
for recipe_name, recipe_data in pairs(AllRecipes) do
    if recipe_name == "myitem" then
        print("Recipe found:", recipe_name)
        print("Ingredients:", table.concat(recipe_data.ingredients, ", "))
    end
end

-- Test component functionality
local item = c_spawn("myitem")
if item then
    print("Item components:", table.concat(item.components, ", "))
else
    print("Failed to spawn item")
end

Solutions:

1. Verify prefab files: Ensure prefab is in PrefabFiles list
2. Check component setup: Validate all required components are added
3. Test recipe ingredients: Ensure all ingredients exist and are available
4. Review asset paths: Verify all asset references are correct

Issue 3: Multiplayer Synchronization Problems

Symptoms:

• Mod works in single-player but not multiplayer
• Different behavior between host and clients
• Items disappear when clients join

Debugging Multiplayer Issues:

-- Check network entity setup
local function ValidateNetworkEntity(inst)
    if not TheWorld.ismastersim then
        print("Running on client")
        return inst  -- Client-side setup only
    else
        print("Running on server")
        -- Server-side setup
    end
end

-- Debug RPC communication
AddModRPCHandler("MyMod", "DebugSync", function(player, data)
    print("Received RPC from:", player.name, "Data:", data)
end)

-- Test client-server synchronization
local function TestSync()
    if TheWorld.ismastersim then
        SendModRPCToClient(GetClientModRPC("MyMod", "DebugSync"), nil, "test_data")
    end
end

Solutions:

1. Proper network setup: Use inst.entity:SetPristine() correctly
2. Server-client separation: Check TheWorld.ismastersim appropriately
3. RPC implementation: Use proper mod RPC handlers for custom data
4. Component replication: Ensure important data syncs to clients

Issue 4: Performance Problems

Symptoms:

• Game lag when mod is enabled
• Frame rate drops
• Memory usage increases over time

Performance Debugging:

-- Profile function execution time
local start_time = GetTime()
MyExpensiveFunction()
local end_time = GetTime()
print("Function took:", end_time - start_time, "seconds")

-- Monitor memory usage
collectgarbage("collect")
local memory_before = collectgarbage("count")
CreateManyEntities()
local memory_after = collectgarbage("count")
print("Memory used:", memory_after - memory_before, "KB")

-- Check for memory leaks
local function MonitorInstances()
    local count = 0
    for inst in pairs(Ents) do
        if inst.prefab == "myitem" then
            count = count + 1
        end
    end
    print("Active instances:", count)
end

Solutions:

1. Optimize frequent operations: Cache expensive calculations
2. Clean up entities: Ensure proper entity removal
3. Limit update frequency: Use appropriate periodic task intervals
4. Profile and optimize: Use debugging tools to identify bottlenecks

Advanced Debugging Techniques

Log File Analysis

Source Reference: dst-scripts/main.lua

-- Enable detailed logging
local original_print = print
print = function(...)
    original_print("[MOD DEBUG]", ...)
    -- Also write to file for analysis
end

-- Custom log levels
local LOG_LEVELS = {
    DEBUG = 1,
    INFO = 2,
    WARN = 3,
    ERROR = 4
}

local function ModLog(level, message)
    if GetModConfigData("log_level") <= level then
        print(string.format("[%s] %s", 
              table.invert(LOG_LEVELS)[level], 
              message))
    end
end

Component State Inspection

-- Real-time component monitoring
local function SetupComponentMonitor(inst)
    if GetModConfigData("enable_monitoring") then
        inst:DoPeriodicTask(5, function()
            print("=== Component Status ===")
            for component_name, component in pairs(inst.components) do
                print(component_name .. ":", component:GetDebugString())
            end
        end)
    end
end

AddPlayerPostInit(SetupComponentMonitor)

Asset Validation

-- Verify all mod assets exist
local function ValidateAssets()
    local missing_assets = {}
    
    for _, asset in ipairs(Assets) do
        if not TheSim:GetFileExists(asset.file) then
            table.insert(missing_assets, asset.file)
        end
    end
    
    if #missing_assets > 0 then
        moderror("Missing assets: " .. table.concat(missing_assets, ", "))
    else
        modprint("All assets validated successfully")
    end
end

-- Call during mod initialization
ValidateAssets()

---

Troubleshooting Content Issues

Common Content Problems

Issue	Symptoms	Solution
Content not loading	Missing features/characters	Check enablement status and directory structure
Configuration not saving	Settings reset on restart	Verify file permissions and save data integrity
Version conflicts	Compatibility errors	Check API version requirements and dependencies
String formatting incorrect	Wrong text display	Review string construction configuration
Performance degradation	Slow loading/gameplay	Review content loading patterns and memory usage
Mod crashes game	Instant crash on load	Check Lua syntax errors and component setup
Multiplayer desync	Different behavior host/client	Verify network entity setup and RPC usage
Assets not displaying	Missing textures/animations	Validate asset paths and file formats

Debugging Content Systems

• Use appropriate debug functions (modprint(), console commands)
• Check content loading sequence and dependency resolution
• Verify content registry state and configuration data
• Review error logs for content loading failures
• Monitor content state during gameplay transitions
• Test with isolated mod setups to identify conflicts

Performance Monitoring

• Track content loading times during startup
• Monitor memory usage of content environments
• Analyze configuration file access patterns
• Measure string construction overhead in localization
• Check dependency resolution performance
• Profile mod functions during gameplay

Mod Compatibility Testing

Testing Checklist

-- Compatibility test framework
local function TestModCompatibility()
    local tests = {
        {
            name = "Basic functionality",
            test = function()
                local item = SpawnPrefab("myitem")
                return item ~= nil and item:IsValid()
            end
        },
        {
            name = "Configuration loading",
            test = function()
                local config = GetModConfigData("test_setting")
                return config ~= nil
            end
        },
        {
            name = "Recipe availability",
            test = function()
                return AllRecipes["myitem"] ~= nil
            end
        }
    }
    
    for _, test in ipairs(tests) do
        local success, result = pcall(test.test)
        print(test.name .. ":", success and result and "PASS" or "FAIL")
    end
end

-- Run compatibility tests
TestModCompatibility()

Multi-Mod Testing

1. Test with popular mods: Always test compatibility with widely-used mods
2. Test mod loading order: Verify your mod works regardless of loading sequence
3. Test with DLC combinations: Ensure compatibility with all DLC states
4. Test server hosting: Verify mod works when hosting dedicated servers

Advanced Content Features

Dynamic Content Management

• Runtime content enablement and disablement
• Hot-swapping of content configurations
• Conditional content loading based on player preferences
• Content dependency resolution and conflict handling

Cross-Content Integration

• Interaction between mods and DLC content
• Shared resource and asset management
• Unified configuration and state management
• Compatible string and localization handling

Content Development Support

• Comprehensive development utilities and helpers
• Error handling and debugging infrastructure
• Version compatibility and upgrade assistance
• Performance optimization tools and guidelines

Future Development

Extensibility Design

• Content infrastructure designed for easy addition of new content types
• Support systems accommodate evolving game features and API
• Configuration systems support dynamic option types and validation
• Environment systems designed for enhanced security and isolation

Integration Planning

• New game features should consider content extensibility from design
• Enhanced content development tools and workflow support
• Improved content discovery and management interfaces
• Better integration with external content distribution platforms

Related Systems

System	Relationship	Integration Points
Character Systems	Integration	Character registration, customization, progression
World Systems	Integration	World generation, content placement, biome support
User Interface	Integration	Content management screens, configuration interfaces
Networking	Integration	Multi-player content synchronization
Development Tools	Enhancement	Enhanced debugging and profiling for content
Data Management	Foundation	Configuration persistence, save data integration

Contributing to Mod Support

Adding New Content Features

• Follow established patterns for content registration and management
• Maintain compatibility with existing content ecosystem
• Document content-specific requirements and dependencies
• Test integration with various content combinations
• Consider performance impact and optimization opportunities

Modifying Content Infrastructure

• Consider impact on existing mod and DLC ecosystem
• Provide migration paths for changed functionality
• Update related documentation and integration guides
• Coordinate with content development community
• Maintain backward compatibility where possible

Quality Assurance

Testing Coverage

• Comprehensive testing of all content combination states
• Cross-content compatibility testing (mods with DLC)
• Localization testing with multiple languages and regions
• Performance testing with large numbers of content packages
• Platform compatibility testing across supported systems

Code Review Standards

• Security review for content environment isolation and safety
• Performance review for content loading and execution paths
• API design review for consistency with core systems
• Compatibility review for cross-content interactions
• Documentation review for completeness and accuracy

Content Ecosystem Health

Community Support

• Clear documentation and examples for content creators
• Active support channels for content development questions
• Regular updates to development tools and utilities
• Community feedback integration into infrastructure improvements

Quality Standards

• Content validation and safety checks
• Performance guidelines and optimization recommendations
• Compatibility testing and validation procedures
• Security review processes for community content

Long-term Sustainability

• Infrastructure designed for long-term maintenance and evolution
• Backward compatibility preservation across game updates
• Community involvement in infrastructure development decisions
• Regular assessment and improvement of content systems