Skip to content
VSPT

Updating your mod to 1.23

A guide for mod developers moving a mod from Vintage Story 1.22.7 to 1.23.0-pre.1: what changed in the API, the base game mods, the engine, the game’s content, its shaders and its bundled libraries, and what to do about each. It was made by comparing the two versions in full: Anego Studios’ public source for the API and the base game mods, a decompile of both engines with the same tool, every type and member of every game assembly, and every game file. We made it while moving our own mod, VSPT, and publish it in case it saves you the same work.

1.23.0-pre.1 is a preview. Anego says API changes may still be adjusted before the stable release, and new world generation is promised for a later preview. This guide describes pre.1 as released on 2026-11-19 and will be updated for later previews. It is not from Anego Studios; where it reports behaviour read from the source rather than seen in the game, it says so.

  1. Rebuild against 1.23. Point your project at a 1.23 install and build. The target framework has not changed (net10.0, .NET 10.0.0), but a mod built against 1.22.7 should not be shipped for 1.23 as it is: fields became properties and signatures changed, which only a rebuild finds, and some old overrides are silently no longer called.
  2. Fix what fails to compile with the API and base game mods. Its “Most likely to break your mod” list is the fastest start.
  3. Clear the new [Obsolete] warnings. Several are errors now (the old FromBytes(BinaryReader), for one); the rest say what to use instead.
  4. If you Harmony-patch or reflect into the engine (VintagestoryLib), go through the engine: 286 of its 1,010 source files changed, and patches that name a method without its argument types may now match an overload.
  5. If your mod has JSON assets or patches the game’s, go through content, shaders and libraries: codes were renamed, files moved, entity settings moved into behaviorConfigs, and willow joined the wood types.
  6. Test in a new 1.23 world and in a world made in 1.22. Old worlds are migrated on first load: their worldgen seed moves to the new SeedWorldgen, and World.Seed gets a new random value.
1.22.7 to 1.23.0-pre.1
VintagestoryAPI 93 public types added, 2 removed, 7 changed; 359 public members added, 42 removed, 230 changed
VSEssentials 192 public types added, 3 removed; 160 public members added, 40 removed, 90 changed
VSSurvivalMod 100 public types added, 6 removed; 539 public members added, 124 removed, 184 changed
VSCreativeMod 25 public types added
The engine (VintagestoryLib) 286 of 1,010 decompiled files changed; 27 types added and 11 removed; 534 members added, 164 removed, 131 changed
Game files 3,527 added, 134 removed, 86 renamed or moved, 2,983 changed
Codes Blocks 14,089 to 14,990, items 4,469 to 5,155, entities 820 to 930; 58 codes gone, 51 of them with an official remap
Bundled libraries ICSharpCode.SharpZipLib no longer ships; Microsoft.Data.Sqlite, SQLitePCLRaw, System.Drawing.Common and Microsoft.Win32.SystemEvents updated; 0Harmony still 2.4.2.0
Shaders 8 changed, 1 include added (oit.ash), none removed
Runtime Unchanged: net10.0
Signing The Windows DLLs and executables are now Authenticode-signed by Anego Studios

From the API and the base game mods (details):

Change What to do
Packet handlers on BlockEntity, BlockEntityBehavior, Entity and EntityBehavior have new SerializedData overloads, which the game calls first; the client ones take ref CachedAccessPerms. EntityBehavior.OnReceivedServerPacket(int, byte[], ref EnumHandling) is no longer called Override the new overloads
Binary serialisation: FromBytes(BinaryReader) became FromBytes(ref BinarySpanReader) throughout; the old overload is an [Obsolete] error Move your overrides to the span reader
AnimationManager and PlayerAnimationManager take the entity in their constructors Pass the entity
World generation uses the new server-only SeedWorldgen; World.Seed no longer has anything to do with terrain Seed your generators from SeedWorldgen
BlockSchematic.Place and its relatives take a SchematicPlacementData Build one
Recipe registries became custom registries (RegisterCustomRegistry, GetCustomRegistry, CustomRegistryBase) Register through the new calls
Several NatFloat fields became INatFloat, and some load as shared instances Do not cast to NatFloat; do not mutate them
Armour: ProtectionModifiers lost its flat, relative and tier fields for ProtectionTiers; old-format armour JSON silently protects nothing Move to ProtectionTiers
IWorldChunk.BlockEntities is keyed by a chunk-local int index, not a BlockPos Index it by the chunk-local index
Melee hits use the item’s damage type (default SlashingAttack); every hit was BluntAttack before Set your weapons’ damage type

From the engine, for mods that Harmony-patch or reflect into VintagestoryLib (details):

Change What to do
Window size and framebuffer size are kept apart: ClientMain.Width/Height and IRenderAPI.FrameWidth/FrameHeight are framebuffer pixels, the DPI scale is folded into RuntimeEnv.GUIScale, and many methods read FramebufferSize where they read ClientSize Recheck anything that sizes in pixels, and transpilers anchored on ClientSize
WorldChunk.BlockEntities went from a BlockPos-keyed field to an int-keyed property Rebuild; index by the chunk-local index
Mod loading: ModContainer is made through a factory, LoadMods takes the side, content mods for the wrong side are disabled, and SharpZipLib is gone Retarget patches on mod loading; ship SharpZipLib yourself if you use it
The network transport and server sends were rewritten: messages are structs, broadcasts take spans, a null in a skip list throws Retarget packet patches by full signature
Terrain comes from SeedWorldgen, migrated once from a 1.22 world’s seed, and never sent to clients Do not derive terrain from World.Seed
Hotbar slots: the skill slot is −1, the off-hand −2, the backpack starts at 10 Recheck code that numbers slots
OnTrySpawnEntity runs on the spawner thread; OnTrySpawnGroupNearOffthread is gone Make spawn handlers thread-safe
Transparency (OIT) was rewritten, the selection outline draws at AfterOIT, atlas textures can be freed at run time, and chunk tesselations carry ids that discard stale uploads Retarget rendering patches; do not hold atlas positions across a release

From the content (details):

Change What to do
69 of the 90 entity files keep diets, AI tasks, drops, breeding and growth in behaviorConfigs Patches on /server/behaviors/<n>/... miss: patch behaviorConfigs
Codes renamed: the bronze falx is the kopis, anvil-<metal> is anvil-singlehorn-<metal>, aged polished rock cobbled is tile, largegear3 is largegear3-u, semitameddeer is tameddeer. The remaps fix saved worlds, not your JSON Update your codes
Willow joined the block/wood world property Types that take their variants from it gain a willow variant that needs textures
Smithing recipes have an anvil type, single-horn by default; the new weapons are beak-horn only Set the anvil type where it matters
Files moved: mammal creature items to creature-mammal.json, metal parts from itemtypes/resource/ to itemtypes/part/, the blades file split Retarget your patches
109 English lang keys removed or renamed; Bulgarian dropped Update your lang references
Page For
The API and the base game mods C# code mods: every binary-breaking change, by area, with what to use instead; behaviour changes; new API; everything newly obsolete; every changed public member in an appendix
The engine Mods that Harmony-patch, reflect into or call VintagestoryLib: changes by engine system, with short decompiled excerpts, and every changed engine member in an appendix
Content, shaders and libraries JSON content mods, patches, shader mods, and code mods that use bundled libraries: codes, remaps, moved files, JSON format changes, shader changes, appendices of every code, file, lang key and JSON property that changed
Part Compared
The API and the base game mods Anego Studios’ public repositories vsapi, vsessentialsmod, vssurvivalmod and vscreativemod, at their “Updated to Version 1.22.7” and “Updated to Version 1.23.0-pre.1” commits
Every assembly Every type and member of VintagestoryAPI, VintagestoryLib, Vintagestory, VintagestoryServer, VSEssentials, VSSurvivalMod and VSCreativeMod, read from their metadata with full signatures, access and [Obsolete] messages, and diffed
The engine Both versions’ VintagestoryLib.dll decompiled with ilspycmd 9.1 with the same options, and diffed
The game files Both versions unpacked from Anego’s own Windows installers and compared file by file; textures by their decoded pixels; codes worked out the way the game’s loader does

The 1.23 announcement: the blog post and Anego’s page for 1.23. The official wiki’s page on modding API updates stops at 1.22 as this is written.