This documentation consists of a descriptions of the game's internal logic. If you don't want to waste your time looking at decompiled code and thinking about it for hours, you are welcome.

It is, however, way be used as a more detailed wiki than the standard game's one.

• Unofficial Dig Or Die API documentation
  • CItemCell
    • Init
  • CBulletDesc
    • Constructor
    • m_isPhysical
  • SWorldDll
    • DllGetSaveOffset
    • ResetDll
  • CInventory
    • AddToInventory
    • InventorySorting
  • GBullets
    • CBulletDesc texture information
  • SNetworkCommands
    • ProcessCommand
  • CUnit
    • GetRand
    • Push
    • Update
  • CUnit.CDesc
    • Fields
  • SLoc
    • GetText
    • LoadLanguage
  • SLoc.CSentence
    • Constructors
    • GetText
  • SScreenHudChat
    • OnInit
  • CItem_MachineAutoBuilder
    • GetRecipes
  • SDataLua
    • GetDescList
    • GetDesc
    • ClearAllDescs
    • RegisterDesc
    • GetLuaPath
    • IsUserTable
    • OnInit
  • SDataLua.CDesc_ListOf1Type
    • Add
    • Clear
  • SMisc
    • GetRandomCorrected
    • GetIterators
  • CUnitMonster
    • UpdateTarget
  • CLifeConditions
    • CheckConditionsForPlant
  • CSurface
    • Constructor
    • SpTop
    • InitSprites
  • SUnits
    • OnUpdateSimu

When this.m_anchor == CItemCell.Anchor.Everywhere_Small, a sprite for the case when the object is not attached to anything, is created with this.m_tile.m_tileIndex.x + 1 (other arguments are passed unchanged).

The constructor accepts spriteTextureName and spriteName, and then creates sprite.

This internally uses the UnityEngine.Resources.LoadAll to load all sprites from $Textures/{spriteTextureName}. Each loaded sprite has it's name, which must match with the spriteName.

So, you need to patch the UnityEngine.Resources.LoadAll (with parameters of types string and Type) and return the array of Sprites if path is equals to $Textures/{spriteTextureName} with each name equal to their spriteName.

Not used anywhere in the game, possible scrapped prototype.

The liquid physics, force processing, electricity processing and lighting processing are happening inside DigOrDie.dll.

This file is located in <Dig or Die root>\DigOrDie_Data\Plugins\DigOrDie.dll and compiled and linked with Microsoft Visual C/C++ (2017, v15.9) (Information is obtained with Detect It Easy).

If you want to change the behavior related to the things listed above, you're out of luck. Or you need to modify DigOrDie.dll (which is directly the x86 machine code), or patch the wrappers around the DigOrDie.dll functions.

The DigOrDie.dll exports the following functions:

• DllSetCallbacks (accepts a callback for displaying debug information and a callback for calculating electricity production for specific cell)
• DllInit
• DllResetSimu
• DllClose
• DllGetSaveOffset
• GetBestSpawnPoint
• DllProcessElectricity
• DllProcessForces
• DllProcessLightingSquare
• DllProcessWaterMT

[DllImport("DigOrDie")]
private static extern int DllGetSaveOffset(int build, int x);

Computes a pseudo-random value between [0, 10] based on the x argument (when build >= 198). Note that the result 10 is only appears once for all x values at x = -1859131240.

Reverse engineered C code:

uint32_t DllGetSaveOffset(int32_t build, int32_t x) {
    if (build < 198) return 0;

    uint32_t hash = x * 0x9e3779b1U; // Golden Ratio's fractional part
    hash = ((hash >> 15) ^ hash) * 0x85ebca77U; // Some prime number
    hash = ((hash >> 13) ^ hash) * 0xc2b2ae3dU; // Some prime number too
    hash = (hash >> 16) ^ hash;

    // ensures that return value is between [0, 10]
    uint64_t product = (uint64_t)hash * 10ULL;
    return (uint32_t)(product / 0xFFFFFFFFULL);
}

The function is used in world data serialization/deserialization to create an offsets between cells that are in the same Y coordinate. I don't fully understand the reason for this function to exists, perhaps obfuscate the data layout and complicate the reverse engineering process?

Proof that the returned values are between [0, 10] using Z3 solver (and that 10 appears only once):

import z3

x = z3.BitVec("x", 32)

hashV = x * 0x9e3779b1
hashV = (z3.LShR(hashV, 15) ^ hashV) * 0x85ebca77
hashV = (z3.LShR(hashV, 13) ^ hashV) * 0xc2b2ae3d
hashV = z3.LShR(hashV, 16) ^ hashV

product = z3.ZeroExt(32, hashV) * 10
res = z3.Extract(31, 0, product / 0xFFFFFFFF)

z3.solve(z3.Not(
    z3.And(
        z3.UGE(res, 0), # res >= 0
        z3.ULE(res, 10) # res <= 10
    )))
# z3.solve(z3.And(res == 10, x != 2435836056))

internal void ResetDll(int2 gs);

Creates an array of int2 with size (SWorld.Gs.x - 8) * (SWorld.Gs.y - 8) and assigns it to m_gridOrder.
Populates the m_gridOrder with coordinates offsetted by 4 for each world's ends (e.g. for 1024x1024 world starts at (4,4) and ends at (1020,1020)).
Shuffles the m_gridOrder using Fisher–Yates shuffle algorithm.

public CStack AddToInventory(CItem item, int nb = 1, bool selectIt = false, bool addItToBarIFN = true);

If the player already has this item, adds to the number of this current item.

Otherwise, creates a new stack of items (CStack), append it to the list of the inventory items (m_items.Add), sort the list of the inventory items by item's id (m_items.Sort(new Comparison<CStack>(this.InventorySorting))).

private int InventorySorting(CStack a, CStack b);

Returns (int)(a.m_item.m_id - b.m_item.m_id).

Identical fields/properties.

internal void ProcessCommand(string input, CPlayer playerSender = null);

Parses input string and executes it as a command.

This function is executes on every client in the server with the same playerSender. If the command needs to be executed on only one client, it will be handled and filtered inside the function.

The chat history is also handled inside this function.

List of commands:

public float GetRand();

Returns m_rand. This value is always the same for each unit.

It is created for randomizing unit behavior and their animations for creating their uniqueness.

public virtual void Push(Vector2 force);

Pushes unit with force.

• If this is CUnitBird applies half (0.5) of the force.
• If this is CUnitBoss applies one tenth (0.1) of the force.
• If this is CUnitWall applies half (0.5) of the force.

internal virtual bool Update();

For every unit in the game the speed is clamped between -30 and 30 for X and Y axis.

The position is clamped between 0 and SWorld.GridRectM2.size.x for X and 0 and SWorld.GridRectM2.size.y for Y.

• public string m_codeName.
• public byte m_id.
• public int m_tier. Affects dropped blood tier, game tensions (SAudio.GetGameTension) and displays screen message for hitting >1 tier monster.
• public string m_locTextId.
• public float m_speedMax.
• public float m_hpMax.
• public int m_armor.
• public Vector2 m_size.
• public CTilesList m_anims.
• public Color24 m_emitLight = default(Color24). Light that unit will emit. Default is none.
• public float m_canDive.
• public bool m_immuneToFire.
• public bool m_skipColsOnPlatforms.
• public bool m_isSpawnPriority.

The class specialized for text handling for the entire game.

public static string GetText(string id, bool forceRegenDynamic = false, string arg1 = null, string arg2 = null, string arg3 = null, string arg4 = null);
public static string GetText(string id, bool forceRegenDynamic, float arg1, float arg2 = -3.4028235E+38f, float arg3 = -3.4028235E+38f, float arg4 = -3.4028235E+38f);

Tries to retrieve text from the ID-text pair dictionary (SSingleton<SLoc>.Inst.m_dico). If it is failed to find one, logs warning and returns "-" string.

Also caches any new combinations of text that is using arg1, arg2, arg3 and arg4 in the SSingleton<SResources>.Inst.m_dicoCachedTexts.

private void LoadLanguage(string language, bool isDefault);

Reads localization strings and populates them into internal dictionary.

Checks if there is localization file (path Application.streamingAssetsPath + "/localization/" + language + ".txt"); if not, logs error and returns. Parses entire localization file to the internal dictionary to store it's data.

Caches any dynamically generated strings in SResources.GetCachedTextLoc in the template form.

Class that stores text ID and it's template (or static text).

public CSentence(string id, string text);

Initializes class with id and text.

Replaces any \\n with \n.

If text contains character { it is considered dynamically generated, and it is depending on passed parameters. Caches template text string if it is generated.

public string GetText(bool forceRegenDynamic, string arg1 = null, string arg2 = null, string arg3 = null, string arg4 = null);
public string GetText(bool forceRegenDynamic, float arg1, float arg2 = 0f, float arg3 = 0f, float arg4 = 0f);

Retrieves localization string from cached dictionary, which depends on arg1, arg2, arg3 and arg4.

If the text is not generated (m_textGenerated == null) simply returns m_textStatic. Otherwise, uses SResources.GetCachedTextLoc to try getting cached text string depending on arg1, arg2, arg3 and arg4.

If forceRegenDynamic is true, will forcibly regenerate cached string (if it is cached) and ignore incomplete string generation (has leftover {).

protected override void OnInit();

Initializes m_txtChatLines with 15 CGuiText to display chat messages in the game. Sets m_isRichText to true for each CGuiText. Also initializes m_txtChatLinesTime with 15 float with the value float.MinValue.

Thus, in the game, can only be displayed maximum 15 lines of text in chat.

public List<CRecipe> GetRecipes();

Returns recipes that can be crafted using current autobuilder. This also initializes private field List<CRecipe> recipes.

Reads a list of CRecipesGroup from Lua variable with name list_recipesgroups.

public static List<T> GetDescList<T>(string id);

Returns a list of preinitialized descriptors with Lua variable name id.

public static T GetDesc<T>(string id) where T : CDesc;

Searches the current mode and its parent hierarchy for a descriptor of type T with the specified id and a matching mod name from the preinitialized list. Returns the descriptor if found; otherwise, returns null.

List of all available descriptors and their types that are defined in Lua scripts.

private void ClearAllDescs();

Iterates over this.m_descMainTypes and dynamically creates generic SDataLua.CDesc_ListOf1Type<> and calls static method .Clear().

private void RegisterDesc(CDesc desc);

Traverses the inheritance chain of the given type upward, dynamically creating generic SDataLua.CDesc_ListOf1Type<> with that deduced type and calling static method .Add(CDesc).

private string GetLuaPath(SDataLua.PathRoot pathRoot, SDataLua.Subpath subpath, string modName, string file = "?");

Returns a path to the Lua scripts location.

The default argument string file = "?" is used as Lua module resolution paths, so this placeholder will be used on require invocation.

private bool IsUserTable(DynValue value);

Checks if value is a table where all values are strings (DataType.String) or all are (DataType.UserData, type that represents custom .NET object).

protected override void OnInit();

Loads Lua descriptors for every available mod.

Preparation stage:

• Gathers all type in the current calling assembly:
  • If the type is a subclass of CDesc, register it in Lua (e.g. all subclasses of CDesc can be used in Lua scripts).
  • If .BaseType is CDesc, add it to this.m_descMainTypes list.
• Set up custom Lua converters for types:
  • int2. Impl: new int2((int)((double)dynVal.Table[1]), (int)((double)dynVal.Table[2]))).
  • IList<float>. Impl: dynVal.Table.Values.Convert(DataType.Table).
• Adds Lua functions:
  • int2 (SDataLua.LuaInt2(int x, int y)). Creates new instance of int2 vector with x and y arguments.
  • Create (SDataLua.LuaCreate(string className)). Create new instance of type with name className using parameterless constructor.
  • Clone (SDataLua.LuaClone(CDesc prototype)). Clones descriptor using MemberwiseClone().
  • Debug (SDataLua.LuaDebug(object prototype)). Prints object and it's type (or - if prototype is null).

Execution stage:

• Adds two module paths:
  1. Path to game's Mods folder that is located under DigOrDie_Data/StreamingAssets/Mods/{modName}/.
  2. Path to user's Mods folder that is located under Documents/Dig Or Die/<steam id>/Mods/{modName}/.
• Calls module with name main.
  • Note that if main.lua exists in both places, the first one executes, and the second one is ignore.
• Invokes string paramsDefault = Clone(params).
• Overwrites two module paths:
  1. Path to game's Params folder that is located under DigOrDie_Data/StreamingAssets/Params/{modName}/.
  2. Path to user's Params folder that is located under Documents/Dig Or Die/<steam id>/Params/{modName}/.
• Calls module with name params.
  • If that modules doesn't exists, does nothing.
  • Note that if params.lua exists in both places, the first one executes, and the second one is ignore.
• Copies every global value that is either DataType.UserData or satisfies SDataLua.IsUserTable in a new table.
• Cleans up (removes) every global value that appears in the new table.
• Assigns a new variable with the mod's name that has the value of the new table.
• Repeat for all available mod's (SOutgame.m_modNames, that contains a list { "Solo", "Multi", "SkyWorld", "UnderTheSea", "Defense" }).

Post execution stage:

• Calls method SDataLua.ClearAllDescs.
• For every mod:
  • Gets a table in the globals with mod's name.
  • Iterates that table and initializes and registers (SDataLua.RegisterDesc) the descriptors (CDesc).
• Gathers descriptors for Lua variable mod and places them into SOutgame.ModesList dictionary with mod's name as a key.
• Calls SDataLua.WriteDefaultParamsValues method for every mod name.
• Sets mode to Solo (SOutgame.SetModeIFN("Solo")).

private static class CDesc_ListOf1Type<T> where T : CDesc;

Purpose of this class is to store every instance of descriptor with type T gathered from executing every world's Lua config files.

See SDataLua.RegisterDesc and SDataLua.ClearAllDescs.

public static void Add(CDesc desc);

Adds desc as T to CDesc_ListOf1Type<T>.m_list, increments CDesc_ListOf1Type<T>.m_idNumMax and sets desc.m_idNum to new value of CDesc_ListOf1Type<T>.m_idNumMax.

public static void Clear();

Clears CDesc_ListOf1Type<T>.m_list and sets CDesc_ListOf1Type<T>.m_idNumMax to 0.

public static bool GetRandomCorrected(float chance, short id, CUnit attacker);

Computes a pseudo-random distribution of action succeeds while reducing extreme streaks of success or failure.

Instead of using raw randomness, it adjusts probabilities dynamically based on previous outcomes, making rare events more consistent and frequent events less streaky.

Used in monster loot dropping (CUnitMonster.GetRandomCorrected).

public static void GetIterators(int n, double t, double dt, float period, out int it0, out int itn);

Used to determine which and how much cells to process in the current simulation step, ensuring the game's grid is updated smoothly over time.
Another way to understand this function is that by iterating through the grid in smaller segments (defined by it0 for the starting point and itn for the number of cells to process) it ensures that every cell in the world is processed exactly once every period seconds.

protected virtual void UpdateTarget();

Targets player by factors like:

• Last time player made sound.
• Unit is locking at player's direction.

Other units in 4 cell radius around also targets player and this propagates further on other units and so on.

If there is an aggressive boss, units also starts to target player regardless of distance.

If the player is 18 cells away, the target is reset (if the unit is not night spawned).

public bool CheckConditionsForGrass(int i, int j);

Checks if the conditions are fulfilled for the grass to grow relative to the position of the mineral.

Grass can grow if the conditions below are all satisfied:

1. The cell above is passable (IsPassable()).
2. The cell altitude (j) is between m_altMin and m_altMax (inclusive).
3. The blue component of the light (m_light.b) in the cell above is between m_lightMin and m_lightMax (inclusive).
4. The water/lava in cell above is between m_waterAboveMin and m_waterAboveMax (inclusive).
5. The water/lava in cell is between m_waterInMineralMin and m_waterInMineralMax (inclusive).
6. The cell is not burning (CCell.Flag_IsBurning).

public bool CheckConditionsForPlant(int i, int j, CItem_Plant plant, bool checkLava = false);

Checks if the conditions are fulfilled for the plant to grow relative to the position of the mineral.

Plant can grow if the condition below are all satisfied:

1. The plant cell is empty or contain the same type of plant.
2. The mineral cell altitude (j) is between m_altMin and m_altMax (inclusive).
3. The blue component of light (m_light.b) in plant cell is between m_lightMin and m_lightMax (inclusive).
4. The water/lava in plant cell is between m_waterAboveMin and m_waterAboveMax (inclusive).
5. If checkLava is true, then plant cell must contain lava if m_isFireProof is true, otherwise, it must not.
6. The water/lava in mineral cell is between m_waterInMineralMin and m_waterInMineralMax (inclusive).
7. If mineral cell has grass, then m_grass must be true, else m_nograss must be true.
8. The mineral cell is not burning (CCell.Flag_IsBurning).

Class for storing sprites (UnityEngine.Sprite) for rendering cells tiles.

public CSurface(string surfaceTexture, int surfaceSortingOrder, int topTileI = -1, int topTileJ = -1, bool hasAltTop = false, CSurface surfaceGrass = null, CSurface surfaceGrassWet = null, bool isGrassWet = false);

Initializes a surface object with texture and rendering properties.

It loads materials for the main surface (material: Materials/SurfaceOpaque, texture: Textures/surfaces/{surfaceTexture}) and top borders (material: Materials/SurfaceBorders, texture: Textures/surfaces/_surface_tops), sets the sorting order, and configures optional grass/wet grass variants. When top tile coordinates are provided, it creates tile sprites for surface borders (main, left, right, and optional alternate top).

public Sprite SpTop{ get { ... } }

Lazily initialized property that provides the main top border sprite for the surface. If the sprite (m_spTop) hasn't been created yet, it triggers InitSprites(), which generates the sprite from a texture atlas using predefined coordinates and dimensions (96x64 pixels)

public void InitSprites();

Initializes the border sprites (m_spTop, m_spTopAlt, m_spTopL, m_spTopR) by slicing them from a shared texture atlas (Textures/surfaces/_surface_tops). It calculates their position based on m_topTileCoords, but for wet grass variant (isGrassWet) it grabs 512 pixels below. The main top sprite (m_spTop) uses a 96x64 region, while left/right borders (m_spTopL, m_spTopR) are 16x64. If m_hasAltTop is true, an alternate top sprite is also created that is 64 pixels below. All sprites use a pivot at the bottom center (for proper alignment) and a fixed pixels-per-unit (100).

protected override void OnUpdateSimu();

Simulation update method handling unit management, monster spawning, boss logic, and defense systems.

• Unit updates:

  • Iterates through all units and updating them, if the update was unsuccessful (e.g. dead, decomposed) removes those units
  • Counts alive monsters (CUnitMonster)
  • Detects active boss units (CUnitBoss) (aggressive/nearby states)
  • Removes player units (CUnitPlayer) if their associated network player left/disconnected

• Monster spawning:

  • Night/Rocket/Eclipse spawns: spawns monsters using formula: Gm_nightSpawnFrequency[difficulty] * deltaTime * paramsMult * playerCountMult* environmentMult (attempts up to 10 spawns per frame when accumulatedspawn)
  • Day spawns: maintains minimum monster count per player with cooldown
  • Handles both normal and "creative spawn" monsters differently

• Boss management:

  • Ensures at least 1 living boss per type exists in world/kill records
  • Kills duplicates furthest from home zone
  • Respawns bosses (CUnitBoss) after m_bossRespawnDelay seconds

• Defense units:

  • Removes defense units (CUnitDefense) when corresponding grid item on the same cellmissing (CItem_Defense)
  • Removes defense units (CUnitDefense) when players is not around them (exceptm_neverUnspawn defenses)

• Cleanup:

  • Removes null unit references and units with invalid id (whenm_unitsById returns null).
  • Sends updated unit position to the network