Character Customization Overview

Build Information

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

System Purpose

The Character Customization category encompasses all functionality related to character and companion appearance modification in Don't Starve Together. These systems work together to provide comprehensive cosmetic customization options including character skins, clothing items, beefalo outfits, and companion modifications.

Key Responsibilities

• Character skin management and application
• Clothing and cosmetic item definitions
• Beefalo companion customization
• Skin trading and filtering systems
• Gift and collection management
• Asset loading and visual presentation

System Scope

This system category includes all visual customization elements but excludes gameplay mechanics (handled by Game Mechanics) and core character functionality (handled by Core Character Systems).

Architecture Overview

System Components

The customization system is built on a layered architecture where core utilities provide foundation services for specialized customization features like trading, filtering, and asset management.

Data Flow

Asset Definitions → Skin System → Customization Interface → Visual Application
       ↓               ↓              ↓                    ↓
   Auto-Generation → Item Matching → Filter Processing → Character Rendering

Integration Points

• Character Systems: Base character functionality and appearance management
• Data Management: Asset loading and customization data persistence
• User Interface: Customization screens and selection interfaces
• Networking: Cosmetic synchronization between players

Recent Changes

Build	Date	Component	Change Type	Description
676042	2025-06-21	Beefalo Clothing	stable	Updated symbol override documentation
676042	2025-06-21	Clothing	stable	Complete clothing catalog with current data
676042	2025-06-21	Skins Utils	stable	Comprehensive utility system

Core Customization Modules

Character Clothing System

Character clothing and cosmetic item data structure for appearance customization.

Module	Status	Description	Key Features
Clothing	stable	Character clothing definitions	Body, hand, legs, feet, head items

Beefalo Customization

Cosmetic customization options for domesticated beefalo companions.

Module	Status	Description	Key Features
Beefalo Clothing	stable	Beefalo clothing system	Themed sets, symbol overrides

Skin Management Utilities

Comprehensive utility system for managing character skins and cosmetic items.

Module	Status	Description	Key Features
Skins Utils	stable	Core skins functionality	Rarity, colors, inventory, filtering
Skins Filters Utils	stable	Filtering utilities	Type, rarity, color filtering
Skins Trade Utils	stable	Trading utilities	Recipe matching, validation

Asset and Data Systems

Auto-generated skin definitions and asset management for the customization system.

Module	Status	Description	Key Features
Skins Definitions Data	stable	Auto-generated skin definitions	Asset mappings, linking relationships
Skin Assets	stable	Asset loading definitions	Animation assets, portraits, textures
Skin Affinity Info	stable	Character-skin associations	Character compatibility mapping

Collection and Gift Systems

Gift system configuration and coordinated skin collections.

Module	Status	Description	Key Features
Skin Gifts	stable	Gift system configuration	Gift types, popup configurations
Skin Set Info	stable	Coordinated skin collections	Emote sets, themed collections

Common Customization Patterns

Character Skin Application

-- Apply character skin with validation
local function ApplyCharacterSkin(player, skin_id)
    if TheInventory:CheckOwnership(skin_id) then
        local skin_data = GetSkinData(skin_id)
        if skin_data and skin_data.type == "base" then
            player:SetSkin(skin_id)
            return true
        end
    end
    return false
end

Clothing Item Management

-- Equip clothing item with symbol overrides
local function EquipClothingItem(character, clothing_id)
    local clothing = CLOTHING[clothing_id]
    if clothing and clothing.symbol_overrides then
        for _, symbol in ipairs(clothing.symbol_overrides) do
            character.AnimState:OverrideSymbol(symbol, clothing_id, symbol)
        end
        character.equipped_clothing = clothing_id
    end
end

Beefalo Customization

-- Apply complete beefalo theme set
local function ApplyBeefaloTheme(beefalo, theme)
    local clothing_types = {"body", "feet", "head", "horn", "tail"}
    for _, part in ipairs(clothing_types) do
        local item_name = "beefalo_" .. part .. "_" .. theme
        local clothing = BEEFALO_CLOTHING[item_name]
        if clothing then
            ApplyBeefaloClothing(beefalo, clothing)
        end
    end
end

Skin Filtering and Trading

-- Filter skins by multiple criteria
local function FilterSkinsByCategory(full_list, category, rarity)
    local filters = {{category, rarity}}
    return ApplyFilters(full_list, filters)
end

-- Validate trading selection
local function ValidateTradeSelection(selections)
    local count = GetNumberSelectedItems(selections)
    local recipe = GetBasicRecipeMatch(selections)
    return count > 0 and recipe ~= nil
end

Customization System Dependencies

Required Systems

• Core Character Systems: Base character functionality and components
• Data Management: Asset loading and persistence
• User Interface: Customization interfaces

Optional Systems

• Game Mechanics: Achievement-based unlocks
• Networking: Multiplayer cosmetic sync

Performance Considerations

Memory Usage

• Skin systems use dynamic loading for texture assets
• Clothing data is cached for frequently accessed items
• Asset streaming optimizes memory usage based on equipped items

Performance Optimizations

• Skin filtering uses efficient lookup tables and early termination
• Symbol overrides batch rendering operations for multiple items
• Asset loading prioritizes currently equipped and previewed items

Scaling Considerations

• Systems support extensive skin collections with thousands of items
• Filtering operations scale efficiently with large inventories
• Trading system handles complex recipe validation without performance impact

Development Guidelines

Best Practices

• Always validate skin ownership before applying visual changes
• Use the filtering utilities for consistent skin categorization
• Follow established naming conventions for new cosmetic items
• Test customization changes across all supported characters

Common Pitfalls

• Bypassing ownership validation for development convenience
• Not handling missing asset data gracefully in custom skins
• Modifying auto-generated data files instead of source systems
• Creating visual conflicts between clothing items and character features

Testing Strategies

• Test all customization options with every playable character
• Verify skin filtering works correctly with edge cases
• Validate trading recipes with various item combinations
• Test asset loading performance with large skin collections

Customization Integration Patterns

With Character Systems

Customization systems enhance character functionality:

• Visual changes reflect character personality and player choice
• Cosmetic items respect character-specific design constraints
• Skin affinity ensures visual consistency with character themes

With User Interface

Customization drives UI presentation:

• Character selection screens display available skins
• Inventory interfaces show owned cosmetic items
• Trading screens facilitate skin exchange workflows
• Collection displays track customization progress

With Asset Management

Customization integrates with game asset pipeline:

• Dynamic loading reduces memory footprint
• Asset streaming supports large cosmetic collections
• Texture optimization maintains visual quality
• Animation integration preserves character expressiveness

Collection and Trading Systems

Skin Collections

• Themed Sets: Coordinated items that work together visually
• Character Affinity: Items designed for specific characters
• Rarity Tiers: Classification system from Common to Elegant
• Gift Categories: Special acquisition methods and presentations

Trading Mechanics

• Recipe System: Defined exchanges between rarity levels
• Validation Logic: Ensures fair and balanced trading
• Filter Generation: Helps players find compatible items
• Selection Management: Streamlined trading interface

Asset and Technical Architecture

Auto-Generation Pipeline

• Source Processing: Export scripts generate definitions from game data
• Asset Organization: Systematic categorization of visual resources
• Validation Systems: Ensure data integrity and completeness
• Update Automation: Seamless integration with game build process

Performance Architecture

• Streaming Groups: Organized asset loading for memory efficiency
• Dynamic Loading: On-demand resource allocation
• Caching Strategies: Optimized access to frequently used data
• Network Optimization: Minimal data synchronization requirements

Troubleshooting Customization Issues

Common Customization Problems

Issue	Symptoms	Solution
Skins not displaying	Visual changes not applied	Check ownership and asset loading
Clothing conflicts	Visual artifacts or missing parts	Verify symbol override compatibility
Filter not working	Incorrect item lists	Validate filter criteria and data
Trading validation fails	Cannot complete trades	Check recipe requirements and selection

Debugging Customization Systems

• Use skin debug commands to inspect loaded assets
• Verify customization data integrity with validation functions
• Check character compatibility with skin affinity mappings
• Review asset loading status for missing resources

Future Development

Extensibility Design

• Customization systems support easy addition of new cosmetic categories
• Asset pipeline accommodates diverse visual styles and themes
• Trading framework adapts to new exchange mechanisms
• Collection system scales with expanding content library

Integration Planning

• New cosmetic features should leverage existing utility systems
• Consider performance implications of large-scale visual changes
• Plan for cross-system compatibility with character and UI updates
• Design for mod compatibility and community content creation

Related Systems

System	Relationship	Integration Points
Core Character Systems	Foundation	Character appearance and component management
Character Progression	Enhancement	Unlock-based customization rewards
User Interface	Presentation	Customization screens and selection interfaces
Data Management	Storage	Asset loading and customization persistence

Contributing to Customization Systems

Adding New Customization Features

1. Follow established data structure patterns
2. Integrate with existing utility and filtering systems
3. Ensure compatibility across all supported characters
4. Document visual requirements and asset specifications

Modifying Existing Features

1. Understand current asset dependencies and relationships
2. Maintain backward compatibility with existing customization data
3. Update related documentation and integration examples
4. Test changes across the complete customization pipeline

Quality Assurance

Customization Validation

• All cosmetic items display correctly across characters
• Trading system maintains balance and fairness
• Asset loading performs efficiently under various conditions
• Collection tracking accurately reflects player progress

Visual Quality Standards

• Customization items maintain consistent art style
• Character personality is preserved through visual changes
• Performance impact remains minimal during gameplay
• Visual conflicts between items are avoided or resolved