Modding:Understanding the VS Engine

This page was last verified for Vintage Story version 1.19.8.

In essence, the VS engine encompasses all code in VintageStoryLib.dll and VintageStoryApi.dll. To a degree the VSEssentials.dll mod could also be considered part of the VS engine as some it is quite integral to create meaningful gameplay.

Subsystems

As you might have read before, Vintage Story was built from the ground up with modding in mind and as such, the game content itself has been seperated into mods as far as possible. These are the essentials mod, the survival mod and the creative mod, all of which are under a readable source license on Github to help you learn by example.

As a modder, most of the time you will be interacting with the engine through an api object. It is passed along to your mod during initalization and is your gateway to adding new code content, rendering, hooking into various process of the game and networking.

Engine code

The VintageStoryLib.dll provides all code necessary to run a game client and a game server. The VintageStoryApi.dll provides interfaces and utilities and common objects to all mods. VintageStoryApi.dll is the one dll file all mods need a reference to.

Vanilla Mods

• The essentials mod provides entity AI, path finding, a number of creature behaviors, asset loading, the weather system, the worldmap system and other minor systems.
• The creative mod provides super flat world generation and creative mode tools.
• The survival mod provides most of the survial experience - over 140 different behaviors for blocks, knapping, clayforming, smithing, containers, character customization, the auction system, the cooking system, world generation, mechanical power and more.

Startup Sequence

When a player starts up single player, the game will first launch a server instance in a seperate thread, once it is ready it will launch a client instance and connect to the server using a fast connection through memory. The server intializes its own subsystem, loads the savegame and then mods, in a clearly defined order - the run phase.

Mods are loaded by searching the mod folder for mods that are correctly packaged, either compiles the .cs files or loads the .dll files and searches for all instances of ModSystem. These are then instantiated, sorted based on their ExecutorOrder, then the relevant Start*() methods are called. This happens twice - once on the server and once on the client.

When the server is ready and the client is ready to connect - the server will send a number of assets to the client. All blocks, items and entities (respective folders: blocktypes, itemtypes & entities) are only loaded server side and then sent to each client. Conversly the textures, shapes and sounds are (mostly) ignored by the server and only loaded on the client.

Game components

Blocks

See Modding:Block System

Networking

See Modding:Synchronization

Wondering where some links have gone?
The modding navbox is going through some changes! Check out Navigation Box Updates for more info and help finding specific pages.