Introduction

The Dehoarder 2 Extensible Mod System (Mod System) is built to support flexibility in reconfiguring the Dehoarder 2 Game. It is the ultimate in high-tech game modding design. Ok, maybe not truly "The Ultimate", but definitely penultimate or at least penultimate adjacent.

Using the Mod System requires the use of the Unity Editor to build Addressable Asset Bundles, which are in turn deployed as Modules (Mods) that are loaded by the Dehoarder 2 Engine at runtime.

The core game itself has been implemented as a Mod that other Mods will depend on.

It is intended that eventually every non-engine asset of the game will be able to be replaced using the Mod System.

The Mod System supports extending the Dehoarder 2 Game Database by using Lua scripting to allow addition of new database entries or modification of existing database

The Mod System supports using Lua Scripting to control the game during runtime. Creators can author StoryEvent scripts that get triggered by certain conditions, such as the player interacting with objects, a certain amount of game time passing, collisions occurring, and so forth.

Intended Audience and Prerequisite Knowlege

This documentation is intended for game modders that seek to extend the Dehoarder 2 gaming experience for themselves and others. Players who simply want to enjoy the game need not read this document to understand and consume the game, but can peruse this documentation if they want to explore "how the sausage is made."

The Mod System extensively utilizes Unity 3D and Lua scripting, and thus beyond the end of this section it is assumed that the intrepid modder has already prepared themselves with the necessary base skills in these technologies.

Specifically within Unity 3D, it would be beneficial to have an understanding of Unity's Addressables technology, as that drives the core of how Mod assets are built, stored and loaded. Other Unity-specific knowledge required depends largely on the types of assets you would like to include with your mods. You would obviously need different skillsets for working with 3D models in Unity than you would for sound effects.

Specifically within Lua, it would be beneficial to understand the require facility, as it drives the multipass loading capability of database building. A little understanding of the coroutine facility is optional but potentially helpful for grokking how time delays in Story Event scripts work under the covers. Beyond those two concepts, just a general grounding in basic Lua scripting is all that should be needed. I've tried to keep the Lua coding as simple as possible and hide as many of the complexities as possible.

A little bit of general understanding about Game Design and Game Programming is always helpful with any game modding endeavor.

Is your Sword of Knowledge nice and sharpened on the above whetstones? Good. Here is your Dehoarder 2 Modders' Guild Novice badge. You are ready to proceed.

Core Concepts

Before diving deeper, it may be helpful to be familiarize yourself with a high-level overview of some of the core concepts that will be discussed throughout the documentation.

Module (Mod)

A module is a collection of Assets, potentially including Database Build Scripts and StoryEvent Scripts, packaged as a Unity Addressable AssetBundle and containing a valid metadata file at a well-known Address describing the mod.

See Creating Mods using Unity for more detailed information.

Object Model Basics

The Dehoarder 2 Object Model is roughly split into two domains - the static database entities in the Dehoarder 2 Database Model (SmilingCat.Dehoarder2.Data), and the dynamic game state entities in the Dehoarder 2 Game Object Model (SmilingCat.Dehoarder2.Game). There is some shared DNA between the two domains; SmilingCat.Builder contains the really basic stuff that I can probably reuse on future games.

See Object Model Basics for more detailed information.

Dehoarder 2 Database Model

The Dehoarder 2 Database Model (SmilingCat.Dehoarder2.Data) contains all static data that is defined when the game is loaded and cannot be changed during gameplay. This is where the definitions for things like Junk items and Furnishings are defined.

See Dehoarder 2 Database Model for more detailed information.

Database Building Phase

A Database Building Phase occurs upon each transition to a scene that contains a DatabaseManager component (later this may be optimized to run the Database Building Phase only on initial startup or when loaded Mods change). During this phase, each loaded Mod will get one or more opportunities to create or replace entities in the database. This is the only time at which the database can be modified. Once the Database Building Phase concludes and the Database is built, all information in the database is read-only and cannot be modified.

See Database Building Phase for more detailed information.

Database Build Scripts

Database build scripts are responsible for adding entities to the database during the Database Building Phase. Each Mod's Database Build Scripts are run multiple times in round-robin fashion until an entire pass through all modules occurs in which no Database Entities are added or modified.

See Database Build Scripts for more detailed information.

Dehoarder 2 Game Model

The Dehoarder 2 Game Model (SmilingCat.Dehoarder2.Game) contains all of the dynamic game state data. This contains the classes necessary to define an instance of the game world, including instances of all of the objects contained in it.

See Dehoarder 2 Game Model for more detailed information.

Story Event Scripts

Story Event Scripts provide the means for the Mod system to control the game's behavior. Story Events can be linked to a number of different in-game events and conditions.

See Story Event Scripts for more detailed information.

Asset Repository

The Asset Repository controls access to system-level resources contained in Modules, such as Textures, Materials, Sounds, Text Files, and Prefabs. Scripts do not directly access the Asset Repository, and instead provide Keys containing Addresses pointing to Assets.

See Asset Repository for more detailed information.

Localization System

The Localization System translates Keys referring to text into translated display text, and formatting information for display to the player. All textual information to be displayed to the player should flow through the Localization System. Since scripts do not output text to the player but instead refers to text using Keys, scripts do not directly use the Localization System.

See Localization System for more detailed information.

Scripting Console

Dehoarder 2 has a built-in scripting console that can be opened using the Toggle Console keybind, which is F11 by default. The console shows as color-coded output any Unity Console messages generated through the Unity Debug object, as well as messages from any print statements run by Lua scripts. The console takes as input a typed/pasted Lua script, and runs it in a context similar to a StoryEvent.

See Scripting Console for more detailed information.

Task-Specific Guides

Beyond the guides for setting up and running a Modding project, This documentation also provides step-by-step guides for a growing number of modding tasks.

See How Do I for more detailed information.