dst-scripts#

Overview#

The dst-scripts repository (LetsStarveTogether/dst-scripts) contains the core game logic Lua scripts for Don't Starve Together (饥荒联机版), the multiplayer survival game developed by Klei Entertainment. It is the primary source of truth for all game systems that govern how entities behave, how the world is generated, how the player interface operates, and how the multiplayer simulation is managed.

The codebase is written entirely in Lua and spans thousands of files organized by functional domain. It implements a rich set of interleaved systems:

• Entity Systems — templates and runtime scripts that define every object in the game world
• AI Behaviors — behavior trees and state machines that drive creature and NPC intelligence
• World Generation — a procedural, hierarchical system that assembles diverse, replayable worlds
• UI Layer — screens and widgets that render the HUD, menus, and in-game interfaces
• Game Mechanics — actions, crafting, cooking, farming, equipment, events, and balance tuning

Note: This repository contains no README file. All documentation of intent and usage is embedded in the code organization, file naming conventions, and inline comments. 1

The repository serves as the foundation for both the base game and its downloadable content expansions, with explicit DLC support built into the task and configuration systems.

Architecture#

dst-scripts follows a Component-Based Entity Architecture aligned with the Entity Component System (ECS) pattern. Rather than using deep inheritance hierarchies, game objects (entities) are assembled at runtime by attaching modular, reusable components. This makes it easy to share behavior across wildly different entity types — a tree, a character, and a campfire can all share the same burnable component.

Architectural Layers#

Five key layers work together to describe and operate every entity in the game:

Core Root Files#

The repository root contains 235+ Lua files. The most architecturally significant are:

• main.lua 2 — Entry point and initialization. Sets up the Lua package path, seeds the random number generator, and defines platform-detection helpers such as IsConsole(), IsSteam(), IsWin32(), and IsPS4() for conditional platform-specific behavior throughout the engine.

• gamelogic.lua 3 — Core game initialization. Requires and bootstraps all essential subsystems including player death tracking, server preferences, profanity filtering, map utilities, constants, user commands, emotes, and the loading screen widget. Also handles platform-specific setup (e.g., PS4 memory tracking).

• brain.lua 4 — AI brain system foundation. Implements the BrainWrangler class, which manages the full lifecycle of AI entity brains. Brains are organized into three lists — updaters, hibernators, and tickwaiters — for efficient per-frame processing.

• entityscript.lua 5 — Base entity script functionality. Provides the foundational ECS integration, including EntityWatchWorldState() and ComponentWatchWorldState() — subscription mechanisms that let entities and components react to global game-state changes.

• networking.lua 6 — Multiplayer networking layer. Handles client/server communication including remote slash commands (Networking_SlashCmd), player announcements, skin announcements, and the spawning of secondary instances for multiplayer sessions.

• actions.lua 7 — Action system definitions. Establishes the action execution framework with range-validation utilities like MakeRangeCheckFn(), DefaultRangeCheck, and PickRangeCheck() to determine whether player interactions are spatially valid.

• constants.lua 8 — Game-wide constant values. Defines mathematical constants (PI, SQRT2, GOLDENANGLE), frame timing (FRAMES = 1/30), resolution settings, camera visibility distances, entity pop-in/pop-out radii, and directional constants (FACING_RIGHT, FACING_UP, etc.).

• tuning.lua 9 — Gameplay balance tuning parameters. Contains the global TUNING table with all adjustable game values: day-cycle timings, character stats (wilson_attack, wilson_health, wilson_hunger, wilson_sanity), multiplayer modifiers, wildlife respawn rates, and modifier functions for dynamic balance adjustments.

• config.lua 10 — Configuration management. Defines a Config class that manages platform-specific option sets with default values and per-platform overrides. The global TheConfig instance is applied at runtime and governs options such as hide_vignette and force_netbookmode.

Directory Structure#

The repository is organized by functional domain. Below is a detailed breakdown of each directory.

prefabs/ — 1,583 files 1#

The largest directory in the repository. Each file defines one or more entity templates — the blueprints from which runtime entities are instantiated. Every interactive or visible object in the game originates from a prefab.

Categories include:

• Player characters — wilson.lua 11, wendy.lua, wolfgang.lua, and all other playable characters; each imports MakePlayerCharacter from a shared player_common factory
• Creatures and mobs — beefalo.lua 12, spider.lua, hound.lua, etc.; creature prefabs load their corresponding brain module and configure shared loot tables
• Items and tools — axe.lua 13, pickaxe.lua, spear.lua, etc.; tool prefabs use parameterized factory functions (e.g., MakeAxe()) to support variants (standard, golden, moonglass) with minimal duplication
• Environmental objects — trees, rocks, grass tufts, and other terrain features
• Food items and recipes — consumables with nutrition and status-effect data

Each prefab file declares its external assets (animation banks, sounds, textures) and prefab dependencies at the top, enabling lazy-loading and explicit dependency tracking. Behavior is injected via common_postinit and master_postinit callback functions passed to the factory.

components/ — 815 files 14#

Reusable modules that add specific behaviors and data to entities. Components are the heart of the ECS pattern — attaching entity:AddComponent("health") gives an entity hit points; entity:AddComponent("combat") enables it to fight. Key examples:

Key design patterns across all components:

• Replica synchronization — critical state is mirrored to self.inst.replica.<component> for networked client replication
• Dynamic tagging — components manage runtime entity tags (e.g., "fire_fueled", "chop_workable") for capability queries
• Cross-component coordination — components reference siblings through the shared inst handle (e.g., health checks combat panic thresholds)
• Event-driven callbacks — onproperty callbacks respond automatically to state changes

stategraphs/ — 261 files 22#

State machine implementations that control animation states and behavioral transitions for entities. Files follow the naming convention SG<entityname>.lua (e.g., SGwilson.lua, SGbeefalo.lua, SGabigail.lua).

Each state graph defines:

• Named animation states (idle, walk, attack, death, sleep, etc.)
• Transition rules between states
• Event handlers that trigger state changes
• Per-state hooks for sounds, particles, and logic callbacks

The shared commonstates.lua file provides reusable state definitions that are mixed into entity-specific graphs.

brains/ — 191 files 23#

AI brain files that implement behavior trees for NPCs and creatures. Each file corresponds to a specific creature or character AI (e.g., beefalobrain.lua 24, spiderbrain.lua, pigbrain.lua).

A brain file typically:

1. Requires the behavior node modules it needs (wander, faceentity, chaseandattack, follow, attackwall)
2. Defines creature-specific distance and timing constants (e.g., SEE_PLAYER_DIST = 5, WANDER_DIST_DAY = 20, MAX_CHASE_TIME = 6) 25
3. Defines AI state constants (GREETING, LOITERING, WANDERING)
4. Composes behavior nodes into a priority-ordered behavior tree

Brains are installed on entities via entity:SetBrain(brain) during prefab construction.

behaviours/ — 29 files 26#

The atomic behavior tree node implementations that brains compose. Each file defines a single reusable behavior class extending BehaviourNode:

Each behavior implements a Visit() method containing the core execution logic that returns the current behavior status. Behaviors can also register event listeners (e.g., chaseandattack listens for "onattackother" events) 29.

map/ — World Generation System 30#

A hierarchical world generation system using four nested subdirectories:

map/levels/ 31 — Top-level world preset definitions (forest.lua, caves.lua, lavaarena.lua, quagmire.lua). Each level specifies required set pieces and a pool of random set pieces to include. Example from forest.lua 32:

local survival_together = {
    id = "SURVIVAL_TOGETHER",
    location = "forest",
    required_setpieces = { "Sculptures_1", "Maxwell5" },
    numrandom_set_pieces = 4,
    random_set_pieces = { "Sculptures_2", ... "Warzone_3" }
}

map/tasks/ 33 — Node definitions for the generation graph (forest.lua, caves.lua, DLCtasks.lua, maxwell.lua, moonisland_tasks.lua, ruins.lua). Tasks use a lock/key constraint system to control which areas unlock which other areas. Example from forest.lua 34:

AddTask("Resource-rich Tier2", {
    locks = LOCKS.NONE,
    keys_given = {KEYS.PICKAXE, KEYS.AXE, KEYS.GRASS, KEYS.WOOD},
    room_choices = {
        ["Forest"] = function() return 1 + math.random(SIZE_VARIATION) end,
        ["Plain"] = function() return 1 + math.random(SIZE_VARIATION) end,
    },
    room_bg = WORLD_TILES.GRASS,
})

map/rooms/ 35 — Room content definitions organized by world type (forest/ with 25 files, cave/ with 16 files). Rooms define entity spawn probabilities for each biome type 36:

AddRoom("BGCrappyForest", {
    value = WORLD_TILES.FOREST,
    contents = {
        distributepercent = .6,
        distributeprefabs = {
            pighouse = 0.015, spiderden = 0.04, gravestone = 0.01, ...
        }
    }
})

map/static_layouts/ 37 — 240+ hand-crafted layout files for specific memorable locations: default_start.lua, chess_spot.lua, toadstool_arena.lua, teleportato_base_layout.lua, etc. These define exact entity placements for set pieces that appear every run.

screens/ — 64 files + redux/ (65 files) 38#

UI screen implementations composing multiple widget components into full-screen interfaces. Includes mainscreen.lua 39, lobbyscreen.lua, pausescreen.lua, optionsscreen.lua, mapscreen.lua, playerhud.lua, and specialized screens for minigames. The redux/ subdirectory (with a nested panels/ directory) contains modernized screen implementations following updated UI architecture patterns.

widgets/ — 184 files + redux/ (86 files) 40#

Reusable UI widget components that compose into screens. Includes foundational elements (button.lua, text.lua, image.lua), HUD elements (healthbadge.lua, hungerbadge.lua, sanitybadge.lua, inventorybar.lua), and interaction widgets (speechbubble.lua, nametagwidget.lua). The redux/ subdirectory (with nested worldsettings/) contains updated widget implementations.

languages/ — 15 files 41#

Localization system using .po format translation files covering Simplified Chinese, Traditional Chinese, French, German, Italian, Japanese, Korean, Polish, Brazilian Portuguese, Russian, and multiple Spanish variants. Also includes a .pot template and Lua language utilities.

scenarios/ — 50 files 42#

Scenario definitions covering chest loot tables, entity spawning configurations, and special game mode setups.

cameras/ 43#

Camera system with followcamera.lua — the main following camera controller managing movement and positioning.

nis/ 44#

Non-interactive sequences for in-game cinematics: maxwellintro.lua and xbnyn.lua.

tools/ and util/ 45 46#

tools/ contains 2 code-generation utility scripts. util/ contains 8 runtime helper modules covering emoji handling, hitbox utilities, profanity filtering, and save-data management.

Key Features#

1. Modular Component Design#

With 815+ components and 261 state graphs, the system enables highly flexible entity composition. 14 22 A campfire, a character, and a creature can share identical burnable 19 or health 15 components, while the combination of components attached to each entity defines its unique behavior profile. Components synchronize critical state to replica objects for seamless multiplayer operation.

2. Behavior Tree AI#

The 29 behavior node implementations in behaviours/ 26 compose into rich creature intelligence via 191 brain files 23. Rather than hard-coding creature AI, individual atomic behaviors (approach, flee, wander, attack) are combined in priority-ordered trees. Creature-specific tuning constants (distances, timings, search radii) in each brain file allow fine-grained adjustment without modifying the underlying behavior logic. The BrainWrangler in brain.lua 4 manages all active brains across hibernation and update states for performance.

3. Procedural World Generation#

The map/ system 30 uses a four-layer hierarchy — levels → tasks → rooms → static layouts — to produce varied yet structured worlds. Task nodes use a lock/key constraint graph 47 to ensure logical world progression; rooms use probability distributions to scatter entities; and 240+ static layouts 37 guarantee memorable hand-crafted locations (boss arenas, ruins, sculptures) appear in every run.

4. UI Modernization#

Both screens/ and widgets/ contain parallel redux/ subdirectories 38 40 reflecting an ongoing architectural migration toward an updated, state-managed UI pattern. The original and modernized implementations coexist, enabling incremental migration without breaking existing functionality.

5. Character-Specific Content#

Seventeen speech_*.lua files 48 49 50 provide each playable character with unique, contextual dialogue organized by action type (e.g., ACTIONFAIL.ACTIVATE.LOCKED_GATE). These files are generated from a batch toolchain (PropagateSpeech.bat via speech_tools.lua), ensuring consistency across character voice packs.

6. DLC Support Framework#

The map task system includes DLCtasks.lua 33, and the configuration layer in main.lua 2 and config.lua 10 includes explicit platform and DLC detection, making it straightforward to gate content behind expansion packs or platform capabilities.

7. Multi-Language Localization#

The languages/ directory 41 supports 15 locales using the industry-standard .po format, covering all major languages for DST's global player base. String tables are referenced throughout UI code to ensure every text element is localizable.

Entity Composition Pattern#

Entities in dst-scripts are not pre-defined monolithic objects — they are assembled dynamically at runtime from reusable pieces. The following steps describe how a full entity comes to life, from static file to live game object.

Step 1 — Prefab Definition#

A prefab file defines the entity template. At the top of each file, two static tables are declared:

• assets — external files the entity needs (animation banks, sound files, textures)
• prefabs — other prefab names this entity depends on (e.g., the loot it drops)

Then one or more factory functions are defined. For player characters, the shared factory is imported: 11

local MakePlayerCharacter = require("prefabs/player_common")

For creatures like the beefalo, a brain module is loaded and a loot table is registered: 12

local brain = require("brains/beefalobrain")
SetSharedLootTable('beefalo', { ... })

For tools, parameterized factories enable variant creation with minimal code duplication: 13

local function MakeAxe(name, common_postinit, master_postinit, data, _assets, _prefabs)

Step 2 — Component Attachment#

During the entity construction callback, components are dynamically attached using entity:AddComponent(). Each call adds a specific capability:

entity:AddComponent("health") -- hit points and damage (cite:code_file:5b9b099f)
entity:AddComponent("combat") -- fighting mechanics (cite:code_file:800c48e4)
entity:AddComponent("inventory") -- item storage (cite:code_file:4d770fc3)
entity:AddComponent("burnable") -- fire interaction (cite:code_file:1c00c8c6)
entity:AddComponent("workable") -- chop/mine actions (cite:code_file:60574071)
entity:AddComponent("equippable") -- wearable behavior (cite:code_file:b5396f8f)

Components are attached via common_postinit (runs on both client and server) and master_postinit (server-only) callbacks passed to the factory, keeping the server/client split clean. After attachment, each component may configure itself — for example, fueled sets its fuel types 18 and workable sets its maximum work value 20.

Step 3 — State Graph Assignment#

Visual and animation behavior is controlled by assigning a state graph:

entity:SetStateGraph("SGwilson")

The state graph (e.g., stategraphs/SGwilson.lua) manages the entity's animation state machine — transitioning between idle, walk, attack, death, and other states in response to game events. The shared commonstates.lua provides base states that most entities reuse. 22

Step 4 — Brain Installation#

For NPCs and creatures, an AI brain is installed:

entity:SetBrain(brain)

The brain (e.g., beefalobrain.lua 24) defines a behavior tree composed from the atomic nodes in behaviours/. The brain evaluates conditions each tick and executes the highest-priority applicable behavior. Configuration constants within the brain file tune the creature's awareness and response characteristics — for the beefalo, these include SEE_PLAYER_DIST = 5 and MAX_CHASE_TIME = 6 25.

Step 5 — Action Registration#

Finally, entities participate in the action system. Actions (defined in actions.lua 7) specify what interactions are possible — CHOP, MINE, ATTACK, EAT, PICKUP, DROP, etc. Components often register action handlers:

• A workable component with action CHOP means a player wielding an axe can chop that entity
• A combat component registers attack actions
• An edible component registers the EAT action

Range checks (MakeRangeCheckFn, DefaultRangeCheck) validate that the acting entity is close enough before the action executes 7.

Putting It Together#

This composition pattern allows arbitrarily complex entities to emerge from simple, individually testable pieces. A beefalo and a spider can share combat, health, and locomotor components, while differing entirely in their brain logic, state graph, loot table, and prefab assets. Adding a new entity type requires only writing a new prefab file and selecting which existing components to attach — no modification to any existing system is necessary.

Technical Details#

Runtime Design Patterns#

• Replica Synchronization — Components sync their authoritative server state to client-side replica objects (e.g., self.inst.replica.health), enabling lag-tolerant multiplayer without duplicating component logic
• Dynamic Tagging — Entities carry a mutable set of string tags managed by components; other systems query tags rather than inspecting component state directly, keeping coupling low
• World-State Subscriptions — EntityWatchWorldState() and ComponentWatchWorldState() 5 allow any entity or component to react to global state changes (day/night, season transitions, etc.) without polling
• Centralized Tuning — All balance-sensitive numbers live in the TUNING table in tuning.lua 9, making balance patches a single-file change
• Platform Abstraction — Platform detection helpers in main.lua 2 and the Config class in config.lua 10 encapsulate all platform-specific branches, keeping game logic platform-neutral