Modding:WorldGen Concept: Difference between revisions

From Vintage Story Wiki
No edit summary
Line 13: Line 13:
World generation is very modular. Almost all generated parts of the world, such as ore deposits, creatures or trees, are specified via JSON content mods. On a coding level, each stage of generation triggers an event which the base game registers handlers to. Event handlers can be registered or removed through the API to alter any part of generation.
World generation is very modular. Almost all generated parts of the world, such as ore deposits, creatures or trees, are specified via JSON content mods. On a coding level, each stage of generation triggers an event which the base game registers handlers to. Event handlers can be registered or removed through the API to alter any part of generation.
== Content modding ==
== Content modding ==
Using content modding, here are the various things that can be added, modified or removed:
Using content modding, here are the various things that can be added, modified or removed. Properties relative to world generation can generally be found under ''Vintagestory/assets/survival/worldgen''
* Ore deposits
{| class="wikitable"
* Structures  
|-
* Trees
! Item !! Description
* Block layers
|-
* Block patches
| Deposits || Anything that is "deposited" in the ground on generation, such as ores or patches of blocks like gravel and chalk
* Geological provinces
|-
* Landforms
| Structures || Pre-defined structures, such as the ruins found throughout
* Villages
|-
| Trees || Tree and shrub placement
|-
| Block layers || Layers of blocks found above the rock layer
|-
| Block patches || Patches of blocks, also vegetation
|-
| Geological provinces || Geological attributes and placement
|-
| Landforms || Land layout and the general arrangement of terrain
|}


== Code modding ==
== Code modding ==

Revision as of 13:31, 15 July 2020

Intro

This article introduces how world generation is handled in Vintage story, and the extent to which it can be modded. It is also intended as a general introduction for modding endeavors in regards to world generation.

This page was last verified for Vintage Story version 1.12.4.

Terminology

Important terminology to note while reading this article:

  • Chunk (An area of 32x32x32 blocks. It is of note that chunks do not span the world height.)
  • Chunk column (A set of chunks spanning the vertical height of the world. Given a world height of 256, a chunk column would represent 8 vertically stacked chunks)
  • Map chunk (The area covered by a chunk column, but not referring to the chunks therein)
  • Region (The area covered by 16x16 chunk columns)

Concept

World generation is the process of generating necessary data about the world when the player requires it. World generation is done on a region, map chunk and chunk column basis - each acting as a meaningful subdivision of the world. Each region, map chunk and chunk column is only generated once and stores important data about that area. World generation is very modular. Almost all generated parts of the world, such as ore deposits, creatures or trees, are specified via JSON content mods. On a coding level, each stage of generation triggers an event which the base game registers handlers to. Event handlers can be registered or removed through the API to alter any part of generation.

Content modding

Using content modding, here are the various things that can be added, modified or removed. Properties relative to world generation can generally be found under Vintagestory/assets/survival/worldgen

Item Description
Deposits Anything that is "deposited" in the ground on generation, such as ores or patches of blocks like gravel and chalk
Structures Pre-defined structures, such as the ruins found throughout
Trees Tree and shrub placement
Block layers Layers of blocks found above the rock layer
Block patches Patches of blocks, also vegetation
Geological provinces Geological attributes and placement
Landforms Land layout and the general arrangement of terrain

Code modding

Using code modding, it is possible to remove any specific part of world generation from the base game entirely, as well as add new functionality.

World types

There are currently three world types - "standard", "superflat", "empty". World types exist under EnumWorldGenPreset. World type has to be specified when registering event handlers for world generation.

Passes

The chunk column generation event is additionally subdivided into passes. Passes are essentially layers in the generation of a chunk column - first laying down the rock layer in one pass, and doing more general cross-chunk actions in later passes, such as flooding them with light or growing patches of grass. Passes exist under EnumWorldGenPass. The pass has to be specified when registering event handlers for chunk column generation.

Index Name Description Requires neighbor chunks
0 None Nothing generated yet false
1 Terrain Basic terrain, rock strata, caves, block layers false
2 TerrainFeatures Deposits, structures, ponds true
3 Vegetation Block patches, shrubbery and trees, rivulets, sunlight flooding in chunk true
4 NeighborSunLightFlood Snow layer, sunlight flooding to nearby chunks true
5 PreDone Done generating, spawn creatures, neighbor chunks might still generate additional things true
6 Done Pass is not triggered as an event -

Events

The generation of either a region (IMapRegion), map chunk (IMapChunk), or chunks contained in that chunk column (IServerChunk and IWorldChunk), triggers an event (in that order). Each of these interfaces holds some specific data about the given region. It is possible to register handlers to events, wherein access is provided for the given interface. The order in which the handlers are assigned is based on the execute order of their specific mod systems.

Accessing events

class Mod : ModSystem
{
    public override double ExecuteOrder()
    {
        // Make sure all delegates have been assigned
        return 10;
    }

    public override void StartServerSide(ICoreServerAPI api)
    {
        // Get the handler for interacting with world generation.
        IWorldGenHandler handler = api.Event.GetRegisteredWorldGenHandlers("standard");

        // Example registering events using a delegate.
        api.Event.ChunkColumnGeneration(/* Handler here */, EnumWorldGenPass.None, "standard");
        api.Event.MapChunkGeneration(/* Handler here */, "standard");
        api.Event.MapRegionGeneration(/* Handler here */, "standard");

        // Retrieving registered handlers.
        List<MapChunkGeneratorDelegate> onMapChunkGen = handler.OnMapChunkGen;
        List<ChunkColumnGenerationDelegate>[] onChunkColGen = handler.OnChunkColumnGen;
        List<MapRegionGeneratorDelegate> onMapRegionGen = handler.OnMapRegionGen;

        foreach (var deleg in onMapChunkGen)
        {
            // Printing class name of delegate instance.
            // This can be useful for finding and removing any particular event from the list.
            api.Server.LogEvent(deleg.Target.ToString());
        }
    } 
}
Icon Sign.png

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.